xcdat.decode_time#

xcdat.decode_time(dataset)[source]#

Decodes CF and non-CF time coordinates and time bounds using cftime.

By default, xarray only supports decoding time with CF compliant units 3. This function enables also decoding time with non-CF compliant units. It skips decoding time coordinates that have already been decoded as "datetime64[ns]" or cftime.datetime.

For time coordinates to be decodable, they must have a “calendar” attribute set to a CF calendar type supported by cftime. CF calendar types include “noleap”, “360_day”, “365_day”, “366_day”, “gregorian”, “proleptic_gregorian”, “julian”, “all_leap”, or “standard”. They must also have a “units” attribute set to a format supported by xcdat (“months since …” or “years since …”).

Parameters

dataset (xr.Dataset) – Dataset with numerically encoded time coordinates and time bounds (if they exist). If the time coordinates cannot be decoded then the original dataset is returned.

Returns

xr.Dataset – Dataset with decoded time coordinates and time bounds (if they exist) as cftime objects.

Notes

Time coordinates are represented by cftime.datetime objects because it is not restricted by the pandas.Timestamp range (years 1678 through 2262). Refer to 4 and 5 for more information on this limitation.

References

3

https://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate

4

https://docs.xarray.dev/en/stable/user-guide/weather-climate.html#non-standard-calendars-and-dates-outside-the-timestamp-valid-range

5

https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timestamp-limitations

Examples

Decode the time coordinates in a Dataset:

>>> from xcdat.dataset import decode_time
>>>
>>> ds.time
<xarray.DataArray 'time' (time: 3)>
array([0, 1, 2])
Coordinates:
* time     (time) int64 0 1 2
Attributes:
    units:          years since 2000-01-01
    bounds:         time_bnds
    axis:           T
    long_name:      time
    standard_name:  time
    calendar:       noleap
>>>
>>> ds_decoded = decode_time(ds)
>>> ds_decoded.time
<xarray.DataArray 'time' (time: 3)>
array([cftime.DatetimeNoLeap(1850, 1, 1, 0, 0, 0, 0, has_year_zero=True),
       cftime.DatetimeNoLeap(1850, 1, 1, 0, 0, 0, 0, has_year_zero=True),
       cftime.DatetimeNoLeap(1850, 1, 1, 0, 0, 0, 0, has_year_zero=True)],
       dtype='object')
Coordinates:
* time     (time) datetime64[ns] 2000-01-01 2001-01-01 2002-01-01
Attributes:
    units:          years since 2000-01-01
    bounds:         time_bnds
    axis:           T
    long_name:      time
    standard_name:  time
    calendar:       noleap

View time encoding information:

>>> ds_decoded.time.encoding
{'source': None,
 'dtype': dtype('int64'),
 'original_shape': (3,),
 'units': 'years since 2000-01-01',
 'calendar': 'noleap'}