feature/cumsum (#1988)

* added cumsum function to time series

* typo in unit test function naming

* update changelog.md

* apply suggestions from pr review and extend tests

---------

Co-authored-by: eliot <[email protected]>
Co-authored-by: dennisbader <[email protected]>

CHANGELOG.md

@@ -14,9 +14,11 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 - `TimeSeries` with a `RangeIndex` starting in the negative start are now supported by `historical_forecasts`. [#1866](https://github.com/unit8co/darts/pull/1866) by [Antoine Madrona](https://github.com/madtoinou).
 - Added a new argument `start_format` to `historical_forecasts()`, `backtest()` and `gridsearch` that allows to use an integer `start` either as the index position or index value/label for `series` indexed with a `pd.RangeIndex`. [#1866](https://github.com/unit8co/darts/pull/1866) by [Antoine Madrona](https://github.com/madtoinou).
 - Added `RINorm` (Reversible Instance Norm) as an input normalization option for all `TorchForecastingModel` except `RNNModel`. Activate it with model creation parameter `use_reversible_instance_norm`. [#1969](https://github.com/unit8co/darts/pull/1969) by [Dennis Bader](https://github.com/dennisbader).
-- Reduced the size of the Darts docker image `unit8/darts:latest`, and included all optional models as well as dev requirements. [#1878](https://github.com/unit8co/darts/pull/1878) by [Alex Colpitts](https://github.com/alexcolpitts96). 
+- Reduced the size of the Darts docker image `unit8/darts:latest`, and included all optional models as well as dev requirements. [#1878](https://github.com/unit8co/darts/pull/1878) by [Alex Colpitts](https://github.com/alexcolpitts96).
+- Added method `TimeSeries.cumsum()` to get the cumulative sum over time series along the time axis. [#1988](https://github.com/unit8co/darts/pull/1988) by [Eliot Zubkoff](https://github.com/Eliotdoesprogramming).
 - Added short examples in the docstring of all the models, including covariates usage and some model-specific parameters. [#1956](https://github.com/unit8co/darts/pull/1956) by [Antoine Madrona](https://github.com/madtoinou).
 - All `RegressionModel`s now support component/column-specific lags for target, past, and future covariates series. [#1962](https://github.com/unit8co/darts/pull/1962) by [Antoine Madrona](https://github.com/madtoinou).
+- Added method `TimeSeries.cumsum()` to get the cumulative sum of the time series along the time axis. [#1988](https://github.com/unit8co/darts/pull/1988) by [Eliot Zubkoff](https://github.com/Eliotdoesprogramming).
 
 **Fixed**
 - Fixed a bug in `TimeSeries.from_dataframe()` when using a pandas.DataFrame with `df.columns.name != None`. [#1938](https://github.com/unit8co/darts/pull/1938) by [Antoine Madrona](https://github.com/madtoinou).

darts/tests/test_timeseries.py

@@ -764,6 +764,26 @@ def test_with_values(self):
         # should not fail if nr samples is not the same:
         series.with_values(np.random.rand(5, 10, 2))
 
+    def test_cumsum(self):
+        cumsum_expected = TimeSeries.from_dataframe(
+            self.series1.pd_dataframe().cumsum()
+        )
+        # univariate deterministic
+        assert self.series1.cumsum() == TimeSeries.from_dataframe(
+            self.series1.pd_dataframe().cumsum()
+        )
+        # multivariate deterministic
+        assert self.series1.stack(self.series1).cumsum() == cumsum_expected.stack(
+            cumsum_expected
+        )
+        # multivariate stochastic
+        # shape = (time steps, components, samples)
+        ts = TimeSeries.from_values(np.random.random((10, 2, 10)))
+        np.testing.assert_array_equal(
+            ts.cumsum().all_values(copy=False),
+            np.cumsum(ts.all_values(copy=False), axis=0),
+        )
+
     def test_diff(self):
         diff1 = TimeSeries.from_dataframe(self.series1.pd_dataframe().diff())
         diff2 = TimeSeries.from_dataframe(diff1.pd_dataframe().diff())

darts/timeseries.py

@@ -2570,7 +2570,7 @@ def diff(
         Returns
         -------
         TimeSeries
-            A TimeSeries constructed after differencing.
+            A new TimeSeries, with the differenced values.
         """
         if not isinstance(n, int) or n < 1:
             raise_log(ValueError("'n' must be a positive integer >= 1."), logger)
@@ -2597,6 +2597,17 @@ def _compute_diff(xa: xr.DataArray):
             new_xa = _compute_diff(new_xa)
         return self.__class__(new_xa)
 
+    def cumsum(self) -> Self:
+        """
+        Returns the cumulative sum of the time series along the time axis.
+
+        Returns
+        -------
+        TimeSeries
+            A new TimeSeries, with the cumulatively summed values.
+        """
+        return self.__class__(self._xa.copy().cumsum(axis=0))
+
     def has_same_time_as(self, other: "TimeSeries") -> bool:
         """
         Checks whether this series has the same time index as `other`.