Update resample time offset FutureWarning and docs (#8479)

* Improve FutureWarning re: resample() loffset parameter

As discussed in #8175

* Add docs re: resample time offset arithmetic

Illustrate updating the time coordinate values of a resampled dataset
using time offset arithmetic. This is the recommended technique to
replace the use of the deprecated `loffset` parameter in `resample()`

re: issue #7596 and discussion
#8175

* Add loffset deprecation warning to resample docstrings

* Add docs change to whats-new.rst

* Drop redundant FutureWarning in warning text

* Change deprecation warning to present tense

* Add code example for FutureWarning message

---------

Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>

doc/user-guide/time-series.rst

@@ -245,6 +245,18 @@ Data that has indices outside of the given ``tolerance`` are set to ``NaN``.
 
     ds.resample(time="1h").nearest(tolerance="1h")
 
+It is often desirable to center the time values after a resampling operation.
+That can be accomplished by updating the resampled dataset time coordinate values
+using time offset arithmetic via the `pandas.tseries.frequencies.to_offset`_ function.
+
+.. _pandas.tseries.frequencies.to_offset: https://pandas.pydata.org/docs/reference/api/pandas.tseries.frequencies.to_offset.html
+
+.. ipython:: python
+
+    resampled_ds = ds.resample(time="6h").mean()
+    offset = pd.tseries.frequencies.to_offset("6h") / 2
+    resampled_ds["time"] = resampled_ds.get_index("time") + offset
+    resampled_ds
 
 For more examples of using grouped operations on a time dimension, see
 :doc:`../examples/weather-data`.

doc/whats-new.rst

@@ -57,6 +57,12 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Added illustration of updating the time coordinate values of a resampled dataset using
+  time offset arithmetic.
+  This is the recommended technique to replace the use of the deprecated ``loffset`` parameter
+  in ``resample`` (:pull:`8479`).
+  By `Doug Latornell <https://github.com/douglatornell>`_.
+
 - Improved error message when attempting to get a variable which doesn't exist from a Dataset.
   (:pull:`8474`)
   By `Maximilian Roos <https://github.com/max-sixty>`_.

xarray/core/common.py

@@ -1010,8 +1010,11 @@ def _resample(
 
         if loffset is not None:
             emit_user_level_warning(
-                "Following pandas, the `loffset` parameter to resample will be deprecated "
-                "in a future version of xarray.  Switch to using time offset arithmetic.",
+                "Following pandas, the `loffset` parameter to resample is deprecated.  "
+                "Switch to updating the resampled dataset time coordinate using "
+                "time offset arithmetic.  For example:\n"
+                "    >>> offset = pd.tseries.frequencies.to_offset(freq) / 2\n"
+                '    >>> resampled_ds["time"] = resampled_ds.get_index("time") + offset',
                 FutureWarning,
             )
 

xarray/core/dataarray.py

@@ -7032,6 +7032,12 @@ def resample(
         loffset : timedelta or str, optional
             Offset used to adjust the resampled time labels. Some pandas date
             offset strings are supported.
+
+            .. deprecated:: 2023.03.0
+                Following pandas, the ``loffset`` parameter is deprecated in favor
+                of using time offset arithmetic, and will be removed in a future
+                version of xarray.
+
         restore_coord_dims : bool, optional
             If True, also restore the dimension order of multi-dimensional
             coordinates.

xarray/core/dataset.py

@@ -10382,6 +10382,12 @@ def resample(
         loffset : timedelta or str, optional
             Offset used to adjust the resampled time labels. Some pandas date
             offset strings are supported.
+
+            .. deprecated:: 2023.03.0
+                Following pandas, the ``loffset`` parameter is deprecated in favor
+                of using time offset arithmetic, and will be removed in a future
+                version of xarray.
+
         restore_coord_dims : bool, optional
             If True, also restore the dimension order of multi-dimensional
             coordinates.