cf.Field.convert_reference_time¶

Field.
convert_reference_time
(*args, **kwargs)[source]¶ Convert reference time data values to have new units.
Conversion is done by decoding the reference times to datetime objects and then reencoding them for the new units.
Any conversions are possible, but this method is primarily for conversions which require a change in the datetimes 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 units of “calendar months” were intended but encoded as “months”, which have special definition. See the note and examples below for more details.
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.Performance
For conversions which do not require a change in the datetimes 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 2000121'
thenc.Units = cf.Units('days since 190111')
will give the same result and be considerably faster thanc.convert_reference_time(cf.Units('days since 190111'))
. Parameters
 units:
Units
, optional The reference time units to convert to. By default the units days since the original reference time in the original calendar.
 Parameter example:
If the original units are
'months since 200011'
in the Gregorian calendar then the default units to convert to are'days since 200011'
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). inplace:
bool
, optional If True then do the operation inplace and return
None
. i: deprecated at version 3.0.0
Use the inplace parameter instead.
 units:
 Returns
Examples
>>> print(f.array) [0 1 2 3] >>> f.Units <Units: months since 200411> >>> print(f.datetime_array) [cftime.DatetimeGregorian(2003, 12, 1, 0, 0, 0, 0, has_year_zero=False) cftime.DatetimeGregorian(2003, 12, 31, 10, 29, 3, 831223, has_year_zero=False) cftime.DatetimeGregorian(2004, 1, 30, 20, 58, 7, 662446, has_year_zero=False) cftime.DatetimeGregorian(2004, 3, 1, 7, 27, 11, 493670, has_year_zero=False)] >>> g = f.convert_reference_time(calendar_months=True) >>> g.Units <Units: days since 200411> >>> print(g.datetime_array) [cftime.DatetimeGregorian(2003, 12, 1, 0, 0, 0, 0, has_year_zero=False) cftime.DatetimeGregorian(2004, 1, 1, 0, 0, 0, 0, has_year_zero=False) cftime.DatetimeGregorian(2004, 2, 1, 0, 0, 0, 0, has_year_zero=False) cftime.DatetimeGregorian(2004, 3, 1, 0, 0, 0, 0, has_year_zero=False)] >>> print(g.array) [ 0 31 62 91]