cf.AuxiliaryCoordinate.convert_reference_time

AuxiliaryCoordinate.convert_reference_time(units=None, calendar_months=False, calendar_years=False, i=False)

Convert reference time data values to have new units.

Conversion is done by decoding the reference times to date-time objects and then re-encoding them for the new units.

Any conversions are possible, but this method is primarily for conversions which require a change in the date-times originally encoded. For example, use this method to reinterpret data values in units of “months” since a reference time to data values in “calendar months” since a reference time. This is often necessary when when units of “calendar months” were intended but encoded as “months”, which have special definition. See the note and examples below for more details.

For conversions which do not require a change in the date-times implied by the data values, this method will be considerably slower than a simple reassignment of the units. For example, if the original units are 'days since 2000-12-1' then c.Units = cf.Units('days since 1901-1-1') will give the same result and be considerably faster than c.convert_reference_time(cf.Units('days since 1901-1-1'))

Note

It is recommended that the units “year” and “month” be used with caution, as explained in the following excerpt from the CF conventions: “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 to be exactly year/12, should also be used with caution.

Examples 1:

>>> d = c.convert_reference_time()

Parameters:

units: cf.Units, optional

The reference time units to convert to. By default the units are “days since the original reference time in the original calendar”.

Example:

If the original units are 'months since 2000-1-1' in the Gregorian calendar then the default units to convert to are 'days since 2000-1-1' in the Gregorian calendar.

calendar_months: bool, optional

If True then treat units of 'months' as if they were calendar months (in whichever calendar is originally specified), rather than a 12th of the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781/12 days).

calendar_years: bool, optional

If True then treat units of 'years' as if they were calendar years (in whichever calendar is originally specified), rather than the interval between 2 successive passages of the sun through vernal equinox (i.e. 365.242198781 days).

i: bool, optional

If True then update the auxiliary coordinate in place. By default a new auxiliary coordinate is created. In either case, a auxiliary coordinate is returned.

Returns:

out: cf.AuxiliaryCoordinate

The auxiliary coordinate with converted reference time data values.

Examples 2:

>>> print c.Units
months since 2000-1-1
>>> print c.array
[1 3]
>>> print c.dtarray
[datetime.datetime(2000, 1, 31, 10, 29, 3, 831197)
 datetime.datetime(2000, 4, 1, 7, 27, 11, 493645)]
>>> print c.bounds.array
[[ 0  2]
 [ 2  4]]
>>> print c.bounds.dtarray
[[datetime.datetime(2000, 1, 1, 0, 0) datetime.datetime(2000, 3, 1, 20, 58, 7, 662441)]
 [datetime.datetime(2000, 3, 1, 20, 58, 7, 662441) datetime.datetime(2000, 5, 1, 17, 56, 15, 324889)]]
>>> c.convert_reference_time(calendar_months=True, i=True)
>>> print c.Units
days since 2000-1-1
>>> print c.array
[  31.,  91.]
>>> print c.dtarray
[datetime.datetime(2000, 2, 1, 0, 0)
 datetime.datetime(2000, 4, 1, 0, 0)]
>>> print c.bounds.dtarray
[[datetime.datetime(2000, 1, 1, 0, 0) datetime.datetime(2000, 3, 1, 0, 0)]
 [datetime.datetime(2000, 3, 1, 0, 0) datetime.datetime(2000, 5, 1, 0, 0)]]