[backport 2.3.x] DEPR: remove the Period resampling deprecation (#62480) (#62485)

Author: jorisvandenbossche

doc/source/whatsnew/v0.21.0.rst

@@ -635,22 +635,17 @@ Previous behavior:
 
 New behavior:
 
-.. code-block:: ipython
+.. ipython:: python
 
-   In [1]: pi = pd.period_range('2017-01', periods=12, freq='M')
+   pi = pd.period_range('2017-01', periods=12, freq='M')
 
-   In [2]: s = pd.Series(np.arange(12), index=pi)
+   s = pd.Series(np.arange(12), index=pi)
 
-   In [3]: resampled = s.resample('2Q').mean()
+   resampled = s.resample('2Q').mean()
 
-   In [4]: resampled
-   Out[4]:
-   2017Q1    2.5
-   2017Q3    8.5
-   Freq: 2Q-DEC, dtype: float64
+   resampled
 
-   In [5]: resampled.index
-   Out[5]: PeriodIndex(['2017Q1', '2017Q3'], dtype='period[2Q-DEC]')
+   resampled.index
 
 Upsampling and calling ``.ohlc()`` previously returned a ``Series``, basically identical to calling ``.asfreq()``. OHLC upsampling now returns a DataFrame with columns ``open``, ``high``, ``low`` and ``close`` (:issue:`13083`). This is consistent with downsampling and ``DatetimeIndex`` behavior.
 

doc/source/whatsnew/v2.2.0.rst

@@ -662,7 +662,7 @@ Other Deprecations
 - Deprecated :meth:`DatetimeArray.__init__` and :meth:`TimedeltaArray.__init__`, use :func:`array` instead (:issue:`55623`)
 - Deprecated :meth:`Index.format`, use ``index.astype(str)`` or ``index.map(formatter)`` instead (:issue:`55413`)
 - Deprecated :meth:`Series.ravel`, the underlying array is already 1D, so ravel is not necessary (:issue:`52511`)
-- Deprecated :meth:`Series.resample` and :meth:`DataFrame.resample` with a :class:`PeriodIndex` (and the 'convention' keyword), convert to :class:`DatetimeIndex` (with ``.to_timestamp()``) before resampling instead (:issue:`53481`)
+- Deprecated :meth:`Series.resample` and :meth:`DataFrame.resample` with a :class:`PeriodIndex` (and the 'convention' keyword), convert to :class:`DatetimeIndex` (with ``.to_timestamp()``) before resampling instead (:issue:`53481`). Note: this deprecation was later undone in pandas 2.3.3 (:issue:`57033`)
 - Deprecated :meth:`Series.view`, use :meth:`Series.astype` instead to change the dtype (:issue:`20251`)
 - Deprecated :meth:`offsets.Tick.is_anchored`, use ``False`` instead (:issue:`55388`)
 - Deprecated ``core.internals`` members ``Block``, ``ExtensionBlock``, and ``DatetimeTZBlock``, use public APIs instead (:issue:`55139`)

doc/source/whatsnew/v2.3.3.rst

@@ -57,6 +57,14 @@ Bug fixes
 
 - The :meth:`DataFrame.iloc` now works correctly with ``copy_on_write`` option when assigning values after subsetting the columns of a homogeneous DataFrame (:issue:`60309`)
 
+Other changes
+~~~~~~~~~~~~~
+
+- The deprecation of using :meth:`Series.resample` and :meth:`DataFrame.resample`
+  with a :class:`PeriodIndex` (and the 'convention' keyword) has been undone.
+  Resampling with a :class:`PeriodIndex` is supported again, but a subset of
+  methods that return incorrect results will raise an error in pandas 3.0 (:issue:`57033`)
+
 
 Other Bug fixes
 ~~~~~~~~~~~~~~~~

pandas/core/generic.py

@@ -9415,7 +9415,7 @@ def resample(
         axis: Axis | lib.NoDefault = lib.no_default,
         closed: Literal["right", "left"] | None = None,
         label: Literal["right", "left"] | None = None,
-        convention: Literal["start", "end", "s", "e"] | lib.NoDefault = lib.no_default,
+        convention: Literal["start", "end", "s", "e"] = "start",
         kind: Literal["timestamp", "period"] | None | lib.NoDefault = lib.no_default,
         on: Level | None = None,
         level: Level | None = None,
@@ -9454,8 +9454,6 @@ def resample(
             For `PeriodIndex` only, controls whether to use the start or
             end of `rule`.
 
-            .. deprecated:: 2.2.0
-                Convert PeriodIndex to DatetimeIndex before resampling instead.
         kind : {{'timestamp', 'period'}}, optional, default None
             Pass 'timestamp' to convert the resulting index to a
             `DateTimeIndex` or 'period' to convert it to a `PeriodIndex`.
@@ -9620,6 +9618,55 @@ def resample(
         2000-01-01 00:06:00    26
         Freq: 3min, dtype: int64
 
+        For a Series with a PeriodIndex, the keyword `convention` can be
+        used to control whether to use the start or end of `rule`.
+
+        Resample a year by quarter using 'start' `convention`. Values are
+        assigned to the first quarter of the period.
+
+        >>> s = pd.Series(
+        ...     [1, 2], index=pd.period_range("2012-01-01", freq="Y", periods=2)
+        ... )
+        >>> s
+        2012    1
+        2013    2
+        Freq: Y-DEC, dtype: int64
+        >>> s.resample("Q", convention="start").asfreq()
+        2012Q1    1.0
+        2012Q2    NaN
+        2012Q3    NaN
+        2012Q4    NaN
+        2013Q1    2.0
+        2013Q2    NaN
+        2013Q3    NaN
+        2013Q4    NaN
+        Freq: Q-DEC, dtype: float64
+
+        Resample quarters by month using 'end' `convention`. Values are
+        assigned to the last month of the period.
+
+        >>> q = pd.Series(
+        ...     [1, 2, 3, 4], index=pd.period_range("2018-01-01", freq="Q", periods=4)
+        ... )
+        >>> q
+        2018Q1    1
+        2018Q2    2
+        2018Q3    3
+        2018Q4    4
+        Freq: Q-DEC, dtype: int64
+        >>> q.resample("M", convention="end").asfreq()
+        2018-03    1.0
+        2018-04    NaN
+        2018-05    NaN
+        2018-06    2.0
+        2018-07    NaN
+        2018-08    NaN
+        2018-09    3.0
+        2018-10    NaN
+        2018-11    NaN
+        2018-12    4.0
+        Freq: M, dtype: float64
+
         For DataFrame objects, the keyword `on` can be used to specify the
         column instead of the index for resampling.
 
@@ -9784,18 +9831,6 @@ def resample(
         else:
             kind = None
 
-        if convention is not lib.no_default:
-            warnings.warn(
-                f"The 'convention' keyword in {type(self).__name__}.resample is "
-                "deprecated and will be removed in a future version. "
-                "Explicitly cast PeriodIndex to DatetimeIndex before resampling "
-                "instead.",
-                FutureWarning,
-                stacklevel=find_stack_level(),
-            )
-        else:
-            convention = "start"
-
         return get_resampler(
             cast("Series | DataFrame", self),
             freq=rule,

pandas/core/resample.py

@@ -1882,12 +1882,6 @@ class PeriodIndexResampler(DatetimeIndexResampler):
 
     @property
     def _resampler_for_grouping(self):
-        warnings.warn(
-            "Resampling a groupby with a PeriodIndex is deprecated. "
-            "Cast to DatetimeIndex before resampling instead.",
-            FutureWarning,
-            stacklevel=find_stack_level(),
-        )
         return PeriodIndexResamplerGroupby
 
     def _get_binner_for_time(self):
@@ -2237,15 +2231,7 @@ def _get_resampler(self, obj: NDFrame, kind=None) -> Resampler:
                 gpr_index=ax,
             )
         elif isinstance(ax, PeriodIndex) or kind == "period":
-            if isinstance(ax, PeriodIndex):
-                # GH#53481
-                warnings.warn(
-                    "Resampling with a PeriodIndex is deprecated. "
-                    "Cast index to DatetimeIndex before resampling instead.",
-                    FutureWarning,
-                    stacklevel=find_stack_level(),
-                )
-            else:
+            if not isinstance(ax, PeriodIndex):
                 warnings.warn(
                     "Resampling with kind='period' is deprecated.  "
                     "Use datetime paths instead.",

pandas/plotting/_matplotlib/timeseries.py

@@ -86,12 +86,9 @@ def maybe_resample(series: Series, ax: Axes, kwargs: dict[str, Any]):
             )
             freq = ax_freq
         elif _is_sup(freq, ax_freq):  # one is weekly
-            # Resampling with PeriodDtype is deprecated, so we convert to
-            #  DatetimeIndex, resample, then convert back.
-            ser_ts = series.to_timestamp()
-            ser_d = ser_ts.resample("D").last().dropna()
-            ser_freq = ser_d.resample(ax_freq).last().dropna()
-            series = ser_freq.to_period(ax_freq)
+            how = "last"
+            series = getattr(series.resample("D"), how)().dropna()
+            series = getattr(series.resample(ax_freq), how)().dropna()
             freq = ax_freq
         elif is_subperiod(freq, ax_freq) or _is_sub(freq, ax_freq):
             _upsample_others(ax, freq, kwargs)

pandas/tests/resample/test_base.py

@@ -87,13 +87,8 @@ def test_asfreq_fill_value(series, create_index):
 def test_resample_interpolate(frame):
     # GH#12925
     df = frame
-    warn = None
-    if isinstance(df.index, PeriodIndex):
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(warn, match=msg):
-        result = df.resample("1min").asfreq().interpolate()
-        expected = df.resample("1min").interpolate()
+    result = df.resample("1min").asfreq().interpolate()
+    expected = df.resample("1min").interpolate()
     tm.assert_frame_equal(result, expected)
 
 
@@ -125,13 +120,7 @@ def test_resample_empty_series(freq, empty_series_dti, resample_method):
     elif freq == "ME" and isinstance(ser.index, PeriodIndex):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
-
-    warn = None
-    if isinstance(ser.index, PeriodIndex):
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = ser.resample(freq)
+    rs = ser.resample(freq)
     result = getattr(rs, resample_method)()
 
     if resample_method == "ohlc":
@@ -189,9 +178,7 @@ def test_resample_nat_index_series(freq, series, resample_method):
     ser = series.copy()
     ser.index = PeriodIndex([NaT] * len(ser), freq=freq)
 
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(FutureWarning, match=msg):
-        rs = ser.resample(freq)
+    rs = ser.resample(freq)
     result = getattr(rs, resample_method)()
 
     if resample_method == "ohlc":
@@ -223,13 +210,7 @@ def test_resample_count_empty_series(freq, empty_series_dti, resample_method):
     elif freq == "ME" and isinstance(ser.index, PeriodIndex):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
-
-    warn = None
-    if isinstance(ser.index, PeriodIndex):
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = ser.resample(freq)
+    rs = ser.resample(freq)
 
     result = getattr(rs, resample_method)()
 
@@ -257,13 +238,7 @@ def test_resample_empty_dataframe(empty_frame_dti, freq, resample_method):
     elif freq == "ME" and isinstance(df.index, PeriodIndex):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
-
-    warn = None
-    if isinstance(df.index, PeriodIndex):
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = df.resample(freq, group_keys=False)
+    rs = df.resample(freq, group_keys=False)
     result = getattr(rs, resample_method)()
     if resample_method == "ohlc":
         # TODO: no tests with len(df.columns) > 0
@@ -306,14 +281,7 @@ def test_resample_count_empty_dataframe(freq, empty_frame_dti):
     elif freq == "ME" and isinstance(empty_frame_dti.index, PeriodIndex):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
-
-    warn = None
-    if isinstance(empty_frame_dti.index, PeriodIndex):
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = empty_frame_dti.resample(freq)
-    result = rs.count()
+    result = empty_frame_dti.resample(freq).count()
 
     index = _asfreq_compat(empty_frame_dti.index, freq)
 
@@ -340,14 +308,7 @@ def test_resample_size_empty_dataframe(freq, empty_frame_dti):
     elif freq == "ME" and isinstance(empty_frame_dti.index, PeriodIndex):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
-
-    msg = "Resampling with a PeriodIndex"
-    warn = None
-    if isinstance(empty_frame_dti.index, PeriodIndex):
-        warn = FutureWarning
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = empty_frame_dti.resample(freq)
-    result = rs.size()
+    result = empty_frame_dti.resample(freq).size()
 
     index = _asfreq_compat(empty_frame_dti.index, freq)
 
@@ -365,21 +326,12 @@ def test_resample_size_empty_dataframe(freq, empty_frame_dti):
     ],
 )
 @pytest.mark.parametrize("dtype", [float, int, object, "datetime64[ns]"])
-@pytest.mark.filterwarnings(r"ignore:PeriodDtype\[B\] is deprecated:FutureWarning")
 def test_resample_empty_dtypes(index, dtype, resample_method):
     # Empty series were sometimes causing a segfault (for the functions
     # with Cython bounds-checking disabled) or an IndexError.  We just run
     # them to ensure they no longer do.  (GH #10228)
-    warn = None
-    if isinstance(index, PeriodIndex):
-        # GH#53511
-        index = PeriodIndex([], freq="B", name=index.name)
-        warn = FutureWarning
-    msg = "Resampling with a PeriodIndex is deprecated"
-
     empty_series_dti = Series([], index, dtype)
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = empty_series_dti.resample("d", group_keys=False)
+    rs = empty_series_dti.resample("d", group_keys=False)
     try:
         getattr(rs, resample_method)()
     except DataError:
@@ -406,17 +358,8 @@ def test_apply_to_empty_series(empty_series_dti, freq):
         # index is PeriodIndex, so convert to corresponding Period freq
         freq = "M"
 
-    msg = "Resampling with a PeriodIndex"
-    warn = None
-    if isinstance(empty_series_dti.index, PeriodIndex):
-        warn = FutureWarning
-
-    with tm.assert_produces_warning(warn, match=msg):
-        rs = ser.resample(freq, group_keys=False)
-
-    result = rs.apply(lambda x: 1)
-    with tm.assert_produces_warning(warn, match=msg):
-        expected = ser.resample(freq).apply("sum")
+    result = ser.resample(freq, group_keys=False).apply(lambda x: 1)
+    expected = ser.resample(freq).apply("sum")
 
     tm.assert_series_equal(result, expected, check_dtype=False)
 
@@ -426,16 +369,8 @@ def test_resampler_is_iterable(series):
     # GH 15314
     freq = "h"
     tg = Grouper(freq=freq, convention="start")
-    msg = "Resampling with a PeriodIndex"
-    warn = None
-    if isinstance(series.index, PeriodIndex):
-        warn = FutureWarning
-
-    with tm.assert_produces_warning(warn, match=msg):
-        grouped = series.groupby(tg)
-
-    with tm.assert_produces_warning(warn, match=msg):
-        resampled = series.resample(freq)
+    grouped = series.groupby(tg)
+    resampled = series.resample(freq)
     for (rk, rv), (gk, gv) in zip(resampled, grouped):
         assert rk == gk
         tm.assert_series_equal(rv, gv)
@@ -448,13 +383,8 @@ def test_resample_quantile(series):
     q = 0.75
     freq = "h"
 
-    msg = "Resampling with a PeriodIndex"
-    warn = None
-    if isinstance(series.index, PeriodIndex):
-        warn = FutureWarning
-    with tm.assert_produces_warning(warn, match=msg):
-        result = ser.resample(freq).quantile(q)
-        expected = ser.resample(freq).agg(lambda x: x.quantile(q)).rename(ser.name)
+    result = ser.resample(freq).quantile(q)
+    expected = ser.resample(freq).agg(lambda x: x.quantile(q)).rename(ser.name)
     tm.assert_series_equal(result, expected)
 
 

pandas/tests/resample/test_datetime_index.py

@@ -184,9 +184,6 @@ def test_resample_basic_grouper(series, unit):
     tm.assert_series_equal(result, expected)
 
 
-@pytest.mark.filterwarnings(
-    "ignore:The 'convention' keyword in Series.resample:FutureWarning"
-)
 @pytest.mark.parametrize(
     "_index_start,_index_end,_index_name",
     [("1/1/2000 00:00:00", "1/1/2000 00:13:00", "index")],
@@ -1058,10 +1055,7 @@ def test_period_with_agg():
     )
 
     expected = s2.to_timestamp().resample("D").mean().to_period()
-    msg = "Resampling with a PeriodIndex is deprecated"
-    with tm.assert_produces_warning(FutureWarning, match=msg):
-        rs = s2.resample("D")
-    result = rs.agg(lambda x: x.mean())
+    result = s2.resample("D").agg(lambda x: x.mean())
     tm.assert_series_equal(result, expected)