NCL Home > Documentation > Functions > Date routines

cd_inv_calendar

Converts a UT-referenced date to a mixed Julian/Gregorian date.

Available in version 6.0.0 and later.

Prototype

	function cd_inv_calendar (
		year       : numeric,  ; numeric allowed in NCL 6.4.0 and later
		month      : numeric,  
		day        : numeric,  
		hour       : numeric,  
		minute     : numeric,  
		second     : numeric,  
		units      : string,   
		option [1] : integer   
	)

	return_val [dimsizes(year)] :  int, long, float, double (pre V6.4.0 --> double only)

Arguments

year

An array or scalar representing years.

month

An array or scalar representing months. Must be same dimensionality as year.

day

An array or scalar representing days. Must be same dimensionality as year.

hour

An array or scalar representing hours. Must be same dimensionality as year.

minute

An array or scalar representing minutes. Must be same dimensionality as year.

second

An array or scalar representing seconds. Must be same dimensionality as year.

units

A string representing a formatted time unit specification. Valid strings include:

seconds
minutes
hours
days
months
years

The following units qualifiers may also be used:

since
after
from
ref

Examples:

  units = "days after 0049-09-01 00:00:00"
  units = "hours ref 1-1-1 00:00:0.0"
  units = "months from 1-1-1"

option

The actual value of this variable currently has no effect, but it can optionally contain a "calendar" or "return_type" attribute. See description below.

Return value

An array of the same size as year with a default return type of double.

As of NCL V6.4.0, you can specify other return types of "float", "long", or "integer" via the special "return_type" attribute attached to option. See the description below for details.

The return variable will have a "units" attribute that contains the temporal units.

Description

This function converts a UT-referenced date to a mixed Julian/Gregorian date.

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 try the temporary ut_inv_calendar_fix function to see if it fixes the problem.

This function is meant to be a replacement for ut_inv_calendar and thus takes the same arguments. Important note: ut_inv_calendar and cd_inv_calendar treat "year 0" differently. See the caveats below.

The default is to use the mixed Julian/Gregorian calendar. To change the calendar, you can set option@calendar to one of the following strings:

"standard"
"gregorian"
"proleptic_gregorian"
"julian"
"360_day", "360"
"365_day", "365"
"366_day", "366"
"noleap", "no_leap"
"allleap", "all_leap"
"none" (Added in V6.1.0)

This code was adopted with permission from a modified version of the cdtime software that is part of the NetCDF library developed at Unidata/UCAR. The cdtime software is part of CDMS, developed by the Program for Climate Model Diagnosis and Intercomparison (PCMDI) at Lawrence Livermore National Laboratory (LLNL).

Caveats

Year 0 is not treated as year 1 like it is with the ut_calendar and ut_inv_calendar functions.
This function does not return the correct minutes and seconds if the reference time doesn't start at minute=0, second=0.
The "none" calendar is not yet supported.
If you use the special "return_type" attribute to specify a return type of something other than double, then be aware that the values could be truncated if they are too large to fit in a float, long, or integer type.
This function was updated in NCL V6.4.0 to allow any numeric type to be used for the first six input arguments.
Internally, these arguments have to be coerced as follows:
- year - long
- month - short
- day - short
- hour - double
- minute - double
- second - double
Truncation may occur if you pass in values that cannot be coerced to the required type. For example, if you enter a float value of "1995.8" for year, this will get truncated to a long equal to "1995". NO WARNING WILL BE ISSUED IF THIS OCCURS.

Examples

Example 1: To see how the inverse function cd_inv_calendar works, simply take the output from cd_calendar and plug it back into cd_inv_calendar:

  utc_date = cd_calendar(time, 0)

  year   = tointeger(utc_date(:,0))
  month  = tointeger(utc_date(:,1))
  day    = tointeger(utc_date(:,2))
  hour   = tointeger(utc_date(:,3))
  minute = tointeger(utc_date(:,4))
  second = utc_date(:,5)

  date = cd_inv_calendar(year,month,day,hour,minute,second,time@units, 0)

The arrays date and time should be identical.

Example 2: Convert yyyymmdd to a user specified 'units' attribute. The default calendar attribute is "standard". This is the same as the "gregorian" calendar.


  yyyymmdd  = (/19900101, 19950105, 19981102, 20030423, 20100612/)

  ntim  = dimsizes(yyyymmdd)

  yyyy  = yyyymmdd/10000 
  mmdd  = yyyymmdd-yyyy*10000                ; mmdd = yyyymmdd%10000
  mm    = mmdd/100
  dd    = mmdd-mm*100                        ; dd   = mmdd%100

  hh    = dd                                 ; create arrays [*] of required size
  mn    = dd
  sc    = dd

  hh    = 0                                  ; array syntax
  mn    = 0
  sc    = 0
                                             ; user specified
  units  = "hours since 1900-01-01 00:00:00" ; "seconds/hours/days since ...."
                                             ; do NOT use "months since ...."

  time   = cd_inv_calendar(yyyy,mm,dd,hh,mn,sc,units, 0)
  time!0 = "time"
  print(time)

The output from the print statement:


Variable: time
Type: double
Total Size: 40 bytes
            5 values
Number of Dimensions: 1
Dimensions and sizes:	[time | 5]
Coordinates: 
Number Of Attributes: 2
  calendar :	standard
  units :	hours since 1900-01-01 00:00:00

(0)	788928
(1)	832848
(2)	866376
(3)	905568
(4)	968136

Example 3: this example illustrates the use of the "return_type" attribute added in NCL V6.4.0, and serves as a precautionary tale of when it is not a good idea to use it.

  year   = 1999
  month  = 12
  day    = 31
  hour   = 0
  minute = 0
  second = 0
  units  = "hours since 1-1-1 00:00:0.0"

  opt = 0
  cd_dbl1 = cd_inv_calendar(year,month,day,hour,minute,second,units,opt)

  opt@return_type = "float"
  cd_flt1 = cd_inv_calendar(year,month,day,hour,minute,second,units,opt)

  print(cd_dbl1)
  print(cd_flt1)
  print("cd_dbl1-cd_flt1 = " + (cd_dbl1-cd_flt1))

cd_dbl1 and cd_flt1 should be identical, except one will be a float and one will be a double:

    Variable: cd_dbl1
    Type: double
    Total Size: 8 bytes
                1 values
    Number of Dimensions: 1
    Dimensions and sizes:[1]
    Coordinates: 
    Number Of Attributes: 2
    calendar : standard
    units : hours since 1-1-1 00:00:0.0
    17522880
    
    
    Variable: cd_flt1
    Type: float
    Total Size: 4 bytes
                1 values
    Number of Dimensions: 1
    Dimensions and sizes:[1]
    Coordinates: 
    Number Of Attributes: 2
    calendar : standard
    units : hours since 1-1-1 00:00:0.0
    1.752288e+07
    cd_dbl1-cd_flt1 = 0

Note what happens, however, if you simply change the value of hour:

;---Change the hour value and note what happens to cd_flt2
  hour  = 23

  opt2 = 0
  cd_dbl2 = cd_inv_calendar(year,month,day,hour,minute,second,units,opt2)

  opt2@return_type = "float"
  cd_flt2 = cd_inv_calendar(year,month,day,hour,minute,second,units,opt2)

  print(cd_dbl2)
  print(cd_flt2)
  print("cd_dbl2-cd_flt2 = " + (cd_dbl2-cd_flt2))

Note the two values are NOT equal and their differences are not zero: