Feat/plotly support (#2985)

Author: brunnedu

CHANGELOG.md

@@ -11,6 +11,16 @@ but cannot always guarantee backwards compatibility. Changes that may **break co
 
 **Improved**
 
+- Added `TimeSeries.plotly()` method for interactive time series visualization using Plotly backend. [#2977](https://github.com/unit8co/darts/pull/2977) by [Dustin Brunner](https://github.com/brunnedu).
+  - Provides interactive plotting with zoom, pan, hover tooltips, and legend interactions
+  - Maintains API consistency with the existing `plot()` method for easy adoption
+  - Supports deterministic and stochastic, univariate and multivariate series
+  - Allows overlaying multiple series on the same figure via the `fig` parameter
+  - Customizable trace styling via `**kwargs`
+  - Includes automatic downsampling for large series (configurable via `downsample_threshold` parameter) to avoid crashes when plotting large series
+  - Integrates seamlessly with `plotting.use_darts_style` which now affects both `TimeSeries.plot()` and `TimeSeries.plotly()`
+  - Plotly remains an optional dependency and can be installed with `pip install plotly`
+
 **Fixed**
 
 - Fixed bug in `StaticCovariatesTransformer` where one-hot encoded column names were incorrectly assigned when the order of columns specified in `cols_cat` differed from the actual data column order. This caused silent data corruption where column names combined wrong feature names with wrong category values (e.g., `City_US` instead of `Country_US`). [#2989](https://github.com/unit8co/darts/pull/2989) by [Dustin Brunner](https://github.com/brunnedu).

darts/config.py

@@ -22,9 +22,9 @@
 **Plotting Options**
 
 - ``plotting.use_darts_style`` : bool (default: False)
-    Whether to apply Darts' custom matplotlib plotting style. When True, Darts will configure
-    matplotlib with a custom style optimized for time series visualization. When False, matplotlib's
-    default or user-configured style will be used. Changes to this option take effect immediately.
+    Whether to apply Darts' custom plotting style to both matplotlib and plotly. When True, Darts will
+    configure both backends with a custom style optimized for time series visualization. When False,
+    the default or user-configured styles will be used. Changes to this option take effect immediately.
 
 Examples
 ========
@@ -50,6 +50,17 @@
 
 logger = get_logger(__name__)
 
+# Darts color palette used for both matplotlib and plotly plotting
+_DARTS_COLORS = [
+    "#000000",
+    "#003dfd",
+    "#b512b8",
+    "#11a9ba",
+    "#0d780f",
+    "#f77f07",
+    "#ba0f0f",
+]
+
 
 class _Option:
     """Internal class representing a single configuration option."""
@@ -117,10 +128,9 @@ def __init__(self):
         plotting_use_darts_style = _Option(
             key="plotting.use_darts_style",
             default_value=False,
-            description="Whether to apply Darts' custom matplotlib plotting style. "
-            "When True, Darts will configure matplotlib with a custom style optimized for "
-            "time series visualization. When False, matplotlib's default or user-configured "
-            "style will be used.",
+            description="Whether to apply Darts' custom plotting style to both matplotlib and plotly. "
+            "When True, Darts will configure both backends with a custom style optimized for "
+            "time series visualization. When False, the default or user-configured styles will be used.",
             validator=self._validate_bool,
             callback=self._on_plotting_style_change,
         )
@@ -134,7 +144,10 @@ def __init__(self):
             ]
         }
         # remember if user applied Darts style
-        self._mpl_style_applied = False
+        self._darts_plotting_style_applied = False
+        # store original templates to restore later
+        self._original_plotly_template = None
+        self._original_mpl_params = None
 
     @staticmethod
     def _validate_positive_int(value: Any):
@@ -150,43 +163,101 @@ def _validate_bool(value: Any):
 
     def _on_plotting_style_change(self, value: bool) -> None:
         """Callback for when plotting.use_darts_style changes."""
+        # matplotlib
         import matplotlib as mpl
         from matplotlib import cycler
 
-        if not value and self._mpl_style_applied:
-            # restore default options
-            mpl.rcParams.update(mpl.rcParamsDefault)
-            self._mpl_style_applied = False
-            return
-
-        # apply Darts plotting style
-        colors = cycler(
-            color=["black", "003DFD", "b512b8", "11a9ba", "0d780f", "f77f07", "ba0f0f"]
-        )
-
-        u8plots_mplstyle = {
-            "font.family": "sans serif",
-            "axes.edgecolor": "black",
-            "axes.grid": True,
-            "axes.labelcolor": "#333333",
-            "axes.labelweight": 600,
-            "axes.linewidth": 1,
-            "axes.prop_cycle": colors,
-            "axes.spines.top": False,
-            "axes.spines.right": False,
-            "axes.spines.bottom": False,
-            "axes.spines.left": False,
-            "grid.color": "#dedede",
-            "legend.frameon": False,
-            "lines.linewidth": 1.3,
-            "xtick.color": "#333333",
-            "xtick.labelsize": "small",
-            "ytick.color": "#333333",
-            "ytick.labelsize": "small",
-            "xtick.bottom": False,
-        }
-        mpl.rcParams.update(u8plots_mplstyle)
-        self._mpl_style_applied = True
+        if value:
+            # store current matplotlib params before applying darts style
+            if not self._darts_plotting_style_applied:
+                self._original_mpl_params = mpl.rcParams.copy()
+
+            # apply Darts plotting style to matplotlib
+            colors = cycler(color=_DARTS_COLORS)
+            u8plots_mplstyle = {
+                "font.family": "sans serif",
+                "axes.edgecolor": "black",
+                "axes.grid": True,
+                "axes.labelcolor": "#333333",
+                "axes.labelweight": 600,
+                "axes.linewidth": 1,
+                "axes.prop_cycle": colors,
+                "axes.spines.top": False,
+                "axes.spines.right": False,
+                "axes.spines.bottom": False,
+                "axes.spines.left": False,
+                "grid.color": "#dedede",
+                "legend.frameon": False,
+                "lines.linewidth": 1.3,
+                "xtick.color": "#333333",
+                "xtick.labelsize": "small",
+                "ytick.color": "#333333",
+                "ytick.labelsize": "small",
+                "xtick.bottom": False,
+            }
+            mpl.rcParams.update(u8plots_mplstyle)
+        else:
+            # restore previous matplotlib options
+            if self._original_mpl_params is not None:
+                mpl.rcParams.update(self._original_mpl_params)
+                self._original_mpl_params = None
+
+        # plotly
+        try:
+            import plotly.graph_objects as go
+            import plotly.io as pio
+
+            if value:
+                # store existing default to restore later
+                if not self._darts_plotting_style_applied:
+                    self._original_plotly_template = pio.templates.default
+
+                # assign the darts plotly template directly
+                pio.templates.default = go.layout.Template(
+                    layout=go.Layout(
+                        font=dict(family="Arial, sans-serif", size=14, color="black"),
+                        paper_bgcolor="white",
+                        plot_bgcolor="white",
+                        colorway=_DARTS_COLORS,
+                        showlegend=True,
+                        legend=dict(
+                            bgcolor="rgba(255, 255, 255, 0.8)",
+                            x=1,
+                            y=1,
+                            yanchor="top",
+                            xanchor="right",
+                            font=dict(size=14),
+                            borderwidth=0,
+                        ),
+                        xaxis=dict(
+                            showline=True,
+                            linecolor="#dedede",
+                            showgrid=False,
+                            title=dict(font=dict(size=16, color="black")),
+                        ),
+                        yaxis=dict(
+                            showline=False,
+                            showgrid=True,
+                            gridcolor="#dedede",
+                            gridwidth=1,
+                            zeroline=True,
+                            zerolinecolor="#dedede",
+                        ),
+                        margin=dict(l=50, r=50, t=50, b=50),
+                    ),
+                    data=dict(scatter=[go.Scatter(line=dict(width=3))]),
+                )
+            else:
+                # restore the previous default
+                if self._original_plotly_template is not None:
+                    pio.templates.default = self._original_plotly_template
+                    self._original_plotly_template = None
+        except ImportError:
+            # plotly not available, skip plotly configuration
+            pass
+
+        # update the state tracker
+        self._darts_plotting_style_applied = value
 
     def _find_option(self, pattern: str, check_unique: bool = False) -> list[_Option]:
         """Find options matching a pattern (supports both exact match and prefix match)."""

darts/tests/conftest.py

@@ -103,6 +103,14 @@
     logger.warning("Polars not installed - Some tests will be skipped.")
     POLARS_AVAILABLE = False
 
+try:
+    import plotly  # noqa: F401
+
+    PLOTLY_AVAILABLE = True
+except ImportError:
+    logger.warning("Plotly not installed - Some tests will be skipped.")
+    PLOTLY_AVAILABLE = False
+
 tfm_kwargs: dict[str, Any] = {
     "pl_trainer_kwargs": {
         "accelerator": "cpu",

darts/tests/test_config.py

@@ -12,6 +12,10 @@
     reset_option,
     set_option,
 )
+from darts.tests.conftest import PLOTLY_AVAILABLE
+
+if PLOTLY_AVAILABLE:
+    import plotly.io as pio
 
 
 @pytest.fixture(scope="function", autouse=True)
@@ -233,8 +237,48 @@ def test_plotting_no_user_style_override_on_reset(self):
         reset_option("plotting.use_darts_style")
         assert mpl.rcParams == user_style
 
-        # Setting Darts style will override this behavior
+        # Setting Darts style and resetting should restore user's style
         set_option("plotting.use_darts_style", True)
         reset_option("plotting.use_darts_style")
-        assert mpl.rcParams != user_style
-        assert mpl.rcParams == mpl.rcParamsDefault
+        assert mpl.rcParams == user_style
+
+    @pytest.mark.skipif(not PLOTLY_AVAILABLE, reason="requires plotly")
+    def test_plotting_style_callback_plotly(self):
+        """Test that changing plotting.use_darts_style updates plotly template."""
+        # Store original template
+        original_template = pio.templates.default
+
+        # Apply Darts style
+        set_option("plotting.use_darts_style", True)
+        assert pio.templates.default != original_template
+        darts_template = pio.templates.default
+
+        # Remove Darts style
+        set_option("plotting.use_darts_style", False)
+        assert pio.templates.default == original_template
+
+        # Re-apply Darts style
+        set_option("plotting.use_darts_style", True)
+        assert pio.templates.default == darts_template
+
+        # Reset style
+        reset_option("plotting.use_darts_style")
+        assert pio.templates.default == original_template
+
+    @pytest.mark.skipif(not PLOTLY_AVAILABLE, reason="requires plotly")
+    def test_plotting_no_user_template_override_on_reset_plotly(self):
+        """Test that resetting plotting.use_darts_style preserves user's plotly template."""
+        # Set a custom template
+        pio.templates.default = "plotly_dark"
+        user_template = pio.templates.default
+        assert user_template == "plotly_dark"
+
+        # Resetting style should not override user's template
+        reset_option("plotting.use_darts_style")
+        assert pio.templates.default == user_template
+
+        # Setting Darts style and resetting should restore user's template
+        set_option("plotting.use_darts_style", True)
+        assert pio.templates.default != user_template
+        reset_option("plotting.use_darts_style")
+        assert pio.templates.default == user_template

darts/tests/test_timeseries_plot.py

@@ -211,17 +211,6 @@ def test_plot_stochastic_params(self, mock_show, config):
         plt.show()
         plt.close()
 
-    @patch("matplotlib.pyplot.show")
-    @pytest.mark.parametrize("config", ["dt", "ri"])
-    def test_plot_multiple_series(self, mock_show, config):
-        index_type = config
-        series1 = getattr(self, f"series_{index_type}_d")
-        series2 = getattr(self, f"series_{index_type}_p")
-        series1.plot()
-        series2.plot()
-        plt.show()
-        plt.close()
-
     @patch("matplotlib.pyplot.show")
     @pytest.mark.parametrize("config", ["dt", "ri"])
     def test_plot_deterministic_and_stochastic(self, mock_show, config):