Time Coding#

This page gives an overview how xarray encodes and decodes times and which conventions and functions are used.

Pandas functionality#

to_datetime#

The function pandas.to_datetime() is used within xarray for inferring units and for testing purposes.

In normal operation pandas.to_datetime() returns a pandas.Timestamp (for scalar input) or pandas.DatetimeIndex (for array-like input) which are related to np.datetime64 values with a resolution inherited from the input (can be one of 's', 'ms', 'us', 'ns'). If no resolution can be inherited 'ns' is assumed. That has the implication that the maximum usable time range for those cases is approximately +/- 292 years centered around the Unix epoch (1970年01月01日). To accommodate that, we carefully check the units/resolution in the encoding and decoding step.

When the arguments are numeric (not strings or np.datetime64 values) "unit" can be anything from 'Y', 'W', 'D', 'h', 'm', 's', 'ms', 'us' or 'ns', though the returned resolution will be "ns".

print(f"Minimum datetime: {pd.to_datetime(int64_min,unit="ns")}")
print(f"Maximum datetime: {pd.to_datetime(int64_max,unit="ns")}")

Minimum datetime: 1677年09月21日 00:12:43.145224193
Maximum datetime: 2262年04月11日 23:47:16.854775807

For input values which can’t be represented in nanosecond resolution an pandas.OutOfBoundsDatetime exception is raised:

try:
 dtime = pd.to_datetime(int64_max, unit="us")
except Exception as err:
 print(err)

try:
 dtime = pd.to_datetime(uint64_max, unit="ns")
 print("Wrong:", dtime)
 dtime = pd.to_datetime([uint64_max], unit="ns")
except Exception as err:
 print(err)

Wrong: 1969年12月31日 23:59:59.999999999
cannot convert input 18446744073709551615 with the unit 'ns'

np.datetime64 values can be extracted with pandas.Timestamp.to_numpy() and pandas.DatetimeIndex.to_numpy(). The returned resolution depends on the internal representation. This representation can be changed using pandas.Timestamp.as_unit() and pandas.DatetimeIndex.as_unit() respectively.

as_unit takes one of 's', 'ms', 'us', 'ns' as an argument. That means we are able to represent datetimes with second, millisecond, microsecond or nanosecond resolution.

time = pd.to_datetime(np.datetime64(0, "D"))
print("Datetime:", time, np.asarray([time.to_numpy()]).dtype)
print("Datetime as_unit('ms'):", time.as_unit("ms"))
print("Datetime to_numpy():", time.as_unit("ms").to_numpy())

Datetime: 1970年01月01日 00:00:00 datetime64[s]
Datetime as_unit('ms'): 1970年01月01日 00:00:00
Datetime to_numpy(): 1970年01月01日T00:00:00.000

time = pd.to_datetime(np.array([-1000, 1, 2], dtype="datetime64[Y]"))
print("DatetimeIndex:", time)
print("DatetimeIndex as_unit('us'):", time.as_unit("us"))
print("DatetimeIndex to_numpy():", time.as_unit("us").to_numpy())

DatetimeIndex: DatetimeIndex(['970-01-01', '1971年01月01日', '1972年01月01日'], dtype='datetime64[s]', freq=None)
DatetimeIndex as_unit('us'): DatetimeIndex(['970-01-01', '1971年01月01日', '1972年01月01日'], dtype='datetime64[us]', freq=None)
DatetimeIndex to_numpy(): ['0970年01月01日T00:00:00.000000' '1971年01月01日T00:00:00.000000'
 '1972年01月01日T00:00:00.000000']

Warning

Input data with resolution higher than 'ns' (eg. 'ps', 'fs', 'as') is truncated (not rounded) at the 'ns'-level. This is currently broken for the 'ps' input, where it is interpreted as 'ns'.

print("Good:", pd.to_datetime([np.datetime64(1901901901901, "as")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "fs")]))
print(" Bad:", pd.to_datetime([np.datetime64(1901901901901, "ps")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "ns")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "us")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "ms")]))

