From 8ee12f66269c1c875d245a118679356dd2624a5a Mon Sep 17 00:00:00 2001
From: Doug Latornell <dlatornell@eoas.ubc.ca>
Date: Tue, 28 Nov 2023 17:31:43 -0800
Subject: [PATCH] Update resample time offset FutureWarning and docs (#8479)

* Improve FutureWarning re: resample() loffset parameter

As discussed in https://github.com/pydata/xarray/discussions/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
https://github.com/pydata/xarray/discussions/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 | 12 ++++++++++++
 doc/whats-new.rst              |  6 ++++++
 xarray/core/common.py          |  7 +++++--
 xarray/core/dataarray.py       |  6 ++++++
 xarray/core/dataset.py         |  6 ++++++
 5 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/user-guide/time-series.rst b/doc/user-guide/time-series.rst
index cbb831cac3a..82172aa8998 100644
--- a/doc/user-guide/time-series.rst
+++ b/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`.
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
index 92048e02837..82842430b53 100644
--- a/doc/whats-new.rst
+++ b/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>`_.
diff --git a/xarray/core/common.py b/xarray/core/common.py
index fa0fa9aec0f..cb5b79defc0 100644
--- a/xarray/core/common.py
+++ b/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,
             )
 
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
index 47708cfb581..bac4ad36adb 100644
--- a/xarray/core/dataarray.py
+++ b/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.
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
index 5d2d24d6723..66c83e95b77 100644
--- a/xarray/core/dataset.py
+++ b/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.