feat: add learning curve method (#1568)

* implement learning curve

* add learning curve to integration to verify functionality

* edit Mapping from tensor to any

* Updated learning_curve to target each metric by name instead of relying on column position

---------

Co-authored-by: Mario Behling <mb@mariobehling.de>

Author: tonypzy

README.md

@@ -285,6 +285,7 @@ The following API is currently supported:
 - [`vis.scatter`](#visscatter)  : 2D or 3D scatter plots
 - [`vis.sunburst`](#vissunburst)  : sunburst (hierarchy) charts
 - [`vis.line`](#visline)     : line plots
+- [`vis.learning_curve`](#vislearning_curve) : named training metric curves
 - [`vis.stem`](#visstem)     : stem plots
 - [`vis.heatmap`](#visheatmap)  : heatmap plots
 - [`vis.confusion_matrix`](#visconfusion_matrix)  : confusion matrix plots
@@ -581,6 +582,29 @@ The following `opts` are supported:
 - `opts.layoutopts` : additional backend layout options (`dict`)
 
 
+#### vis.learning_curve
+This function draws named machine-learning metrics as line plots. It accepts a mapping from metric names to scalar values or equal-length 1D series and forwards to [`vis.line`](#visline).
+
+For example:
+
+```python
+win = vis.learning_curve(
+    {"train_loss": [1.0, 0.8, 0.6], "val_loss": [1.1, 0.9, 0.7]},
+    step=[1, 2, 3],
+    env="training",
+    opts={"title": "Loss", "ylabel": "loss"},
+)
+
+vis.learning_curve(
+    {"train_loss": 0.55, "val_loss": 0.68},
+    step=4,
+    win=win,
+    env="training",
+    update="append",
+)
+```
+
+
 #### vis.stem
 This function draws a stem plot. It takes as input an `N` or `NxM` tensor
 `X` that specifies the values of the `N` points in the `M` time series.

cypress/integration/pane.js

@@ -17,6 +17,7 @@ const basic_examples = [
   // ["Mesh Plot", "plot_special_mesh"], // disabled due to webgl
   ['Graph Plot', 'plot_special_graph'],
   ['Sankey Plot', 'plot_special_sankey'],
+  ['Learning Curve', 'plot_line_learning_curve'],
   ['Matplotlib Plot', 'misc_plot_matplot'],
   ['Latex Plot', 'misc_plot_latex'],
   ['Video Pane', 'misc_video_tensor'],

example/components/plot_line.py

@@ -114,6 +114,33 @@ def plot_line_many_updates(viz, env, args):
         )
 
 
+def plot_line_learning_curve(viz, env, args):
+    epochs = np.arange(1, 11)
+    train_loss = np.exp(-epochs / 4.0) + 0.08 * np.random.rand(len(epochs))
+    val_loss = np.exp(-epochs / 3.7) + 0.12 * np.random.rand(len(epochs)) + 0.08
+    win = viz.learning_curve(
+        {
+            "train_loss": train_loss,
+            "val_loss": val_loss,
+        },
+        step=epochs,
+        opts={"title": "Learning curve", "ylabel": "loss"},
+        env=env,
+    )
+
+    for epoch in range(11, 16):
+        viz.learning_curve(
+            {
+                "train_loss": np.exp(-epoch / 4.0),
+                "val_loss": np.exp(-epoch / 3.7) + 0.08,
+            },
+            step=epoch,
+            win=win,
+            update="append",
+            env=env,
+        )
+
+
 def plot_line_opts(viz, env, args):
     return viz.line(
         X=np.column_stack(

example/demo.py

@@ -73,6 +73,7 @@
     plot_line_pytorch,
     plot_line_stem,
     plot_line_many_updates,
+    plot_line_learning_curve,
 )
 from components.plot_special import (
     plot_special_boxplot,
@@ -149,6 +150,7 @@ def run_demo(viz, env, args):
     plot_line_doubleyaxis(viz, env, args)
     plot_line_pytorch(viz, env, args)
     plot_line_stem(viz, env, args)
+    plot_line_learning_curve(viz, env, args)
 
     # ============= #
     # scatter plots #

py/visdom/__init__.py

@@ -2034,6 +2034,113 @@ def update_window_opts(self, win, opts, env=None):
         }
         return self._send(data_to_send, endpoint="update")
 
+    @pytorch_wrap
+    def learning_curve(
+        self,
+        metrics,
+        step=None,
+        win=None,
+        env=None,
+        opts=None,
+        update=None,
+    ):
+        """
+        This function draws machine-learning learning curves using named metrics.
+        It is a convenience wrapper around `line`, accepting a mapping from metric
+        names to scalar values or equal-length 1D series.
+
+        `metrics` should be a non-empty mapping, for example:
+
+            {"train_loss": [1.0, 0.8], "val_loss": [1.1, 0.9]}
+
+        `step` can be a scalar or a 1D series matching the metric length. When
+        `update='append'`, `step` must be specified to avoid repeatedly appending
+        points at the same x-coordinate.
+        """
+        assert hasattr(metrics, "items"), "metrics should be a mapping"
+        metric_items = list(metrics.items())
+        assert len(metric_items) > 0, "must provide at least one metric"
+
+        names = []
+        series = []
+        for metric_name, metric_values in metric_items:
+            name = str(metric_name)
+            values = np.asarray(_to_numpy(metric_values))
+            values = np.squeeze(values)
+            if values.ndim == 0:
+                values = values.reshape(1)
+            assert (
+                values.ndim == 1
+            ), "metric '{}' should be a scalar or one-dimensional".format(name)
+            assert values.shape[0] > 0, "metric '{}' should not be empty".format(name)
+            names.append(name)
+            series.append(values)
+
+        num_steps = series[0].shape[0]
+        for name, values in zip(names, series):
+            assert (
+                values.shape[0] == num_steps
+            ), "metric '{}' has length {}, expected {}".format(
+                name, values.shape[0], num_steps
+            )
+
+        if step is None:
+            assert update != "append", "must specify step when update='append'"
+            X = np.arange(num_steps)
+        else:
+            X = np.asarray(_to_numpy(step))
+            X = np.squeeze(X)
+            if X.ndim == 0:
+                X = X.reshape(1)
+            assert X.ndim == 1, "step should be a scalar or one-dimensional"
+            assert X.shape[0] == num_steps, "step has length {}, expected {}".format(
+                X.shape[0], num_steps
+            )
+
+        opts = {} if opts is None else dict(opts)
+        opts.setdefault("title", "Learning Curve")
+        opts.setdefault("xlabel", "step")
+        opts.setdefault("ylabel", "metric")
+        if opts.get("legend") is None:
+            legend = names
+            opts["legend"] = legend
+        else:
+            legend = opts["legend"]
+            assert isinstance(legend, (tuple, list)), "legend should be a list or tuple"
+            assert len(legend) >= len(
+                names
+            ), "legend should have at least as many entries as metrics"
+
+        if update is not None:
+            result = None
+            # Send one named update per metric so mapping order cannot swap traces.
+            for name, values in zip(names, series):
+                metric_opts = None
+                if update != "remove":
+                    metric_opts = dict(opts)
+                    metric_opts["legend"] = [name]
+                result = self.line(
+                    X=X,
+                    Y=values,
+                    win=win,
+                    env=env,
+                    opts=metric_opts,
+                    update=update,
+                    name=name,
+                )
+            return result
+
+        Y = np.column_stack(series)
+
+        return self.line(
+            X=X,
+            Y=Y,
+            win=win,
+            env=env,
+            opts=opts,
+            update=update,
+        )
+
     @pytorch_wrap
     def scatter(self, X, Y=None, win=None, env=None, opts=None, update=None, name=None):
         """

py/visdom/__init__.pyi

@@ -127,6 +127,15 @@ class Visdom:
     def update_window_opts(
         self, win: Text, opts: Mapping[Text, Any], env: _OptStr = ...
     ) -> _SendReturn: ...
+    def learning_curve(
+        self,
+        metrics: Mapping[Text, Any],
+        step: Optional[Tensor] = ...,
+        win: _OptStr = ...,
+        env: _OptStr = ...,
+        opts: _OptOps = ...,
+        update: _OptStr = ...,
+    ) -> _SendReturn: ...
     def scatter(
         self,
         X: Tensor,