Good: DatetimeIndex(['1970年01月01日 00:00:00.000001901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970年01月01日 00:00:00.001901901'], dtype='datetime64[ns]', freq=None)
 Bad: DatetimeIndex(['1970年01月01日 00:00:01.901901901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970年01月01日 00:31:41.901901901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970年01月23日 00:18:21.901901'], dtype='datetime64[us]', freq=None)
Good: DatetimeIndex(['2030年04月08日 18:05:01.901000'], dtype='datetime64[ms]', freq=None)

Warning

Care has to be taken, as some configurations of input data will raise. The following shows, that we are safe to use pandas.to_datetime() when providing numpy.datetime64 as scalar or numpy array as input.

print(
 "Works:",
 np.datetime64(1901901901901, "s"),
 pd.to_datetime(np.datetime64(1901901901901, "s")),
)
print(
 "Works:",
 np.array([np.datetime64(1901901901901, "s")]),
 pd.to_datetime(np.array([np.datetime64(1901901901901, "s")])),
)
try:
 pd.to_datetime([np.datetime64(1901901901901, "s")])
except Exception as err:
 print("Raises:", err)
try:
 pd.to_datetime(1901901901901, unit="s")
except Exception as err:
 print("Raises:", err)
try:
 pd.to_datetime([1901901901901], unit="s")
except Exception as err:
 print("Raises:", err)
try:
 pd.to_datetime(np.array([1901901901901]), unit="s")
except Exception as err:
 print("Raises:", err)

Works: 62238-11-15T11:51:41 62238-11-15 11:51:41
Works: ['62238-11-15T11:51:41'] DatetimeIndex(['62238-11-15 11:51:41'], dtype='datetime64[s]', freq=None)

to_timedelta#

The function pandas.to_timedelta() is used within xarray for inferring units and for testing purposes.

In normal operation pandas.to_timedelta() returns a pandas.Timedelta (for scalar input) or pandas.TimedeltaIndex (for array-like input) which are np.timedelta64 values with ns resolution internally. That has the implication, that the usable timedelta covers only roughly 585 years. To accommodate for that, we are working around that limitation in the encoding and decoding step.

f"Maximum timedelta range: ({pd.to_timedelta(int64_min,unit="ns")}, {pd.to_timedelta(int64_max,unit="ns")})"

'Maximum timedelta range: (-106752 days +00:12:43.145224193, 106751 days 23:47:16.854775807)'

For input values which can’t be represented in nanosecond resolution an pandas.OutOfBoundsTimedelta exception is raised:

try:
 delta = pd.to_timedelta(int64_max, unit="us")
except Exception as err:
 print("First:", err)

try:
 delta = pd.to_timedelta(uint64_max, unit="ns")
except Exception as err:
 print("Second:", err)

Second: Cannot cast 18446744073709551615 from ns to 'ns' without overflow.

When arguments are numeric (not strings or np.timedelta64 values) "unit" can be anything from 'W', 'D', 'h', 'm', 's', 'ms', 'us' or 'ns', though the returned resolution will be "ns".

np.timedelta64 values can be extracted with pandas.Timedelta.to_numpy() and pandas.TimedeltaIndex.to_numpy(). The returned resolution depends on the internal representation. This representation can be changed using pandas.Timedelta.as_unit() and pandas.TimedeltaIndex.as_unit() respectively.

as_unit takes one of 's', 'ms', 'us', 'ns' as an argument. That means we are able to represent timedeltas with second, millisecond, microsecond or nanosecond resolution.

delta = pd.to_timedelta(np.timedelta64(1, "D"))
print("Timedelta:", delta, np.asarray([delta.to_numpy()]).dtype)
print("Timedelta as_unit('ms'):", delta.as_unit("ms"))
print("Timedelta to_numpy():", delta.as_unit("ms").to_numpy())

Timedelta: 1 days 00:00:00 timedelta64[s]
Timedelta as_unit('ms'): 1 days 00:00:00
Timedelta to_numpy(): 86400000 milliseconds

