ENH: Add end and end_day options for origin from resample

pandas/core/generic.py

@@ -7952,6 +7952,7 @@ def resample(
         on=None,
         level=None,
         origin: Union[str, TimestampConvertibleTypes] = "start_day",
+        backward: Optional[bool_t] = None,
         offset: Optional[TimedeltaConvertibleTypes] = None,
     ) -> Resampler:
         """
@@ -7972,8 +7973,9 @@ def resample(
             `DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`.
         closed : {'right', 'left'}, default None
             Which side of bin interval is closed. The default is 'left'
-            for all frequency offsets except for 'M', 'A', 'Q', 'BM',
-            'BA', 'BQ', and 'W' which all have a default of 'right'.
+            for all frequency offsets with forward resampling except for 'M',
+            'A', 'Q', 'BM', 'BA', 'BQ', and 'W' which all have a default of
+            'right'. When `Backward` set to be True, default is 'right'.
         label : {'right', 'left'}, default None
             Which bin edge label to label bucket with. The default is 'left'
             for all frequency offsets except for 'M', 'A', 'Q', 'BM',
@@ -8006,7 +8008,8 @@ def resample(
         level : str or int, optional
             For a MultiIndex, level (name or number) to use for
             resampling. `level` must be datetime-like.
-        origin : {'epoch', 'start', 'start_day'}, Timestamp or str, default 'start_day'
+        origin : {'epoch', 'start', 'start_day', 'end', 'end_day'}, Timestamp \
+        or str, default 'start_day'
             The timestamp on which to adjust the grouping. The timezone of origin
             must match the timezone of the index.
             If a timestamp is not used, these values are also supported:
@@ -8017,6 +8020,21 @@ def resample(
 
             .. versionadded:: 1.1.0
 
+            - 'end': `origin` is the last value of the timeseries
+            - 'end_day': `origin` is the ceiling midnight of the last day
+
+            .. versionadded:: 1.2.0
+
+        backward : bool, default is None
+            Resample on the given `origin` from a backward direction. True when
+            `origin` is 'end' or 'end_day'. False when `origin` is 'start' or
+            'start_day'. Optional when using datetime `origin` , and default
+            False. The resample result for a specified datetime stands for the
+            group from time substract the given `freq` to time with a right
+            `closed` setting by default.
+
+            .. versionadded:: 1.2.0
+
         offset : Timedelta or str, default is None
             An offset timedelta added to the origin.
 
@@ -8296,6 +8314,28 @@ def resample(
         2000-10-02 00:21:00    24
         Freq: 17T, dtype: int64
 
+        If you want to take the last timestamp as `origin` with a backward resample:
+
+        >>> ts.index.max()
+        Timestamp('2000-10-02 00:26:00', freq='7T')
+        >>> ts.groupby(pd.Grouper(freq='17min', origin='end')).sum()
+        2000-10-01 23:35:00     0
+        2000-10-01 23:52:00    18
+        2000-10-02 00:09:00    27
+        2000-10-02 00:26:00    63
+        Freq: 17T, dtype: int64
+
+        You can also specify the backward origin:
+
+        >>> ts.groupby(pd.Grouper(freq='17min',
+                                  origin='2000-10-02 00:30:00',
+                                  backward=True)).sum()
+        2000-10-01 23:39:00     3
+        2000-10-01 23:56:00    15
+        2000-10-02 00:13:00    45
+        2000-10-02 00:30:00    45
+        Freq: 17T, dtype: int32
+
         To replace the use of the deprecated `base` argument, you can now use `offset`,
         in this example it is equivalent to have `base=2`:
 
@@ -8337,6 +8377,7 @@ def resample(
             key=on,
             level=level,
             origin=origin,
+            backward=backward,
             offset=offset,
         )
 

pandas/core/groupby/grouper.py

@@ -83,9 +83,10 @@ class Grouper:
             However, loffset is also deprecated for ``.resample(...)``
             See: :class:`DataFrame.resample`
 
-    origin : {'epoch', 'start', 'start_day'}, Timestamp or str, default 'start_day'
-        The timestamp on which to adjust the grouping. The timezone of origin must
-        match the timezone of the index.
+    origin : {'epoch', 'start', 'start_day', 'end', 'end_day'}, Timestamp \
+    or str, default 'start_day'
+        The timestamp on which to adjust the grouping. The timezone of origin
+        must match the timezone of the index.
         If a timestamp is not used, these values are also supported:
 
         - 'epoch': `origin` is 1970-01-01
@@ -94,6 +95,21 @@ class Grouper:
 
         .. versionadded:: 1.1.0
 
+        - 'end': `origin` is the last value of the timeseries
+        - 'end_day': `origin` is the ceiling midnight of the last day
+
+        .. versionadded:: 1.2.0
+
+    backward : bool, default is None
+        Resample on the given `origin` from a backward direction. True when
+        `origin` is 'end' or 'end_day'. False when `origin` is 'start' or
+        'start_day'. Optional when using datetime `origin` , and default
+        False. The resample result for a specified datetime stands for the
+        group from time substract the given `freq` to time with a right
+        `closed` setting by default.
+
+        .. versionadded:: 1.2.0
+
     offset : Timedelta or str, default is None
         An offset timedelta added to the origin.
 
@@ -200,6 +216,15 @@ class Grouper:
     2000-10-02 00:15:00    45
     Freq: 17T, dtype: int64
 
+    If you want to take the last timestamp as `origin` with a backward resample:
+
+    >>> ts.groupby(pd.Grouper(freq='17min', origin='end')).sum()
+    2000-10-01 23:35:00     0
+    2000-10-01 23:52:00    18
+    2000-10-02 00:09:00    27
+    2000-10-02 00:26:00    63
+    Freq: 17T, dtype: int64
+
     If you want to adjust the start of the bins with an `offset` Timedelta, the two
     following lines are equivalent:
 

pandas/core/resample.py

@@ -1366,6 +1366,7 @@ def __init__(
         convention: Optional[str] = None,
         base: Optional[int] = None,
         origin: Union[str, TimestampConvertibleTypes] = "start_day",
+        backward: Optional[bool] = None,
         offset: Optional[TimedeltaConvertibleTypes] = None,
         **kwargs,
     ):
@@ -1389,9 +1390,15 @@ def __init__(
                 label = "right"
         else:
             if closed is None:
-                closed = "left"
+                if origin in ["end", "end_day"] or backward:
+                    closed = "right"
+                else:
+                    closed = "left"
             if label is None:
-                label = "left"
+                if origin in ["end", "end_day"] or backward:
+                    label = "right"
+                else:
+                    label = "left"
 
         self.closed = closed
         self.label = label
@@ -1404,17 +1411,37 @@ def __init__(
         self.fill_method = fill_method
         self.limit = limit
 
-        if origin in ("epoch", "start", "start_day"):
+        if origin in ("epoch", "start", "start_day", "end", "end_day"):
             self.origin = origin
         else:
             try:
                 self.origin = Timestamp(origin)
             except Exception as e:
                 raise ValueError(
-                    "'origin' should be equal to 'epoch', 'start', 'start_day' or "
-                    f"should be a Timestamp convertible type. Got '{origin}' instead."
+                    "'origin' should be equal to 'epoch', 'start', 'start_day', "
+                    "'end', 'end_day' or should be a Timestamp convertible "
+                    f"type. Got '{origin}' instead."
                 ) from e
 
+        if backward is None:
+            if self.origin in ("end", "end_day"):
+                self.backward = True
+            else:
+                self.backward = False
+        elif backward:
+            if origin in ("start", "start_day"):
+                raise ValueError(
+                    "`start` or `start_day` origin isn't allowed when "
+                    "`backward` is True"
+                )
+            self.backward = backward
+        else:
+            if origin in ("end", "end_day"):
+                raise ValueError(
+                    "`end` or `end_day` origin isn't allowed when `backward` is False"
+                )
+            self.backward = backward
+
         try:
             self.offset = Timedelta(offset) if offset is not None else None
         except Exception as e:
@@ -1502,6 +1529,7 @@ def _get_time_bins(self, ax):
             self.freq,
             closed=self.closed,
             origin=self.origin,
+            backward=self.backward,
             offset=self.offset,
         )
         # GH #12037
@@ -1655,6 +1683,7 @@ def _get_period_bins(self, ax: PeriodIndex):
                 self.freq,
                 closed=self.closed,
                 origin=self.origin,
+                backward=self.backward,
                 offset=self.offset,
             )
 
@@ -1708,7 +1737,7 @@ def _take_new_index(obj, indexer, new_index, axis=0):
 
 
 def _get_timestamp_range_edges(
-    first, last, freq, closed="left", origin="start_day", offset=None
+    first, last, freq, closed="left", origin="start_day", backward=False, offset=None
 ):
     """
     Adjust the `first` Timestamp to the preceding Timestamp that resides on
