Translates numeric time coordinates to calendar times.
Available in version 5.2.0 and later.
load "$NCARG_ROOT/lib/ncarg/nclscripts/contrib/calendar_decode2.ncl" function calendar_decode2 ( time : numeric, option  : integer )
An array of numeric time coordinates in one of the supported calendar systems. See dimension restrictions below.
time@units = Udunits-style time reference string, scalar. E.g. "days since 1800-1-1 00:00:00". The attribute name "units" must be lowercase. The string value is case insensitive. The units attribute is required.
time@calendar = name of calendar system, string scalar. E.g. "gregorian". The attribute name "calendar" must be lowercase. The string value is case insensitive. The calendar attribute is optional. If missing, Gregorian is implied.option
A scalar integer indicating the format of the output. See description below.
An array of translated date and time values equivalent to the input time coordinates. The format of the output array is selected by the option parameter.
option = 0 or -5: The result array will be of type float (option 0) or integer (option -5), with one added dimension on the right:
result(:,0) --> years
result(:,1) --> months
result(:,2) --> days
result(:,3) --> hours
result(:,4) --> minutes
result(:,5) --> seconds
Other options: The result array will have the same dimensions as the input array. For a description of the other formats, see the documentation for ut_calendar.
The COARDS convention is also supported, as it uses the Gregorian calendar by default. This is the definitive reference for CF-1:
Supported calendar systems:
- gregorian or standard
- Mixed Gregorian/Julian calendar as defined by UDUNITS. This is
the default when the "calendar" attribute is missing. See caution
- Gregorian calendar extended to dates before 1582-10-15.
- noleap or 365_day
- Gregorian calendar with no leap years. Every year has 365 days.
- all_leap or 366_day
- Gregorian calendar with every year being a leap year. Every
year has 366 days.
- All years are 360 days divided into 30 day months.
Custom calendar attributes in CF-1.4, not currently supported here:
Caution: When using the "gregorian" calendar system, the UDUNITS mixed Gregorian/Julian interpretation is used.
For the mixed Gregorian/Julian calendar, it is strongly recommended that all encoded dates as well as the reference date in the units string be greater than or equal to October 15, 1582. This is the valid start date for the contemporary interval of the Gregorian calendar system.
Known bug in NCL V6.4.0 and earlier: Many users have reported a "60 second" bug in several of NCL's date conversion routines, in which you get a value of "n minutes, 60 seconds" instead of "n+1 minutes, 0 seconds". See the 6.4.0 release notes for details. If you encounter this bug, please email the ncl-talk group with the details. Meanwhile, you can ry the temporary calendar_decode2_fix, which was added in NCL V6.4.0 for test purposes and potentially as a replacement function. A decision will be made about this function in a future release of NCL.
Restrictions in this version:
When calendar = "gregorian" or equivalent, this routine defers to NCL's ut_calendar function and includes all of its functionality.
This also applies for "proleptic_gregorian" or equivalent, but only when all dates including the time unit string are "safe" dates later than 1582.
The following apply when any of the other supported calendars are used:
For proleptic_gregorian calendar with any dates 1852 or earlier, only output options 0 and -5 are supported.
For output options 0 and -5, all calendars other than gregorian and proleptic_gregorian, the input time variable must be scalar or a one dimensional array. For all other output options, there is no restriction on dimensionality.
- Units string syntax must be one of these three:
uuuu since y-m-d
uuuu since y-m-d h:m:s
uuuu since y-m-d h:m:s.s
days since 1800-1-1
days since 1800-01-01 0:0:0
days since 1800-01-01 00:00:0.000
- Base unit for time (uuuu) must be one of these:
day or days
hour or hours
minute or minutes
second or seconds
- The base year must be zero or positive.
- Time of day in the units string is NOT CHECKED and MUST BE ZERO.
- (LATER: Time of day in the units string is restricted to zero only.)
- The time zone suffix in the units string is not supported and must
not be included.
- The global "conventions" attribute is not checked for consistency
with calendar attributes encountered.
- Type and dimension checking of calendar attributes is minimal.
Following typical conventions, attribute names are CASE SENSITIVE.
String attribute values are CASE INSENSITIVE.
University of Colorado, CIRES Climate Diagnostics Center (CDC)
NOAA/ESRL/PSD, Climate Analysis Branch (CAB)