图表显示

根据 dvc.yaml 中定义的任何 plots 生成图表（或其他目标文件）。

概要

usage: dvc plots show [-h] [-q | -v] [-t <name_or_path>] [-x <field>]
                      [-y <field>] [--no-header] [--title <text>]
                      [--x-label <text>] [--y-label <text>] [-o <path>]
                      [--show-vega] [--open] [--html-template <path>]
                      [targets [targets ...]]

positional arguments:
  targets               Plots files or plot IDs from `dvc.yaml` to
                        visualize. Shows all plots by default.

描述

此命令提供了一种快速可视化特定数据的方法，例如损失函数、AUC 曲线、混淆矩阵等。

默认情况下，使用 dvc.yaml 中定义的所有图表，但您可以指定任何 targets，这些可以是图表文件，或在 dvc.yaml 中任意位置定义的非文件图表 ID，或任何其他文件（它们不一定需要在 dvc.yaml 中定义）。

可通过图表模板使用 --template 选项自定义图表样式。有关图表文件格式和模板的更多信息，请参见 dvc plots。

选项

-o <路径>, --out <路径> - 指定用于写入包含图表的 HTML 文件的目录。默认为 dvc_plots，或由 plots.out_dir 配置选项设置的值。
-t <名称或路径>, --template <名称或路径> - 要注入数据的图表模板。默认模板为 .dvc/plots/default.json。更多详情请参见 dvc plots。
-x <字段> - X 轴数据来源的字段名称。默认使用自动生成的 index 字段。有关此 index 字段的更多信息，请参见自定义模板。对于表格型图表文件，需提供列名或列号。
-y <字段> - Y 轴数据来源的字段名称。默认使用 targets 中找到的最后一个字段。对于表格型图表文件，需提供列名或列号。
--x-label <文本> - X 轴标签。默认为 X 字段名称。
--y-label <文本> - Y 轴标签。默认为 Y 字段名称。
--title <文本> - 图表标题。
--show-vega - 生成 Vega-Lite 规范文件而非 HTML 文件。更多信息请参见 dvc plots。
--open - 自动在浏览器中打开生成的 HTML 文件。您可通过启用 dvc config plots.auto_open 使其成为默认行为。
--no-header - 告知 DVC CSV 或 TSV targets 文件没有标题行。此时可使用从 0 开始的数字索引代替列名来标识各列。
--html-template <路径> - 自定义 HTML 模板的路径。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例：分层数据

本示例将使用分层指标文件 train.json：

{
  "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 }
  ]
}

展开以查看 YAML 格式

以下是对应的 train.yaml 指标文件：

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

DVC 会识别并绘制文件中第一个 JSON 数组（train）中的 JSON 对象：

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

请注意，默认情况下仅使用最后一个字段名称（loss）进行绘图。

使用 -y 选项更改要绘制的字段：

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

示例：表格数据

我们将使用表格指标文件 `logs.csv` 来进行以下示例：

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

展开以查看 TSV 格式

以下是对应的 `train.tsv` 指标文件：

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

默认情况下，此命令会绘制表格的最后一列（参见 `-y` 选项）：

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

使用 `-y` 选项更改要绘制的列：

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

无标题表

没有标题的表格数据文件可通过 `--no-header` 选项绘制。列可通过其数值位置（从 `0` 开始）使用 `-y` 指定：

$ dvc plots show --no-header logs.csv -y 2
file:///Users/usr/src/dvc_plots/index.html

示例：`dvc.yaml` 绘图

最小绘图配置

我们使用以下 `logs.csv` 数据：

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

我们可以在 dvc.yaml 中放置的最简绘图配置是数据源路径：

stages:
  train:
    cmd: ...

plots:
  - logs.csv

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

我们也可以对其进行自定义：

plots:
  - logs.csv:
      x: epoch
      y: accuracy
      title: Displaying accuracy
      x_label: This is epoch
      y_label: This is accuracy

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

多数据系列绘图

`training_data.csv` 中的数据：

epoch,train_loss,test_loss
1,0.33,0.4
2,0.3,0.28
3,0.2,0.25
4,0.1,0.23

在 dvc.yaml 中的绘图定义：

plots:
  - test_vs_train_loss:
      x: epoch
      y:
        training_data.csv: [test_loss, train_loss]
      title: Compare loss training versus test

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

从不同文件中获取数据

我们来准备一个比较，对比 `train_classes.csv` 和 `test_classes.csv` 数据集的混淆矩阵数据（如下）：

actual_class,predicted_class
dog,dog
dog,dog
dog,dog
dog,bird
cat,cat
cat,cat
cat,cat
cat,dog
bird,bird
bird,bird
bird,bird
bird,dog

actual_class,predicted_class
dog,dog
dog,dog
dog,cat
bird,bird
bird,bird
bird,cat
cat,cat
cat,cat
cat,bird

在 dvc.yaml 中：

plots:
  - test_vs_train_confusion:
      x: actual_class
      y:
        train_classes.csv: predicted_class
        test_classes.csv: predicted_class
      title: Compare test vs train confusion matrix
      template: confusion
      x_label: Actual class
      y_label: Predicted class

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

从不同文件中获取 `x` 和 `y` 数据

实际类别和预测类别可能来自不同的数据源：

actual_class
dog
dog
dog
bird
bird
bird
cat
cat
cat