delta = pd.to_timedelta([0, 1, 2], unit="D")
print("TimedeltaIndex:", delta)
print("TimedeltaIndex as_unit('ms'):", delta.as_unit("ms"))
print("TimedeltaIndex to_numpy():", delta.as_unit("ms").to_numpy())

TimedeltaIndex: TimedeltaIndex(['0 days', '1 days', '2 days'], dtype='timedelta64[s]', freq=None)
TimedeltaIndex as_unit('ms'): TimedeltaIndex(['0 days', '1 days', '2 days'], dtype='timedelta64[ms]', freq=None)
TimedeltaIndex to_numpy(): [ 0 86400000 172800000]

Warning

Care has to be taken, as some configurations of input data will raise. The following shows, that we are safe to use pandas.to_timedelta() when providing numpy.timedelta64 as scalar or numpy array as input.

print(
 "Works:",
 np.timedelta64(1901901901901, "s"),
 pd.to_timedelta(np.timedelta64(1901901901901, "s")),
)
print(
 "Works:",
 np.array([np.timedelta64(1901901901901, "s")]),
 pd.to_timedelta(np.array([np.timedelta64(1901901901901, "s")])),
)
try:
 pd.to_timedelta([np.timedelta64(1901901901901, "s")])
except Exception as err:
 print("Raises:", err)
try:
 pd.to_timedelta(1901901901901, unit="s")
except Exception as err:
 print("Raises:", err)
try:
 pd.to_timedelta([1901901901901], unit="s")
except Exception as err:
 print("Raises:", err)
try:
 pd.to_timedelta(np.array([1901901901901]), unit="s")
except Exception as err:
 print("Raises:", err)

Works: 1901901901901 seconds 22012753 days 11:51:41
Works: [1901901901901] TimedeltaIndex(['22012753 days 11:51:41'], dtype='timedelta64[s]', freq=None)

Timestamp#

pandas.Timestamp is used within xarray to wrap strings of CF encoding reference times and datetime.datetime.

When arguments are numeric (not strings) "unit" can be anything from 'Y', 'W', 'D', 'h', 'm', 's', 'ms', 'us' or 'ns', though the returned resolution will be "ns".

In normal operation pandas.Timestamp holds the timestamp in the provided resolution, but only one of 's', 'ms', 'us', 'ns'. Lower resolution input is automatically converted to 's', higher resolution input is truncated to 'ns'.

The same conversion rules apply here as for pandas.to_timedelta() (see to_timedelta). Depending on the internal resolution Timestamps can be represented in the range:

for unit in ["s", "ms", "us", "ns"]:
 print(
 f"unit: {unit!r} time range ({pd.Timestamp(int64_min,unit=unit)}, {pd.Timestamp(int64_max,unit=unit)})"
 )

unit: 's' time range (-292277022657-01-27 08:29:53, 292277026596-12-04 15:30:07)
unit: 'ms' time range (-292275055-05-16 16:47:04.193000, 292278994-08-17 07:12:55.807000)
unit: 'us' time range (-290308-12-21 19:59:05.224193, 294247-01-10 04:00:54.775807)
unit: 'ns' time range (1677年09月21日 00:12:43.145224193, 2262年04月11日 23:47:16.854775807)

Since relaxing the resolution, this enhances the range to several hundreds of thousands of centuries with microsecond representation. NaT will be at np.iinfo("int64").min for all of the different representations.

Warning

When initialized with a datetime string this is only defined from -9999年01月01日 to 9999年12月31日.

try:
 print("Works:", pd.Timestamp("-9999年01月01日 00:00:00"))
 print("Works, too:", pd.Timestamp("9999年12月31日 23:59:59"))
 print(pd.Timestamp("10000-01-01 00:00:00"))
except Exception as err:
 print("Errors:", err)

Works: -9999年01月01日 00:00:00
Works, too: 9999年12月31日 23:59:59
Errors: year must be in 1..9999, not 10000: 10000-01-01 00:00:00

