issue_comments: 424395224

@sbiner these are all reasonable points of confusion. The current behavior in xarray regarding non-standard calendars is complicated, and we are working toward improving the situation. I've tried to provide a recommended solution based on your example as well as some historical/future context. Apologies for the long-winded answer!

Recommendation

For accurate round-tripping of date types, I would recommend that you run your code to open the dataset with the xarray option enable_cftimeindex set to True (by default it is currently set to False; for why this is the case, see the note regarding the default behavior). In the case of your example this would look like: ``` In [1]: import cftime

In [2]: import numpy as np

In [3]: import xarray as xr

In [4]: units = 'days since 2000-02-25'

In [5]: times = cftime.num2date(np.arange(7), units=units, calendar='365_day')

In [6]: da = xr.DataArray(np.arange(7), coords=[times], dims=['time'], name='a')

In [7]: da.to_netcdf('data-noleap.nc')

In [8]: with xr.set_options(enable_cftimeindex=True): ...: cftimeindex_enabled = xr.open_dataset('data-noleap.nc') ...: Here we can see that the time index is a `CFTimeIndex`, and that the time coordinate contains instances of `cftime.DatetimeNoLeap` objects (as they were in the original DataArray we created): In [9]: cftimeindex_enabled.indexes['time'] Out[9]: CFTimeIndex([2000-02-25 00:00:00, 2000-02-26 00:00:00, 2000-02-27 00:00:00, 2000-02-28 00:00:00, 2000-03-01 00:00:00, 2000-03-02 00:00:00, 2000-03-03 00:00:00], dtype='object', name=u'time')

In [10]: cftimeindex_enabled.time[0] Out[10]: <xarray.DataArray 'time' ()> array(cftime._cftime.DatetimeNoLeap(2000, 2, 25, 0, 0, 0, 0, 6, 56), dtype=object) Coordinates: time object 2000-02-25 00:00:00 Note that `resample` along a CFTimeIndex has not been implemented yet (#2191). Attempting to do so will raise an error. If you are interested in computing something as simple as a time series of annual means using `resample`, then you could work around that in the meantime by using `groupby`, for example: In [11]: cftimeindex_enabled.groupby('time.year').mean('time') Out[11]: <xarray.Dataset> Dimensions: (year: 1) Coordinates: * year (year) int64 2000 Data variables: a (year) float64 3.0 ``` For more information on what is enabled and what is not enabled when using a CFTimeIndex for indexing, see this section in the documentation.

Default behavior

The default behavior can be traced back to the early days of xarray (see the original discussion in #118, #121, and #126). It boils down to coercing any dates decoded into cftime.datetime objects (formerly netCDF4.datetime) into np.datetime64[ns] objects whenever possible. If this coercion is not possible (e.g. a date in the file is not allowed in the standard calendar like 2000-02-30 in the case of a 360-day calendar, or a date has a year outside the range 1678-2262) then cftime.datetime objects are allowed to remain. In other words, by default xarray indeed does use cftime to decode the dates; however, after decoding, it will try its hardest to convert those dates into a friendly type for pandas.

The advantage of the default approach is that, when possible, it allows you to take advantage of all the nice features that a time coordinate indexed by a pandas.DatetimeIndex provides (like resample). A disadvantage is that the dates in memory may not have the same calendar type as those encoded in the file (e.g. if the dates in the file are from a non-standard calendar, like no leap). For operations that rely on computing differences between dates (e.g.differentiate orinterp involving a time coordinate), this can lead to subtle (and silent) errors. Therefore when using dates coerced into a DatetimeIndex from a non-standard calendar, one should use caution to only do operations that are independent of the calendar type (one notable exception here is that xarray does make an effort to encode these dates accurately when writing out to a netCDF file).

Connecting back to your example, we can see that if we don't open the dataset with enable_cftimeindex=True, the dates are coerced to np.datetime64 objects and a DatetimeIndex is used: ``` In [12]: default = xr.open_dataset('data-noleap.nc')

In [13]: default.indexes['time'] Out[13]: DatetimeIndex(['2000-02-25', '2000-02-26', '2000-02-27', '2000-02-28', '2000-03-01', '2000-03-02', '2000-03-03'], dtype='datetime64[ns]', name=u'time', freq=None)

In [14]: default.time[0] Out[14]: <xarray.DataArray 'time' ()> array(951436800000000000L, dtype='datetime64[ns]') Coordinates: time datetime64[ns] 2000-02-25 In this case, as noted above, `resample` works: In [15]: default.resample(time='Y').mean('time') Out[15]: <xarray.Dataset> Dimensions: (time: 1) Coordinates: * time (time) datetime64[ns] 2000-12-31 Data variables: a (time) float64 3.0 ```

Future behavior

In xarray we are slowly working towards better support for operations involving cftime.datetime objects (see #789, #1084, #1252, #2008, #2142, #2301, #2434). Eventually we would like to switch to using enable_cftimeindex=True as the default: in that case the behavior would be to use np.datetime64 objects (associated with DatetimeIndexes) only for standard calendars, and cftime.datetime objects (associated with CFTimeIndexes) for any other calendar types.

The two major outstanding issues on this front are probably: - Adding resample functionality to CFTimeIndex (#2191) - Plotting data with cftime.datetime coordinate axes in matplotlib or holoviews (#2164).

Once those two remaining issues are addressed, one should be able to do most of the significant things one can do with np.datetime64 dates with cftime.datetime dates (and therefore changing the default behavior would be justified).