Variables representing time must always explicitly include
the units
attribute; there is no default value.
The units
attribute takes a string value formatted
as per the recommendations in the Udunits package [UDUNITS].
The following excerpt from the Udunits documentation explains the time unit encoding by example:
The specification: seconds since 1992-10-8 15:15:42.5 -6:00 indicates seconds since October 8th, 1992 at 3 hours, 15 minutes and 42.5 seconds in the afternoon in the time zone which is six hours to the west of Coordinated Universal Time (i.e. Mountain Daylight Time). The time zone specification can also be written without a colon using one or two-digits (indicating hours) or three or four digits (indicating hours and minutes).
The acceptable units for time are listed in the
udunits.dat
file.
The most commonly used of these strings (and their abbreviations)
includes day (d)
, hour (hr, h)
,
minute (min)
and second (sec, s)
.
Plural forms are also acceptable. The reference time string
(appearing after the identifier since
) may
include date alone; date and time; or date, time, and time zone.
The reference time is required. A reference time in year 0 has a
special meaning (see Section 7.4, “Climatological Statistics”).
Note: if the time zone is omitted the default is UTC, and if both time and time zone are omitted the default is 00:00:00 UTC.
We recommend that the unit year
be used with caution. The Udunits package defines a year
to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. Udunits includes the following definitions for years: a common_year
is 365 days, a leap_year
is 366 days, a Julian_year
is 365.25 days, and a Gregorian_year
is 365.2425 days.
For similar reasons the unit month
, which is defined in
udunits.dat
to be exactly year/12
, should also be used with caution.
Example 4.4. Time axis
double time(time) ; time:long_name = "time" ; time:units = "days since 1990-1-1 0:0:0" ;
A time coordinate is identifiable from its units string alone. The Udunits routines utScan()
and utIsTime()
can be used to make this determination.
Optionally, the time coordinate may be indicated additionally by providing the standard_name
attribute with an appropriate value, and/or the axis
attribute with the value T
.
In order to calculate a new date and time given a base date, base time and a time increment one must know what calendar to use. For this purpose we recommend that the calendar be specified by the attribute calendar
which is assigned to the time coordinate variable. The values currently defined for calendar
are:
gregorian
or standard
Mixed Gregorian/Julian calendar as defined by Udunits. This is the default.
proleptic_gregorian
A Gregorian calendar extended to dates before 1582-10-15. That is, a year is a leap year if either (i) it is divisible by 4 but not by 100 or (ii) it is divisible by 400.
noleap
or 365_day
Gregorian calendar without leap years, i.e., all years are 365 days long.
all_leap
or 366_day
Gregorian calendar with every year being a leap year, i.e., all years are 366 days long.
360_day
All years are 360 days divided into 30 day months.
julian
Julian calendar.
none
No calendar.
The calendar
attribute may be set to none
in climate experiments that simulate a fixed time of year. The time of year is indicated by the date in the reference time of the units
attribute. The time coordinate that might apply in a perpetual July experiment are given in the following example.
Example 4.5. Perpetual time axis
variables: double time(time) ; time:long_name = "time" ; time:units = "days since 1-7-15 0:0:0" ; time:calendar = "none" ; data: time = 0., 1., 2., ...;
Here, all days simulate the conditions of 15th July, so it does not make sense to give them different dates. The time coordinates are interpreted as 0, 1, 2, etc. days since the start of the experiment.
If none of the calendars defined above applies (e.g., calendars appropriate to a different paleoclimate era), a non-standard calendar can be defined. The lengths of each month are explicitly defined with the month_lengths
attribute of the time axis:
month_lengths
A vector of size 12, specifying the number of days in the months from January to December (in a non-leap year).
If leap years are included, then two other attributes of the time axis should also be defined:
leap_year
An example of a leap year. It is assumed that all years that differ from this year by a multiple of four are also leap years. If this attribute is absent, it is assumed there are no leap years.
leap_month
A value in the range 1-12, specifying which month is lengthened by a day in leap years (1=January). If this attribute is not present, February (2) is assumed. This attribute is ignored if leap_year
is not specified.
The calendar
attribute is not required when a non-standard calendar is being used. It is sufficient to define the calendar using the month_lengths
attribute, along with leap_year
, and leap_month
as appropriate. However, the calendar
attribute is allowed to take non-standard values and in that case defining the non-standard calendar using the appropriate attributes is required.
Example 4.6. Paleoclimate time axis
double time(time) ; time:long_name = "time" ; time:units = "days since 1-1-1 0:0:0" ; time:calendar = "126 kyr B.P." ; time:month_lengths = 34, 31, 32, 30, 29, 27, 28, 28, 28, 32, 32, 34 ;
The mixed Gregorian/Julian calendar used by Udunits is explained in the following excerpt from the udunits(3) man page:
The udunits(3) package uses a mixed Gregorian/Julian calen- dar system. Dates prior to 1582-10-15 are assumed to use the Julian calendar, which was introduced by Julius Caesar in 46 BCE and is based on a year that is exactly 365.25 days long. Dates on and after 1582-10-15 are assumed to use the Gregorian calendar, which was introduced on that date and is based on a year that is exactly 365.2425 days long. (A year is actually approximately 365.242198781 days long.) Seem- ingly strange behavior of the udunits(3) package can result if a user-given time interval includes the changeover date. For example, utCalendar() and utInvCalendar() can be used to show that 1582-10-15 *preceded* 1582-10-14 by 9 days.
Due to problems caused by the discontinuity in the default mixed Gregorian/Julian calendar, we strongly recommend that this calendar should only be used when the time coordinate does not cross the discontinuity. For time coordinates that do cross the discontinuity the proleptic_gregorian
calendar should be used instead.