This appendix describes the treatment of leap seconds in CF in more detail than [calendar], and provides guidance for writers of datasets about the choice of a suitable CF calendar. Because precision to the second has rarely been needed in the climate and forecast community, leap seconds have typically been ignored, including in many datasets and versions of the CF conventions before 1.12.
In CF 1.13 and later, in all calendars except the utc calendar,
-
any datetime with seconds equal to or greater than 60 is invalid and must not appear as the reference datetime in the
unitsattribute, and -
the difference is always 60 seconds between the time coordinates for the start of consecutive minutes.
If you are producing model-generated datasets with datetimes that follow the Gregorian calendar, the proleptic_gregorian calendar is recommended, because it unequivocally indicates to the user of the dataset that leap seconds are not included in the timeline (it is assumed that this is true for model data).
On these grounds, it is preferable to the standard calendar, which is ambiguous in CF versions before 1.13 about the inclusion of leap seconds (see below).
If you are producing real-world datasets with datetimes in UTC, and if it’s important for the datetimes and time intervals to be accurate to the second, the utc calendar is recommended.
When a datetime is converted to a time coordinate or vice-versa in the utc calendar, any leap seconds must be counted that occurred between the instant concerned and the reference datetime in the units attribute.
Therefore both the writer and the user of the dataset will need software that has access to a list of dates (such as Leap_Second.dat from IERS) on which leap seconds were inserted.
If you are producing real-world datasets with datetimes in UTC but do not expect all users of your datasets to have such software, the standard calendar is recommended.
For real-world data since 1972, time coordinates in the standard calendar must be calculated:
-
from datetimes in UTC or a local time zone offset from UTC,
-
as if there were no leap seconds (i.e. assuming 60 seconds elapsed between the start of each minute and the next).
This practice enables the user of the dataset to recover UTC datetimes from the time coordinates without any information about when leap seconds were inserted. It has the following consequences:
-
Datetimes within leap seconds cannot be converted to time coordinates.
-
The difference between two time coordinates will differ from the duration of the time interval between the two instants by the net number of leap seconds that occurred between them.
The differences between the utc and standard calendars are illustrated with examples related to the leap second that was added to UTC at the end of 2016.
If calendar="utc" and units="seconds since 2016-12-31 23:59:58", a value of 4 for the time coordinate represents the datetime 2017-01-01 00:00:01, because four seconds had elapsed by that instant since 2016-12-31 23:59:58 (seconds ending at 2016-12-31 23:59:59, 2016-12-31 23:59:60, 2017-01-01 00:00:00, 2017-01-01 00:00:01).
If calendar="standard", with the same units="seconds since 2016-12-31 23:59:58", the datetime 2017-01-01 00:00:01 is represented by a time coordinate of 3, because the UTC leap second (from 2016-12-31 23:59:60 to 2017-01-01 00:00:00) is ignored when calculating time coordinates in the standard calendar .
In the utc calendar, the elapsed time between the same time of day on consecutive days is normally 86400 seconds, but increases to 86401 seconds when a positive leap second intervenes.
For example, with respect to the the reference datetime in units="seconds since 2016-12-31 23:59:58", the datetime 2017-01-01 23:59:58, which is one calendar day later, is represented by a time coordinate of 86401.
In the standard calendar, with the same units, the time coordinate for 2017-01-01 23:59:58 is 86400.
In datasets written with CF versions before 1.13, the standard calendar has been used both for real-world data, and for data generated by models that follow the Gregorian calendar and do not include leap seconds in the timeline.
Moreover, time coordinates in some real-world datasets take leap seconds into account, and others do not.
As a consequence of such differences, users of real-world data in the standard calendar need to be aware that the time coordinates for the same real-world instant in two datasets, both using the standard calendar, could disagree by some number of seconds.
CF version 1.12 introduced possible values of the form "leap_seconds: value" for the units_metadata attribute, in order to specify the treatment of leap seconds in the standard, julian and proleptic_gregorian calendars.
CF version 1.13 withdrew this use of units_metadata, in favour of the recommendations given above regarding choice of calendar.