Edit on GitHub

dvc.api.metrics_show()

Load metrics tracked in a DVC project.

def metrics_show(
    *targets: str,
    repo: Optional[str] = None,
    rev: Optional[str] = None,
) -> Dict:

Usage:

import dvc.api

metrics = dvc.api.metrics_show()

Description

Retrieves metrics values from a DVC project and returns a dictionary, such as:

{
  "avg_prec": { "train": 0.97, "val": 0.92 },
  "roc_auc": { "train": 0.98, "val": 0.94 }
}

Without arguments, this function will retrieve all metrics from all tracked metrics files (used in any dvc.yaml file). This applies to the current project version when using Git (including any changes in the working tree).

The function parameters (below) let you restrict what's retrieved.

Metrics

  • *targets - one or more separate path(s) to valid metrics file(s) to retrieve metrics from, for example "eval/train_val_metrics.json", "eval/test_metrics.json". If no targets are provided, all metrics files tracked in any dvc.yaml will be targeted by default.

  • repo - specifies the location of the DVC project. It can be a URL or a file system path. Both HTTP and SSH protocols are supported for online Git repos (e.g. [user@]server:project.git). Default: The current project (found by walking up from the current working directory tree).

  • rev - Git commit (any revision such as a branch or tag name, a commit hash or an experiment name). If repo is not a Git repo, this option is ignored. Default: None (current working tree will be used)

Example: Filter by one or more targets

targets can be a single name (string):

import dvc.api
metrics = dvc.api.metrics_show("eval/train_val_metrics.json")
{
  "avg_prec": { "train": 0.97, "val": 0.92 },
  "roc_auc": { "train": 0.98, "val": 0.94 }
}

Or multiple names (strings):

import dvc.api
metrics = dvc.api.metrics_show("eval/train_val_metrics.json", "eval/test_metrics.json")
{
  "eval/train_val_metrics.json": {
    "avg_prec": { "train": 0.97, "val": 0.92 },
    "roc_auc": { "train": 0.98, "val": 0.94 }
  },
  "eval/test_metrics.json": {
    "avg_prec": { "test": 0.72 },
    "roc_auc": { "test": 0.77 }
  }
}

Example: Filter by revision

You can pass any valid Git revision to just get metrics from that revision:

import dvc.api
metrics = dvc.api.metrics_show(rev="HEAD~1")
{
  "avg_prec": { "train": 0.97, "val": 0.92 },
  "roc_auc": { "train": 0.98, "val": 0.94 }
}

Example: Use a remote DVC repository

You can use the repo argument to retrieve metrics from any DVC repository without having to clone it locally.

import dvc.api
metrics = dvc.api.metrics_show(
    repo="https://github.com/iterative/example-get-started")
{
  "avg_prec": {
    "train": 0.9743681430252835,
    "test": 0.9249974999612706
  },
  "roc_auc": {
    "train": 0.9866678562450621,
    "test": 0.9460213440787918
  }
}
Content

🐛 Found an issue? Let us know! Or fix it:

Edit on GitHub

Have a question? Join our chat, we will help you:

Discord Chat