Make cftime dateoffsets public

[dcherian]

Consider the following cftime vector. It's fairly common to see users asking how to subtract "1 month" from this kind of vector:

xr.set_options(display_style="text")
time = xr.DataArray(
    xr.cftime_range("1000-01-01", "1000-05-01", freq="MS", calendar="360_day"), dims="time", name="time"
)
time

<xarray.DataArray 'time' (time: 5)>
array([cftime.Datetime360Day(1000, 1, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 2, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 3, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 4, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 5, 1, 0, 0, 0, 0, has_year_zero=False)],
      dtype=object)
Coordinates:
  * time     (time) object 1000-01-01 00:00:00 ... 1000-05-01 00:00:00

Subtracting pd.Timedelta("1 month") does not work because a month does not represent an absolute unit of time. Instead the solution appears to be:

time - xr.coding.cftime_offsets.MonthBegin(1)

<xarray.DataArray 'time' (time: 5)>
array([cftime.Datetime360Day(999, 12, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 1, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 2, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 3, 1, 0, 0, 0, 0, has_year_zero=False),
       cftime.Datetime360Day(1000, 4, 1, 0, 0, 0, 0, has_year_zero=False)],
      dtype=object)
Coordinates:
  * time     (time) object 1000-01-01 00:00:00 ... 1000-05-01 00:00:00

I think pandas exposes this functionality as pd.DateOffset(months=1). Can we add a similar xr.DateOffset?

[spencerkclark]

I agree this would be useful functionality. Were you thinking that we would design xr.DateOffset such that it would work for both np.datetime64 values and cftime objects?

[dcherian]

Were you thinking that we would design xr.DateOffset such that it would work for both np.datetime64 values and cftime objects?

I think so. It would be very convenient and is similar to the proposed xr.date_range (#5233)