Note

pandas.Timestamp is the only current possibility to correctly import time reference strings. It handles non-ISO formatted strings, keeps the resolution of the strings ('s', 'ms' etc.) and imports time zones. When initialized with numpy.datetime64 instead of a string it even overcomes the above limitation of the possible time range.

try:
 print("Handles non-ISO:", pd.Timestamp("92-1-8 151542"))
 print(
 "Keeps resolution 1:",
 pd.Timestamp("1992年10月08日 15:15:42"),
 pd.Timestamp("1992年10月08日 15:15:42").unit,
 )
 print(
 "Keeps resolution 2:",
 pd.Timestamp("1992年10月08日 15:15:42.5"),
 pd.Timestamp("1992年10月08日 15:15:42.5").unit,
 )
 print(
 "Keeps timezone:",
 pd.Timestamp("1992年10月08日 15:15:42.5 -6:00"),
 pd.Timestamp("1992年10月08日 15:15:42.5 -6:00").unit,
 )
 print(
 "Extends timerange :",
 pd.Timestamp(np.datetime64("-10000-10-08 15:15:42.5001")),
 pd.Timestamp(np.datetime64("-10000-10-08 15:15:42.5001")).unit,
 )
except Exception as err:
 print("Errors:", err)

Handles non-ISO: 1992年01月08日 15:15:42
Keeps resolution 1: 1992年10月08日 15:15:42 us
Keeps resolution 2: 1992年10月08日 15:15:42.500000 us
Keeps timezone: 1992年10月08日 15:15:42.500000-06:00 us
Extends timerange : -10000-10-08 15:15:42.500100 us

DatetimeIndex#

pandas.DatetimeIndex is used to wrap np.datetime64 values or other datetime-likes when encoding. The resolution of the DatetimeIndex depends on the input, but can be only one of 's', 'ms', 'us', 'ns'. Lower resolution input is automatically converted to 's', higher resolution input is cut to 'ns'. pandas.DatetimeIndex will raise pandas.OutOfBoundsDatetime if the input can’t be represented in the given resolution.

try:
 print(
 "Works:",
 pd.DatetimeIndex(
 np.array(["1992年01月08日", "1992年01月09日"], dtype="datetime64[D]")
 ),
 )
 print(
 "Works:",
 pd.DatetimeIndex(
 np.array(
 ["1992年01月08日 15:15:42", "1992年01月09日 15:15:42"],
 dtype="datetime64[s]",
 )
 ),
 )
 print(
 "Works:",
 pd.DatetimeIndex(
 np.array(
 ["1992年01月08日 15:15:42.5", "1992年01月09日 15:15:42.0"],
 dtype="datetime64[ms]",
 )
 ),
 )
 print(
 "Works:",
 pd.DatetimeIndex(
 np.array(
 ["1970年01月01日 00:00:00.401501601701801901", "1970年01月01日 00:00:00"],
 dtype="datetime64[as]",
 )
 ),
 )
 print(
 "Works:",
 pd.DatetimeIndex(
 np.array(
 ["-10000-01-01 00:00:00.401501", "1970年01月01日 00:00:00"],
 dtype="datetime64[us]",
 )
 ),
 )
except Exception as err:
 print("Errors:", err)

Works: DatetimeIndex(['1992年01月08日', '1992年01月09日'], dtype='datetime64[s]', freq=None)
Works: DatetimeIndex(['1992年01月08日 15:15:42', '1992年01月09日 15:15:42'], dtype='datetime64[s]', freq=None)
Works: DatetimeIndex(['1992年01月08日 15:15:42.500000', '1992年01月09日 15:15:42'], dtype='datetime64[ms]', freq=None)
Works: DatetimeIndex(['1970年01月01日 00:00:00.401501601', '1970年01月01日 00:00:00'], dtype='datetime64[ns]', freq=None)
Works: DatetimeIndex(['-10000-01-01 00:00:00.401501', '1970年01月01日 00:00:00'], dtype='datetime64[us]', freq=None)

