Variables representing time must always explicitly include
units attribute; there is no default value.
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
The most commonly used of these strings (and their abbreviations)
hour (hr, h),
minute (min) and
second (sec, s).
Plural forms are also acceptable. The reference time string
(appearing after the identifier
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
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
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
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
Mixed Gregorian/Julian calendar as defined by Udunits. This is the default.
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.
Gregorian calendar without leap years, i.e., all years are 365 days long.
Gregorian calendar with every year being a leap year, i.e., all years are 366 days long.
All years are 360 days divided into 30 day months.
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:
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:
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.
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.
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_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.