Visualizing Plots

DVC can generate and render plots based on your project's data. A typical workflow is:

1. Save some data, for example in JSON format. This may be an ML pipeline output.

   [
       {
           "actual": "0",
           "predicted": "0"
       },
   ...

2. Define plots in dvc.yaml, optionally using templates to configure how to visualize the data.

   plots:
     # Data series source
     - eval/live/plots/sklearn/cm/test.json:
         # Configure template and axes.
         template: confusion
         x: actual
         y: predicted
   
     # Multiple data sources
     - ROC:
         x: fpr
         y:
           eval/live/plots/sklearn/roc/train.json: tpr
           eval/live/plots/sklearn/roc/test.json: tpr
   
     # Image file source
     - eval/importance.png

3. Show all plots in a single view or report.

   

4. Run experiments and compare the resulting plots.

   

Supported plot file formats

To create valid plots files, you can:

• Use DVCLive in your Python code to log the data automatically in a DVC-compatible format.
• Generate a JSON, YAML 1.2, CSV, or TSV data series file yourself.
• Save an JPEG, GIF, PNG, or SVG image file to render directly in your reports (helpful for custom visualizations that would be hard to configure in DVC).

DVC generates plots as static HTML webpages you can open with a web browser or view in VS Code via the Plots Dashboard of the DVC Extension. (they can be saved as SVG or PNG image files from there).

For data-series plots, DVC expects to see one or more arrays of objects (usually float numbers) in the file. These are rendered using Vega-Lite (declarative grammar for defining graphics).

Tabular data

In tabular file formats (CSV and TSV), each column is an array. dvc plots subcommands can produce plots for a specified column or a set of them. For example, epoch, loss, and accuracy are the column names below:

epoch,loss,accuracy
1,0.19,0.81
2,0.11,0.89
3,0.07,0.93
4,0.04,0.96

You can configure how DVC visualizes the data (see dvc plots show):

$ dvc plots show logs.csv -x epoch -y loss
file:///Users/usr/src/dvc_plots/index.html

Hierarchical data

Hierarchical file formats (JSON and YAML) should contain an array of consistent objects (sharing a common structure): All objects should contain the fields used for the X and Y axis of the plot (see DVC template anchors); Extra elements will be ignored silently.

dvc plots subcommands can produce plots for a specified field or a set of them, from the array's objects. For example, loss is one of the field names in the train array below:

{
  "train": [
    { "accuracy": 0.96658, "loss": 0.10757 },
    { "accuracy": 0.97641, "loss": 0.07324 },
    { "accuracy": 0.87707, "loss": 0.08136 },
    { "accuracy": 0.87402, "loss": 0.09026 },
    { "accuracy": 0.8795, "loss": 0.0764 },
    { "accuracy": 0.88038, "loss": 0.07608 },
    { "accuracy": 0.89872, "loss": 0.08455 }
  ]
}

You can configure how DVC visualizes the data (see dvc plots show):

$ dvc plots show train.json -y loss
file:///Users/usr/src/dvc_plots/index.html

Defining plots

In order to create visualizations, users need to provide the data and (optionally) configuration that will help customize the plot. DVC provides two ways to configure visualizations. Users can define top-level plots in dvc.yaml, or mark specific stage outputs as plots.

Top-level plots

Plots can be defined in a top-level plots key in dvc.yaml. Top-level plots can use any file found in the project.

In the simplest use, you only need to provide the plot's file path. In the example below, DVC will take data from logs.csv and use the default plotting behavior (apply the linear plot template to the last found column):

stages:
  build:
    cmd: python train.py
    outs:
      - logs.csv
  ...
plots:
  - logs.csv

$ dvc plots show
file:///Users/usr/src/dvc_plots/index.html

For customization, we can:

• Use a plot ID (ROC) that is not a file path.
• Specify one or more columns for the x (fpr) and y (tpr) axes.
• Specify one or more data sources (evaluation/train/plots/roc.json and evaluation/test/plots/roc.json) as keys to the x and y axes.
• Specify any other available configuration field (title, template, x_label, y_label).

plots:
  - ROC:
      x: fpr
      y:
        evaluation/train/plots/roc.json: tpr
        evaluation/test/plots/roc.json: tpr
      title: Train vs. Test ROC
      x_label: False Positive Rate
      y_label: True Positive Rate

$ dvc plots show
file:///Users/usr/src/dvc_plots/index.html

Plot outputs

When defining pipelines, some outputs (both files and directories) can be placed under a plots list for the corresponding stage in dvc.yaml. This will tell DVC that they are intended for visualization.

stages:
  build:
    cmd: python train.py
    plots:
      - logs.csv:
        x: epoch
        y: loss
  ...

Plotting stage outputs is convenient for working with plots at the stage level, without having to write top-level plots definitions in dvc.yaml. However, stage-level plots do not support custom plot IDs or multiple data sources.

Plot templates (data-series only)

DVC uses Vega-Lite JSON specifications to create plots from user data. A set of built-in plot templates are included.

The linear template is the default. It can be changed with the --template (-t) option of dvc plots show and dvc plots diff. The argument provided to --template can be a (built-in) template name or a path to a custom template.

DVC has the following built-in plot templates:

• linear - basic linear plot including cursor interactivity (default)
• simple - simplest linear template (not interactive); Good base to create custom templates.
• scatter - scatter plot
• smooth - linear plot with LOESS smoothing, see example
• confusion - confusion matrix, see example
• confusion_normalized - confusion matrix with values normalized to <0, 1> range
• bar_horizontal - horizontal bar plot, see example
• bar_horizontal_sorted - horizontal bar plot sorted by bar size

Note that in the case of CSV/TSV metrics files, column names from the table header (first row) are equivalent to field names.

Refer to dvc plots templates for more information on how to prepare your own template from pre-defined ones.

Comparing plots

When you run experiments or otherwise update the data in the plots files, those updates will be automatically reflected in your visualizations. To compare between experiments or Git revisions, you can use dvc plots diff, dvc exp show --pcp, or the plots dashboard from the VS Code Extension.