CF Conventions Time Handling#

Xarray tries to adhere to the latest version of the CF Conventions. Relevant is the section on Time Coordinate and the Calendar subsection.

CF time decoding#

Decoding of values with a time unit specification like "seconds since 1992年10月8日 15:15:42.5 -6:00" into datetimes using the CF conventions is a multistage process.

  1. If we have a non-standard calendar (e.g. "noleap") decoding is done with the cftime package, which is not covered in this section. For the "standard"/"gregorian" calendar as well as the "proleptic_gregorian" calendar the above outlined pandas functionality is used.

  2. The "standard"/"gregorian" calendar and the "proleptic_gregorian" are equivalent for any dates and reference times >= "1582年10月15日". First the reference time is checked and any timezone information stripped off. In a second step, the minimum and maximum values are checked if they can be represented in the current reference time resolution. At the same time integer overflow would be caught. For the "standard"/"gregorian" calendar the dates are checked to be >= "1582年10月15日". If anything fails, the decoding is attempted with cftime.

  3. As the unit (here "seconds") and the resolution of the reference time "1992年10月8日 15:15:42.5 -6:00" (here "milliseconds") might be different, the decoding resolution is aligned to the higher resolution of the two. Users may also specify their wanted target resolution by setting the time_unit keyword argument to one of 's', 'ms', 'us', 'ns' (default 'ns'). This will be included in the alignment process. This is done by multiplying the values by the ratio of nanoseconds per time unit and nanoseconds per reference time unit. To retain consistency for NaT values a mask is kept and re-introduced after the multiplication.

  4. Times encoded as floating point values are checked for fractional parts and the resolution is enhanced in an iterative process until a fitting resolution (or 'ns') is found. A SerializationWarning is issued to make the user aware of the possibly problematic encoding.

  5. Finally, the values (at this point converted to int64 values) are cast to datetime64[unit] (using the above retrieved unit) and added to the reference time pandas.Timestamp.

calendar = "proleptic_gregorian"
values = np.array([-1000 * 365, 0, 1000 * 365], dtype="int64")
units = "days since 2000年01月01日 00:00:00.000001"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[us]"
dt

array(['1000年08月31日T00:00:00.000001', '2000年01月01日T00:00:00.000001',
 '2999年05月03日T00:00:00.000001'], dtype='datetime64[us]')

units = "microseconds since 2000年01月01日 00:00:00"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[us]"
dt

array(['1999年12月31日T23:59:59.635000', '2000年01月01日T00:00:00.000000',
 '2000年01月01日T00:00:00.365000'], dtype='datetime64[us]')

values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "days since 2000年01月01日 00:00:00.001"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[ms]"
dt

array(['2000年01月01日T00:00:00.001', '2000年01月01日T06:00:00.001',
 '2000年01月01日T12:00:00.001', '2000年01月01日T18:00:00.001',
 '2000年01月02日T00:00:00.001'], dtype='datetime64[ms]')

values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "hours since 2000年01月01日"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt

array(['2000年01月01日T00:00:00', '2000年01月01日T00:15:00',
 '2000年01月01日T00:30:00', '2000年01月01日T00:45:00',
 '2000年01月01日T01:00:00'], dtype='datetime64[s]')

values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "hours since 2000年01月01日 00:00:00 03:30"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt

array(['2000年01月01日T03:30:00', '2000年01月01日T03:45:00',
 '2000年01月01日T04:00:00', '2000年01月01日T04:15:00',
 '2000年01月01日T04:30:00'], dtype='datetime64[s]')