predicted_class
dog
dog
cat
bird
bird
cat
cat
cat
bird

在 dvc.yaml 中：

plots:
  - confusion:
      x:
        actual.csv: actual_class
      y:
        preds.csv: predicted_class
      template: confusion

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

示例：Vega-Lite 规范文件

在许多自动化场景（如机器学习的 CI/CD）中，输出 Vega-Lite 规范文件比渲染 HTML 图表更为方便。例如，生成其他图像格式（如 PNG 或 JPEG），或以不同方式将其集成到网页或移动应用中。`--show-vega` 选项可防止将此图表规范包装在 HTML 中，而是将生成的 JSON 输出到标准输出：

$ dvc plots show --show-vega logs.csv -y accuracy

{
    "$schema": "https://vega.github.io/schema/vega-lite/v4.json",
    "data": {
        "values": [
    {
        "accuracy": "0.9418667",
    ...

自定义 HTML 模板

可通过使用 `--html-template` 选项为 dvc plots show 和 dvc plots diff 提供一个 HTML 文件。这允许您自定义 DVC 注入其生成图表的容器。

⚠️ 此功能与自定义 Vega-Lite 模板是独立的。

此 HTML 文件的唯一要求是使用 `{plot_divs}` 标记指定注入图表的位置。请参阅下方使用此功能在无网络连接环境下渲染 DVC 图表的示例。

示例：离线 HTML 模板

dvc plots 生成的图表使用 Vega-Lite JavaScript 库，默认情况下会加载在线资源。有时您可能需要在无网络连接的情况下生成图表，或希望自定义图表输出以添加额外内容（如横幅或额外文本）。DVC 允许替换包含最终图表的 HTML 文件。

将 Vega-Lite 库下载到您将生成 dvc plots 的目录中：

$ wget https://cdn.jsdelivr.net/npm/vega@5.20.2 -O my_vega.js
$ wget https://cdn.jsdelivr.net/npm/vega-lite@5.1.0 -O my_vega_lite.js
$ wget https://cdn.jsdelivr.net/npm/vega-embed@6.18.2 -O my_vega_embed.js

创建以下 HTML 文件，并将其保存为 .dvc/plots/mypage.html：

<html>
  <head>
    <script src="../path/to/my_vega.js" type="text/javascript"></script>
    <script src="../path/to/my_vega_lite.js" type="text/javascript"></script>
    <script src="../path/to/my_vega_embed.js" type="text/javascript"></script>
  </head>
  <body>
    {plot_divs}
  </body>
</html>

请注意，这是一个标准的 HTML 文件，仅包含 {plot_divs} 作为 DVC 注入图表的占位符。此文件中的 <script> 标签指向我们上述下载的本地 JavaScript 库。我们可以这样使用它：

$ dvc plots show --html-template .dvc/plots/mypage.html

您还可以通过将 DVC 配置选项 plots.html_template 设置为此文件，使其成为默认 HTML 模板。

$ dvc config plots.html_template plots/mypage.html

请注意，传递给 dvc config plots.html_template 的路径是相对于 .dvc/ 目录的相对路径。

示例：平滑图表

在某些情况下，我们希望对图表进行平滑处理。在此示例中，我们将使用包含 100 个数据点的噪声图表：

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

我们可以使用 -t（--template）选项和 smooth 模板来减少噪声：

$ dvc plots show -t smooth data.csv
file:///Users/usr/src/dvc_plots/index.html

示例：混淆矩阵

本示例将使用 classes.csv：

actual,predicted
cat,cat
cat,cat
cat,cat
cat,dog
cat,dinosaur
cat,dinosaur
cat,bird
turtle,dog
turtle,cat
...

让我们可视化它：

$ dvc plots show classes.csv --template confusion \
                             -x actual -y predicted
file:///Users/usr/src/dvc_plots/index.html

DVC 中已预定义了混淆矩阵模板。

我们可以使用 confusion_normalized 模板来归一化结果：

$ dvc plots show classes.csv -t confusion_normalized \
                             -x actual -y predicted
file:///Users/usr/src/dvc_plots/index.html

示例：水平条形图

这是一个简单的条形图，适用于例如可视化模型特征重要性。

本示例将使用 importances.csv：

feature_name,feature_importance
petal_width,0.4
petal_length,0.33
sepal_width,0.24
sepal_length,0.03

让我们可视化它：

$ dvc plots show importances.csv --template bar_horizontal \
                             -x feature_importance -y feature_name
file:///Users/usr/src/dvc_plots/index.html

使用 bar_horizontal 模板时，图表将按垂直轴排序（在我们的示例中，这意味着按特征名称字母顺序排序）。

如果您希望按水平轴排序（例如按特征重要性排序），可以改用 bar_horizontal_sorted 模板：

$ dvc plots show importances.csv -t bar_horizontal_sorted \
                             -x feature_importance -y feature_name
file:///Users/usr/src/dvc_plots/index.html

示例：散点图

让我们使用如下所示的 probs.json，绘制实际数值类别与对应预测概率的散点图：

[
  {"actual": 7, "prob": 0.2525983154773712},
  {"actual": 1, "prob": 0.6300574541091919},
  ...
]

$ dvc plots show probs.json -t scatter \
                             -x actual -y prob
file:///Users/usr/src/dvc_plots/index.html