diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b7b1eaa22..277b306743 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,9 +11,11 @@ but cannot always guarantee backwards compatibility. Changes that may **break co **Improved** +- Added a warning when calling `TimeSeries.values()` without specifying a sample for a stochastic time series. - Improvements to `TimeSeries` : - `__pow__` now supports raising to negative powers (as series, arrays or scalars). E.g. `series ** (-2)`. [#3298](https://github.com/unit8co/darts/pull/3298) by [Gabriel Demetrios Lafis](https://github.com/galafis). - - `__truediv__` now supports dividing by zeros (as series, arrays or scalars). E.g. `series / 0.` [#3298](https://github.com/unit8co/darts/pull/3298) by [Gabriel Demetrios Lafis](https://github.com/galafis). + - `__truediv__` now supports dividing by zeros (as series, arrays or scalars). E.g. `series / 0.`. [#3298](https://github.com/unit8co/darts/pull/3298) by [Gabriel Demetrios Lafis](https://github.com/galafis). + - Added a warning when calling `values()` on stochastic series without specifying a sample. [#3307](https://github.com/unit8co/darts/pull/3307) by [Pallav Biyala](https://github.com/Pallav-Biyala). **Fixed** diff --git a/darts/tests/test_timeseries.py b/darts/tests/test_timeseries.py index 556edbc296..b76302f8f8 100644 --- a/darts/tests/test_timeseries.py +++ b/darts/tests/test_timeseries.py @@ -2417,6 +2417,30 @@ def test_mutability_times(self): assert ts.time_index.equals(idx) + def test_values_stochastic_warning(self, caplog): + ts = TimeSeries.from_values(np.arange(30).reshape(10, 1, 3)) + msg = "stochastic series only extracts values of a single sample" + with caplog.at_level(logging.WARNING): + values = ts.values() + + assert msg in caplog.text + np.testing.assert_array_equal(values, ts.all_values()[:, :, 0]) + caplog.clear() + + with caplog.at_level(logging.WARNING): + values = ts.values(sample=1) + + assert msg not in caplog.text + np.testing.assert_array_equal(values, ts.all_values()[:, :, 1]) + caplog.clear() + + with caplog.at_level(logging.WARNING): + values = TimeSeries.from_values(ts.values(sample=1)).values() + + assert msg not in caplog.text + np.testing.assert_array_equal(values, ts.all_values()[:, :, 1]) + caplog.clear() + def helper_test_slice(test_series: TimeSeries): # base case diff --git a/darts/timeseries.py b/darts/timeseries.py index 7d5616195d..b39e8f3386 100644 --- a/darts/timeseries.py +++ b/darts/timeseries.py @@ -2050,7 +2050,7 @@ def last_values(self) -> np.ndarray: self._assert_deterministic() return self._values[-1, :, 0].copy() - def values(self, copy: bool = True, sample: int = 0) -> np.ndarray: + def values(self, copy: bool = True, sample: int | None = None) -> np.ndarray: """Return a 2-D array of shape (time, component), containing the series' values for one `sample`. Parameters @@ -2059,13 +2059,24 @@ def values(self, copy: bool = True, sample: int = 0) -> np.ndarray: Whether to return a copy of the values, otherwise returns a view. Leave it to True unless you know what you are doing. sample - For stochastic series, the sample for which to return values. Default: 0 (first sample). + For stochastic series, the sample for which to return values. + If omitted, sample 0 is returned with a warning. Default: None Returns ------- numpy.ndarray The values composing the time series. """ + if sample is None: + if self.is_stochastic: + logger.warning( + "`TimeSeries.values()` on stochastic series only extracts values of a single sample " + "(sample 0 by default). For meaningful results, use `TimeSeries.all_values()` to extract " + "all sample values or any other series statistic / aggregate such as `mean()`, " + "`quantile()`, ..." + ) + sample = 0 + if self.is_deterministic and sample != 0: raise_log( ValueError(