exp save
Save the current project workspace as a DVC experiment.
Synopsis
Description
Provides a way to save the current status of your project as an experiment without polluting it with unnecessary commits, branches, directories, etc.
Only files tracked by either Git or DVC are saved to the experiment. Use the
--include-untracked (-I) option to explicitly include any untracked files in
the experiment.
dvc exp save creates experiments just like
dvc exp run, but does not require
reproduction or setup of pipeline stages, making it
possible to quickly start tracking, comparing and persisting experiments.
Options
-
-n <name>,--name <name>- specify a unique name for this experiment. A default one will be generated otherwise, such asurban-sign.The name of the experiment is exposed in env var
DVC_EXP_NAME. -
-I <path>,--include-untracked <path>- specify untracked file(s) to be included in the saved experiment. Multiple files can be specified. -
-f,--force- overwrite the experiment if an experiment with the same name already exists. -
-h,--help- prints the usage/help message, and exits. -
-q,--quiet- do not write anything to standard output. Exit with 0 if all stages are up to date or if all stages are successfully executed, otherwise exit with 1. The command defined in the stage is free to write output regardless of this flag. -
-v,--verbose- displays detailed tracing information.
Examples
This example is based on our Get Started, where you can find the actual source code.
Let's say we have modified our repo by adding new data (data/new.xml), new
code (src/extratrees.py), as well as modifying the training script
(src/train.py). After running dvc add data/new.xml, we have the following
status in the repo:
$ git status
On branch main
Your branch is up to date with 'upstream/main'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: data/.gitignore
modified: src/train.py
Untracked files:
(use "git add <file>..." to include in what will be committed)
data/new.xml.dvc
src/extratrees.py
no changes added to commit (use "git add" and/or "git commit -a")We can run dvc repro to reproduce the pipeline and inspect results, e.g. by
running dvc metrics show. We are not quite ready for a commit, but we want to
save the results of this experiment, so we can run:
dvc exp save --name extra-trees -I data/new.xml.dvc -I src/extra_trees.pyWe use the -I flags to make sure to include new (untracked) files in the
experiment.
We can now get rid of all the changes in the workspace, as well as removing untracked files:
$ git reset --hard
$ rm data/new.xml data/new.xml.dvc src/extratrees.pyWe see the experiment we just saved by using dvc exp show
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Experiment Created avg_prec roc_auc prepare.split prepare.seed featurize.max_features featurize.ngrams train.seed train.n_est train.min_split data/data.xml data/features data/prepared model.pkl src/evaluate.py src/featurization.py src/prepare.py src/train.py
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
workspace - 0.925 0.94602 0.2 20170428 200 2 20170428 50 0.01 22a1a29 f35d4cc 153aad0 fb021d7 759095a e0265fc f09ea0c c3961d7
main Nov 02, 2022 0.925 0.94602 0.2 20170428 200 2 20170428 50 0.01 22a1a29 f35d4cc 153aad0 fb021d7 759095a e0265fc f09ea0c c3961d7
└── d0f234c [extra-trees] 12:11 PM 0.92707 0.94612 0.2 20170428 200 2 20170428 50 0.01 ced660e f35d4cc 153aad0 27473f2 759095a e0265fc f09ea0c 6537232
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────The experiment has higher avg_prec/roc_auc, so we want to restore it, we can
use dvc exp apply:
$ dvc exp apply extra-trees
Changes for experiment 'extra-trees' have been applied to your current workspace.
$ git status
On branch main
Your branch is up to date with 'upstream/main'.
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: data/.gitignore
modified: data/data.xml.dvc
modified: dvc.lock
modified: evaluation/metrics.json
modified: evaluation/plots/metrics/avg_prec.tsv
modified: evaluation/plots/metrics/roc_auc.tsv
modified: evaluation/plots/prc.json
modified: evaluation/plots/sklearn/confusion_matrix.json
modified: evaluation/plots/sklearn/roc.json
modified: evaluation/report.html
modified: src/train.py
Untracked files:
(use "git add <file>..." to include in what will be committed)
data/new.xml.dvc
src/extratrees.py
no changes added to commit (use "git add" and/or "git commit -a")All changes, including untracked files, have been restored to the workspace.
See our Get Started guide, for more examples on how to use experiments.