cf.DomainAncillary.convert_reference_time

DomainAncillary.convert_reference_time(*args, **kwargs)

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 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 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')).

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 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).

inplace: bool, optional

If True then do the operation in-place and return None.

i: deprecated at version 3.0.0

Use the inplace parameter instead.

Returns

DomainAncillary or None

The construct with converted reference time data values, or None if the operation was in-place.

Examples

>>> print(f.array)
[0 1 2 3]
>>> f.Units
<Units: months since 2004-1-1>
>>> 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 2004-1-1>
>>> 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]