---

name: metrics-params-plots description: "Track, compare, inspect, and troubleshoot DVC metrics, params, and plots from CLI, dvc.yaml, and the public Python API." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

DVC Metrics, Params, and Plots

Use this sub-skill when a task is about declaring, showing, diffing, comparing, exporting, or debugging DVC metrics, params, or plots. It covers CLI reporting, dvc.yaml declarations, plot configuration, and the public dvc.api.metrics_show() / dvc.api.params_show() helpers.

Route Here For

• Metrics: dvc metrics show, dvc metrics diff, metric declarations in dvc.yaml, -m, -M, JSON/Markdown output, revision comparison, and precision behavior.
• Params: dvc params diff, params dependencies in dvc.yaml, dvc stage add -p, multiple params files, stage-scoped params, --deps, JSON/Markdown output, and Python API inspection.
• Plots: dvc plots show, dvc plots diff, dvc plots modify, dvc plots templates, top-level plots: definitions, stage plot outputs, Vega/HTML output, CSV/TSV header behavior, image plots, and plot templates.
• Python API: dvc.api.metrics_show() and dvc.api.params_show() for safe JSON-friendly summaries from scripts or notebooks.

Route Elsewhere

• Use ../data-and-pipelines/SKILL.md for stage construction basics, dvc init, dvc add, dvc repro, dvc status, dependencies, outputs, and cache lifecycle outside metrics/plots declarations.
• Use ../experiments/SKILL.md for dvc exp show, experiment tables, experiment queueing/runs, experiment comparison semantics, and experiment-specific interpretation of metrics/params.
• Use remote/cache guidance when metrics or plots cannot be read because data cache objects are missing locally and must be fetched.

Quick Decision Pattern

1. If the user wants machine-readable reporting, prefer --json for CLI commands or the bundled scripts/summarize_metrics_params.py helper.
2. If metrics or params should be generated by a pipeline, declare them on the stage (-m, -M, --plots, --plots-no-cache, and -p) before running dvc repro.
3. If the task compares revisions, use dvc metrics diff or dvc params diff; for plots, use dvc plots diff and add --json / --show-vega when browser output is not acceptable.
4. If params are unexpected, inspect both the stage params dependency declarations and the API flattening behavior for duplicate keys across files.
5. If plots fail, check data format, headers, x/y fields, template names, and whether the plot target is a stage output or a top-level plots: definition.

Common Commands

dvc metrics show --json --precision 4
dvc metrics diff HEAD workspace --json --precision 4
dvc params diff HEAD workspace --targets params.yaml --deps --json
dvc plots show reports/metrics.tsv --json --show-vega -x step -y accuracy --out dvc_plots
dvc plots diff HEAD workspace --targets reports/metrics.tsv --json --out dvc_plots

This checkout exposes dvc params diff in the CLI and exposes param display through dvc.api.params_show(). Do not promise a dvc params show CLI subcommand unless dvc params --help in the target environment lists it.

Bundled References

• references/workflows.md gives CLI and dvc.yaml recipes for metrics, params, and plots.
• references/api-reference.md documents verified public API signatures, return shapes, duplicate-key behavior, and helper usage.
• references/data-formats.md explains supported metrics/params/plots data formats, top-level plot definitions, and plots config keys.
• references/troubleshooting.md maps empty output, duplicate keys, path mistakes, format precision, and malformed files to concrete checks.
• scripts/summarize_metrics_params.py safely calls the public API and prints JSON without running pipeline commands or opening browsers.

Safe Helper

From this sub-skill directory, run:

python scripts/summarize_metrics_params.py --repo /path/to/project --rev HEAD --metrics-target reports/metrics.json --params-target params.yaml --stage train --deps

The helper imports dvc.api, calls only read-style API functions, emits JSON, and converts no-data/no-repo/API exceptions into explicit result objects.