Metrics Params Plots

---
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

```bash
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:

```bash
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.