values = np.array([-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64")
units = "days since 0001年01月01日 00:00:00"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt

array(['-2000年01月01日T00:00:00', '0000年01月01日T00:00:00',
 '0002年01月01日T00:00:00', '2000年01月01日T00:00:00'],
 dtype='datetime64[s]')

CF time encoding#

For encoding the process is more or less a reversal of the above, but we have to make some decisions on default values.

  1. Infer data_units from the given dates.

  2. Infer units (either cleanup given units or use data_units

  3. Infer the calendar name from the given dates.

  4. If dates are cftime.datetime objects then encode with cftime.date2num

  5. Retrieve time_units and ref_date from units

  6. Check ref_date >= 1582年10月15日, otherwise -> cftime

  7. Wrap dates with pd.DatetimeIndex

  8. Subtracting ref_date (pandas.Timestamp) from above pandas.DatetimeIndex will return pandas.TimedeltaIndex

  9. Align resolution of pandas.TimedeltaIndex with resolution of time_units

  10. Retrieve needed units and delta to faithfully encode into int64

  11. Divide time_deltas by delta, use floor division (integer) or normal division (float)

  12. Return result

calendar = "proleptic_gregorian"
dates = np.array(
 [
 "-2000年01月01日T00:00:00",
 "0000年01月01日T00:00:00",
 "0002年01月01日T00:00:00",
 "2000年01月01日T00:00:00",
 ],
 dtype="datetime64[s]",
)
orig_values = np.array(
 [-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64"
)
units = "days since 0001年01月01日 00:00:00"
values, _, _ = xr.coding.times.encode_cf_datetime(
 dates, units, calendar, dtype=np.dtype("int64")
)
print(values, units)
np.testing.assert_array_equal(values, orig_values)

[-730851 -366 365 730119] days since 0001年01月01日 00:00:00

dates = np.array(
 [
 "-2000年01月01日T01:00:00",
 "0000年01月01日T00:00:00",
 "0002年01月01日T00:00:00",
 "2000年01月01日T00:00:00",
 ],
 dtype="datetime64[s]",
)
orig_values = np.array(
 [-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64"
)
orig_values *= 24 # Convert to hours
orig_values[0] += 1 # Adjust for the hour offset in dates above
units = "days since 0001年01月01日 00:00:00"
values, units, _ = xr.coding.times.encode_cf_datetime(
 dates, units, calendar, dtype=np.dtype("int64")
)
print(values, units)
np.testing.assert_array_equal(values, orig_values)

[-17540423 -8784 8760 17522856] hours since 0001年01月01日

/tmp/ipykernel_6212/3474695674.py:17: UserWarning: Times can't be serialized faithfully to int64 with requested units 'days since 0001年01月01日'. Serializing with units 'hours since 0001年01月01日' instead. Set encoding['dtype'] to floating point dtype to serialize with units 'days since 0001年01月01日'. Set encoding['units'] to 'hours since 0001年01月01日' to silence this warning .
 values, units, _ = xr.coding.times.encode_cf_datetime(

Default Time Unit#

The current default time unit of xarray is 'ns'. When setting keyword argument time_unit unit to 's' (the lowest resolution pandas allows) datetimes will be converted to at least 's'-resolution, if possible. The same holds true for 'ms' and 'us'.

datetimes1_filename = "test-datetimes1.nc"

attrs = {"units": "hours since 2000年01月01日"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(datetimes1_filename)

xr.open_dataset(datetimes1_filename)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) datetime64[ns] 32B 2000年01月01日 ... 2000年01月01日T03:00:00
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      datetime64[ns]
      2000年01月01日 ... 2000年01月01日T03:00:00
      array(['2000年01月01日T00:00:00.000000000', '2000年01月01日T01:00:00.000000000',
 '2000年01月01日T02:00:00.000000000', '2000年01月01日T03:00:00.000000000'],
 dtype='datetime64[ns]')
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(datetimes1_filename, decode_times=coder)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) datetime64[s] 32B 2000年01月01日 ... 2000年01月01日T03:00:00
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      datetime64[s]
      2000年01月01日 ... 2000年01月01日T03:00:00
      array(['2000年01月01日T00:00:00', '2000年01月01日T01:00:00', '2000年01月01日T02:00:00',
 '2000年01月01日T03:00:00'], dtype='datetime64[s]')

If a coarser unit is requested the datetimes are decoded into their native on-disk resolution, if possible.

datetimes2_filename = "test-datetimes2.nc"

attrs = {"units": "milliseconds since 2000年01月01日"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(datetimes2_filename)

xr.open_dataset(datetimes2_filename)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) datetime64[ns] 32B 2000年01月01日 ... 2000年01月01日T00:00:00.003000
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      datetime64[ns]
      2000年01月01日 ... 2000年01月01日T00:00:...
      array(['2000年01月01日T00:00:00.000000000', '2000年01月01日T00:00:00.001000000',
 '2000年01月01日T00:00:00.002000000', '2000年01月01日T00:00:00.003000000'],
 dtype='datetime64[ns]')
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(datetimes2_filename, decode_times=coder)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) datetime64[ms] 32B 2000年01月01日 ... 2000年01月01日T00:00:00.003000
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      datetime64[ms]
      2000年01月01日 ... 2000年01月01日T00:00:...
      array(['2000年01月01日T00:00:00.000', '2000年01月01日T00:00:00.001',
 '2000年01月01日T00:00:00.002', '2000年01月01日T00:00:00.003'],
 dtype='datetime64[ms]')

Similar logic applies for decoding timedelta values. The default resolution is "ns":

timedeltas1_filename = "test-timedeltas1.nc"

attrs = {"units": "hours"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(timedeltas1_filename)

xr.open_dataset(timedeltas1_filename)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) int64 32B 0 1 2 3
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      int64
      0 1 2 3
      units :
      hours
      array([0, 1, 2, 3])

By default, timedeltas will be decoded to the same resolution as datetimes:

coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(timedeltas1_filename, decode_times=coder, decode_timedelta=True)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) timedelta64[ns] 32B 00:00:00 01:00:00 02:00:00 03:00:00
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      timedelta64[ns]
      00:00:00 01:00:00 02:00:00 03:00:00
      array([ 0, 3600000000000, 7200000000000, 10800000000000],
 dtype='timedelta64[ns]')

but if one would like to decode timedeltas to a different resolution, one can provide a coder specifically for timedeltas to decode_timedelta:

timedelta_coder = xr.coders.CFTimedeltaCoder(time_unit="ms")
xr.open_dataset(
 timedeltas1_filename, decode_times=coder, decode_timedelta=timedelta_coder
)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) int64 32B 0 1 2 3
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      int64
      0 1 2 3
      units :
      hours
      array([0, 1, 2, 3])

As with datetimes, if a coarser unit is requested the timedeltas are decoded into their native on-disk resolution, if possible:

timedeltas2_filename = "test-timedeltas2.nc"

attrs = {"units": "milliseconds"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(timedeltas2_filename)

xr.open_dataset(timedeltas2_filename, decode_timedelta=True)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) timedelta64[ns] 32B 00:00:00 ... 00:00:00.003000
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      timedelta64[ns]
      00:00:00 ... 00:00:00.003000
      array([ 0, 1000000, 2000000, 3000000], dtype='timedelta64[ns]')
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(timedeltas2_filename, decode_times=coder, decode_timedelta=True)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) timedelta64[ns] 32B 00:00:00 ... 00:00:00.003000
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      timedelta64[ns]
      00:00:00 ... 00:00:00.003000
      array([ 0, 1000000, 2000000, 3000000], dtype='timedelta64[ns]')

To opt-out of timedelta decoding (see issue Undesired decoding to timedelta64) pass False to decode_timedelta:

xr.open_dataset(timedeltas2_filename, decode_timedelta=False)

<xarray.Dataset> Size: 32B
Dimensions: (time: 4)
Coordinates:
 * time (time) int64 32B 0 1 2 3
Data variables:
 *empty*
xarray.Dataset
    • time: 4
    • time
      (time)
      int64
      0 1 2 3
      units :
      milliseconds
      array([0, 1, 2, 3])

Note

Note that in the future the default value of decode_timedelta will be False rather than None.