@@ -1761,7 +1790,13 @@ def _get_timestamp_range_edges(
                 origin = origin.tz_localize(None)
 
         first, last = _adjust_dates_anchored(
-            first, last, freq, closed=closed, origin=origin, offset=offset
+            first,
+            last,
+            freq,
+            closed=closed,
+            origin=origin,
+            backward=backward,
+            offset=offset,
         )
         if isinstance(freq, Day):
             first = first.tz_localize(index_tz)
@@ -1781,7 +1816,7 @@ def _get_timestamp_range_edges(
 
 
 def _get_period_range_edges(
-    first, last, freq, closed="left", origin="start_day", offset=None
+    first, last, freq, closed="left", origin="start_day", backward=False, offset=None
 ):
     """
     Adjust the provided `first` and `last` Periods to the respective Period of
@@ -1823,7 +1858,13 @@ def _get_period_range_edges(
     adjust_last = freq.is_on_offset(last)
 
     first, last = _get_timestamp_range_edges(
-        first, last, freq, closed=closed, origin=origin, offset=offset
+        first,
+        last,
+        freq,
+        closed=closed,
+        origin=origin,
+        backward=backward,
+        offset=offset,
     )
 
     first = (first + int(adjust_first) * freq).to_period(freq)
@@ -1832,7 +1873,7 @@ def _get_period_range_edges(
 
 
 def _adjust_dates_anchored(
-    first, last, freq, closed="right", origin="start_day", offset=None
+    first, last, freq, closed="right", origin="start_day", backward=False, offset=None
 ):
     # First and last offsets should be calculated from the start day to fix an
     # error cause by resampling across multiple days when a one day period is
@@ -1844,8 +1885,19 @@ def _adjust_dates_anchored(
         origin_nanos = first.normalize().value
     elif origin == "start":
         origin_nanos = first.value
-    elif isinstance(origin, Timestamp):
-        origin_nanos = origin.value
+    elif isinstance(origin, Timestamp) or origin in ("end", "end_day"):
+        if backward:
+            if origin == "end":
+                origin = last
+            elif origin == "end_day":
+                origin = last.ceil("D")
+            sub_freq_times = (origin.value - first.value) // freq.nanos
+            if closed == "left":
+                sub_freq_times += 1
+            first = origin - sub_freq_times * freq
+            origin_nanos = first.value
+        else:
+            origin_nanos = origin.value
     origin_nanos += offset.value if offset else 0
 
     # GH 10117 & GH 19375. If first and last contain timezone information,

pandas/tests/resample/test_datetime_index.py

@@ -770,8 +770,8 @@ def test_resample_bad_origin(origin):
     rng = date_range("2000-01-01 00:00:00", "2000-01-01 02:00", freq="s")
     ts = Series(np.random.randn(len(rng)), index=rng)
     msg = (
-        "'origin' should be equal to 'epoch', 'start', 'start_day' or "
-        f"should be a Timestamp convertible type. Got '{origin}' instead."
+        "'origin' should be equal to 'epoch', 'start', 'start_day', 'end', 'end_day' "
+        f"or should be a Timestamp convertible type. Got '{origin}' instead."
     )
     with pytest.raises(ValueError, match=msg):
         ts.resample("5min", origin=origin)