MetriCal Command: Run

Usage

Run - CLI Example

metrical run [OPTIONS] [MANIFEST_PATH] --workspace [WORKSPACE]

Purpose

This command executes a MetriCal manifest file located at the specified MANIFEST_PATH. The manifest contains all the necessary configuration and parameters to carry out a complete calibration process. See the manifest overview for more details.

Note that the order of execution is determined by the input and output dependencies of each stage, not the ordering in the manifest file itself. Manifests will not process if there is a cyclic dependency between stages or a missing input dependency.

Default Dry Runs

As MetriCal is a credit-based system, we want to make sure you have control over when credits are consumed. By default, the calibrate command will not show results or consume credits unless you explicitly pass show-results = true in your manifest. This allows you to run dry runs of calibrations to see if everything looks good before committing to spending credits on the final result.

Table CP-001 will show you the current results obfuscation behavior based on presence or absence of the show-results flag along with the status of your calibration:

Loading...

Forcing Output of Results

In the case of a failed calibration, or a calibration with high-risk data diagnostics, no results will be shown, regardless of the status of the show_results flag. This is because MetriCal works to prevent you from using bad calibrations at all! If you feel confident in your data collection approach, though, just set override-diagnostics to true to force output of the calibration results.

Automatic Reporting

Unlike other modes, the Run command automatically generates an HTML report for the entire manifest run in the final workspace directory. If the --report-path option is provided, however, the report will be saved to the specified location.

Error Handling

If any stage fails during execution, the entire manifest run will halt immediately and return the exit code, along with any diagnostic information. This ensures that subsequent stages do not run with incomplete or invalid data. Users should review the error messages provided to diagnose and resolve issues before re-running the manifest.

Examples

Run a MetriCal manifest located in the specified directory.

metrical run /path/to/directory/<manifest_name>.toml

Arguments

[MANIFEST_PATH]

The path to the TOML manifest.

Options

Global Arguments

As with every command, all global arguments are supported (though not all may be used).

--workspace [WORKSPACE]

The output directory for the final results. By default, if no workspace is provided, the workspace defined in the manifest file will be used.

Results are stored in subdirectories per step. For example, if the output directory is ./output, and there are steps named init and calibrate, then results will be stored in ./output/init and ./output/calibrate.

--set [OVERRIDE_VARIABLES]

Override variables in the manifest.

Say we have a variable named data-to-run:

[project.variables.data-to-run]
description = "The dataset to use for this run"
value = "default_dataset.mcap"

However, we don't want to use default_dataset.mcap for this next run; we have another dataset, better_dataset.mcap, that would work better.

MetriCal makes this easy with the --set option. You can overwrite this default value from the command line like so: --set data-to-run:better_dataset.mcap. Now, MetriCal will use this new value for the run instead of the default.