Deprecation of loffset parameter to resample()

[douglatornell]

I am struggling to understand how to deal with this deprecation. I can't figure out values for the new origin and offset parameters of Dataset.resample() that produce the same result I get with loffset. Here is example code that resamples a day-averaged dataset to a month-averaged one using loffset:

import datetime

import numpy
import pandas
import xarray

extracted_ds = xarray.Dataset(
    coords={
        "time": pandas.date_range(
            "2015-04-01",
            periods=30,
            freq=pandas.tseries.offsets.DateOffset(days=1),
        ),
        "depth": numpy.arange(0, 4, 0.5),
        "y": numpy.arange(9),
        "x": numpy.arange(4),
    },
    data_vars={
        "diatoms": xarray.DataArray(
            name="diatoms",
            data=numpy.ones((30, 8, 9, 4), dtype=numpy.single),
            coords={
                "time": pandas.date_range(
                    "2015-04-01",
                    periods=30,
                    freq=pandas.tseries.offsets.DateOffset(days=1),
                ),
                "depth": numpy.arange(0, 4, 0.5),
                "y": numpy.arange(9),
                "x": numpy.arange(4),
            },
        )
    },
)

offset = (datetime.date(2015, 5, 1) - datetime.date(2015, 4, 1)) / 2
print(f"{offset=}")

resampler = extracted_ds.resample(
    {"time": "1M"},
    label="left",
    loffset=offset,
    skipna=False,
)
print(f"{resampler=}")

resampled_ds = resampler.mean("time", keep_attrs=True)
print(f"{resampled_ds=}")

expected = xarray.DataArray(
    pandas.date_range(
        "2015-04-15", periods=1, freq=pandas.tseries.offsets.DateOffset(days=1)
    ),
    coords={
        "time": pandas.date_range(
            "2015-04-15",
            periods=1,
            freq=pandas.tseries.offsets.DateOffset(days=1),
        )
    },
    dims="time",
)
xarray.testing.assert_equal(resampled_ds.time, expected)

That code gives the result:

offset=datetime.timedelta(days=15)
resampler=DatasetResample, grouped over '__resample_dim__'
1 groups with labels 2015-04-15.
resampled_ds=<xarray.Dataset>
Dimensions:  (time: 1, depth: 8, y: 9, x: 4)
Coordinates:
  * depth    (depth) float64 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5
  * y        (y) int64 0 1 2 3 4 5 6 7 8
  * x        (x) int64 0 1 2 3
  * time     (time) datetime64[ns] 2015-04-15
Data variables:
    diatoms  (time, depth, y, x) float32 1.0 1.0 1.0 1.0 1.0 ... 1.0 1.0 1.0 1.0
<input>:39: FutureWarning: Following pandas, the `loffset` parameter to resample will be deprecated in a future version of xarray.  Switch to using time offset arithmetic.

Note the value of the time coordinate: 2015-04-15; i.e. the centre of the period over which the mean is calculated.

Changing the resampler() call to:

resampler = extracted_ds.resample(
    {"time": "1M"},
    label="left",
    offset=offset,
    skipna=False,
)

produces:

offset=datetime.timedelta(days=15)
resampler=DatasetResample, grouped over '__resample_dim__'
1 groups with labels 2015-03-31.
resampled_ds=<xarray.Dataset>
Dimensions:  (time: 1, depth: 8, y: 9, x: 4)
Coordinates:
  * depth    (depth) float64 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5
  * y        (y) int64 0 1 2 3 4 5 6 7 8
  * x        (x) int64 0 1 2 3
  * time     (time) datetime64[ns] 2015-03-31
Data variables:
    diatoms  (time, depth, y, x) float32 1.0 1.0 1.0 1.0 1.0 ... 1.0 1.0 1.0 1.0
Traceback (most recent call last):
  File "/home/doug/.local/share/JetBrains/Toolbox/apps/pycharm-professional/plugins/python/helpers/pydev/pydevconsole.py", line 364, in runcode
    coro = func()
           ^^^^^^
  File "<input>", line 66, in <module>
  File "/home/doug/conda_envs/reshapr-dev/lib/python3.11/site-packages/xarray/testing.py", line 37, in wrapper
    
  File "/home/doug/conda_envs/reshapr-dev/lib/python3.11/site-packages/xarray/testing.py", line 84, in assert_equal
    type(a) == type(b) or isinstance(a, Coordinates) and isinstance(b, Coordinates)
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: Left and right DataArray objects are not equal
Differing values:
L
    array(['2015-03-31T00:00:00.000000000'], dtype='datetime64[ns]')
R
    array(['2015-04-15T00:00:00.000000000'], dtype='datetime64[ns]')
Differing coordinates:
L * time     (time) datetime64[ns] 2015-03-31
R * time     (time) datetime64[ns] 2015-04-15

Why is the value of time now 2015-03-31? That date isn't in the dataset that we are resampling!

Setting the origin parameter, explicitly, or to "start" or "start_day" doesn't result in any change; e.g.:

resampler = extracted_ds.resample(
    {"time": "1M"},
    label="left",
    offset=offset,
    origin=datetime.date(2015, 4, 1),
    skipna=False,
)

produces the same result as above.

I guess I'm not understanding what "Switch to using time offset arithmetic." in the deprecation means. I'd appreciate any guidance or suggestions.

I'm using:

• python 3.11.4
• xarray 2023.8.0
• flox 0.7.2
• pandas 2.0.3
• numpy 1.25.1

[fuxb]

I also struggled with understanding this, but finally found #4535 (comment)

So in your case this would be:

from pandas.tseries.frequencies import to_offset

resampler = extracted_ds.resample(
    {"time": "1M"},
    label="left",
    skipna=False,
)
resampler["time"] = resampler.get_index("time") + to_offset(offset)

Please can anybody from the development team confirm that this is the correct way to do this? Thx.

[dcherian]

Yes that looks right. Suggestions or a PR to improve that error message are very welcome!

[douglatornell]

Thanks @fuxb! That was the clue that I needed. When I tested your suggestion though, I found that the time offset arithmetic has to be done on the resampled dataset, not the resampler object. So, the correct resolution for my problem is:

resampler = extracted_ds.resample(
    {"time": "1M"},
    label="left",
    skipna=False,
)

resampled_ds = resampler.mean("time", keep_attrs=True)
resampled_ds["time"] = resampled_ds.get_index("time") + pandas.tseries.frequencies.to_offset(offset)

[douglatornell]

@dcherian I think maybe rewording the error message from:

FutureWarning: Following pandas, the `loffset` parameter to resample will be deprecated in a
future version of xarray.  Switch to using time offset arithmetic.

to

FutureWarning: Following pandas, the `loffset` parameter to resample will be deprecated in a
future version of xarray.  Switch to updating the resampled dataset time coordinate using time offset arithmetic.

would be an improvement.

However, I'm not sure that I would have arrived at the solution even with that change. Your suggestion in #7596 that there needs to be an example in the docs is spot on. I'm willing to take a try at that if you want me to. I can include the above error message change in the PR if you think it is an improvement.

[dcherian]

I'm willing to take a try at that if you want me to. I can include the above error message change in the PR if you think it is an improvement.

Yes please to both. We need help!