Fix/warn when extracting stochastic TimeSeries values

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**
 

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

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(