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.

Raises:

KeyError – If time coordinates were not detected in the dataset, either because they don’t exist at all or their CF attributes (e.g., ‘axis’ or ‘standard_name’) are not set.

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

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'}