Deprecate certain cftime frequency strings following pandas (#8415)

* Deprecate certain frequency strings following pandas [test-upstream]

Specifically the frequency strings "A", "AS", "Q", "M", "H", "T", "S", "L",
"U", and "N" are deprecated in favor of "Y", "YS", "QE", "ME", "h", "min", "s",
"ms", "us", and "ns", respectively.

* Apply suggestions from code review

Co-authored-by: Pascal Bourgault <[email protected]>

---------

Co-authored-by: Pascal Bourgault <[email protected]>
Co-authored-by: Deepak Cherian <[email protected]>

Author: 3 people

doc/user-guide/time-series.rst

@@ -89,7 +89,7 @@ items and with the `slice` object:
 
 .. ipython:: python
 
-    time = pd.date_range("2000-01-01", freq="H", periods=365 * 24)
+    time = pd.date_range("2000-01-01", freq="h", periods=365 * 24)
     ds = xr.Dataset({"foo": ("time", np.arange(365 * 24)), "time": time})
     ds.sel(time="2000-01")
     ds.sel(time=slice("2000-06-01", "2000-06-10"))
@@ -115,7 +115,7 @@ given ``DataArray`` can be quickly computed using a special ``.dt`` accessor.
 
 .. ipython:: python
 
-    time = pd.date_range("2000-01-01", freq="6H", periods=365 * 4)
+    time = pd.date_range("2000-01-01", freq="6h", periods=365 * 4)
     ds = xr.Dataset({"foo": ("time", np.arange(365 * 4)), "time": time})
     ds.time.dt.hour
     ds.time.dt.dayofweek
@@ -207,7 +207,7 @@ For example, we can downsample our dataset from hourly to 6-hourly:
 .. ipython:: python
     :okwarning:
 
-    ds.resample(time="6H")
+    ds.resample(time="6h")
 
 This will create a specialized ``Resample`` object which saves information
 necessary for resampling. All of the reduction methods which work with
@@ -216,21 +216,21 @@ necessary for resampling. All of the reduction methods which work with
 .. ipython:: python
     :okwarning:
 
-    ds.resample(time="6H").mean()
+    ds.resample(time="6h").mean()
 
 You can also supply an arbitrary reduction function to aggregate over each
 resampling group:
 
 .. ipython:: python
 
-    ds.resample(time="6H").reduce(np.mean)
+    ds.resample(time="6h").reduce(np.mean)
 
 You can also resample on the time dimension while applying reducing along other dimensions at the same time
 by specifying the `dim` keyword argument
 
 .. code-block:: python
 
-    ds.resample(time="6H").mean(dim=["time", "latitude", "longitude"])
+    ds.resample(time="6h").mean(dim=["time", "latitude", "longitude"])
 
 For upsampling, xarray provides six methods: ``asfreq``, ``ffill``, ``bfill``, ``pad``,
 ``nearest`` and ``interpolate``. ``interpolate`` extends ``scipy.interpolate.interp1d``
@@ -243,7 +243,7 @@ Data that has indices outside of the given ``tolerance`` are set to ``NaN``.
 
 .. ipython:: python
 
-    ds.resample(time="1H").nearest(tolerance="1H")
+    ds.resample(time="1h").nearest(tolerance="1h")
 
 
 For more examples of using grouped operations on a time dimension, see

doc/user-guide/weather-climate.rst

@@ -239,7 +239,7 @@ For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports:
 
 .. ipython:: python
 
-    da.resample(time="81T", closed="right", label="right", offset="3T").mean()
+    da.resample(time="81min", closed="right", label="right", offset="3min").mean()
 
 .. _nanosecond-precision range: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timestamp-limitations
 .. _ISO 8601 standard: https://en.wikipedia.org/wiki/ISO_8601

doc/whats-new.rst

@@ -39,6 +39,12 @@ Breaking changes
   `xcdat <https://github.com/xCDAT/xcdat>`_ instead (:pull:`8441`).
   By `Justus Magin <https://github.com/keewis`_.
 
+- Following pandas, :py:meth:`infer_freq` will return ``"Y"``, ``"YS"``,
+  ``"QE"``, ``"ME"``, ``"h"``, ``"min"``, ``"s"``, ``"ms"``, ``"us"``, or
+  ``"ns"`` instead of ``"A"``, ``"AS"``, ``"Q"``, ``"M"``, ``"H"``, ``"T"``,
+  ``"S"``, ``"L"``, ``"U"``, or ``"N"``.  This is to be consistent with the
+  deprecation of the latter frequency strings (:issue:`8394`, :pull:`8415`). By
+  `Spencer Clark <https://github.com/spencerkclark>`_.
 - Bump minimum tested pint version to ``>=0.22``. By `Deepak Cherian <https://github.com/dcherian>`_.
 
 Deprecations
@@ -51,6 +57,14 @@ Deprecations
   this was one place in the API where dimension positions were used.
   (:pull:`8341`)
   By `Maximilian Roos <https://github.com/max-sixty>`_.
+- Following pandas, the frequency strings ``"A"``, ``"AS"``, ``"Q"``, ``"M"``,
+  ``"H"``, ``"T"``, ``"S"``, ``"L"``, ``"U"``, and ``"N"`` are deprecated in
+  favor of ``"Y"``, ``"YS"``, ``"QE"``, ``"ME"``, ``"h"``, ``"min"``, ``"s"``,
+  ``"ms"``, ``"us"``, and ``"ns"``, respectively.  These strings are used, for
+  example, in :py:func:`date_range`, :py:func:`cftime_range`,
+  :py:meth:`DataArray.resample`, and :py:meth:`Dataset.resample` among others
+  (:issue:`8394`, :pull:`8415`).  By `Spencer Clark
+  <https://github.com/spencerkclark>`_.
 - Rename :py:meth:`Dataset.to_array` to  :py:meth:`Dataset.to_dataarray` for
   consistency with :py:meth:`DataArray.to_dataset` &
   :py:func:`open_dataarray` functions. This is a "soft" deprecation — the