pyhs3 CLI

pyhs3 installs a command-line tool of the same name, wired to pyhs3.cli:app. Run pyhs3 --help or python -m pyhs3 --help for the tool’s own summary of the commands below.

Every command accepts the workspace as a positional argument, a path to an HS3 JSON file. Passing -, or omitting the argument entirely when standard input is not a terminal, reads the workspace from stdin instead, so cat workspace.json | pyhs3 validate - and pyhs3 validate workspace.json are equivalent.

pyhs3

pyhs3 Usage: pyhs3 [OPTIONS] COMMAND [ARGS]... Command-line tools for HS3 workspaces: validate, inspect, and   evaluate.                                                       ╭─ Options ─────────────────────────────────────────────────────╮ │--helpShow this message and exit.                  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Commands ────────────────────────────────────────────────────╮ │graph   Render a distribution's computation graph to an    │ │image file.                                        │ │validateLoad and validate an HS3 workspace, reporting      │ │success or the errors found.                       │ │inspect Summarize a workspace: distributions, domains,     │ │data, likelihoods, analyses.                       │ │nll     Compute the negative log-likelihood at a point in  │ │parameter space.                                   │ │plot    Render one named data entry from a workspace as a  │ │matplotlib figure.                                 │ ╰───────────────────────────────────────────────────────────────╯

graph

graph Usage: pyhs3 graph [OPTIONS] [WORKSPACE] Render a distribution's computation graph to an image file.     Builds the model the same way nll does (--analysis selects  whichanalysis or likelihood to build from) and delegates to Model.visualize_graph. Prints the path of therendered file to  stdout. Requires the graph optional dependency(pip install  'pyhs3[graph]', which installs pydot) and thesystem Graphviz  dot executable, which pydot cannot install on its own(apt  install graphviz, brew install graphviz, orconda install  graphviz). If either is missing, or the nameddistribution  doesn't exist in the model, this reports the problemthrough a  clean error and exits non-zero, never a raw traceback. ╭─ Arguments ───────────────────────────────────────────────────╮ │WORKSPACE<str>Path to an HS3 workspace JSON file.  │ │Use '-' or omit to read from stdin.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │*--name<str>Name of the distribution to    │ │visualize.                     │ │[required]                     │ │--analysis<str>Name of the analysis (or       │ │likelihood) to build the model │ │from. Defaults to the sole one.│ │--fmt<str>Output format: svg, png, or    │ │pdf.                           │ │[default: svg]                 │ │--outfile<str>Output file path. Defaults to  │ │'{name}_graph.{fmt}'.          │ │--path<str>Directory to write the output  │ │file in. Ignored if --outfile  │ │is set.                        │ │--show-idAppend each op's toposort index│ │to its label.                  │ │--show-dtypeKeep dtype annotations in node │ │labels.                        │ │--show-shapeKeep shape annotations in node │ │labels.                        │ │--helpShow this message and exit.    │ ╰───────────────────────────────────────────────────────────────╯

validate

validate Usage: pyhs3 validate [OPTIONS] [WORKSPACE] Load and validate an HS3 workspace, reporting success or the    errors found.                                                   On success, prints <source> is a valid HS3 workspace. and exits 0. Onfailure, exits 1: a schema error (a field missing or the  wrong type) isreported through  Workspace.format_validation_error, and without--verbose only  the first 20 are shown, with the rest summarized bycount; an  unresolved cross-reference (a likelihood naming a distribution that doesn't exist, for example) is reported through pyhs3.exceptions.WorkspaceValidationError. ╭─ Arguments ───────────────────────────────────────────────────╮ │WORKSPACE<str>Path to an HS3 workspace JSON file.  │ │Use '-' or omit to read from stdin.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--verbose-vShow all validation errors, not just the│ │first 20.                               │ │--helpShow this message and exit.             │ ╰───────────────────────────────────────────────────────────────╯

inspect

inspect Usage: pyhs3 inspect [OPTIONS] [WORKSPACE] Summarize a workspace: distributions, domains, data,            likelihoods, analyses.                                          Prints a Rich table when attached to an interactive terminal  and machinereadable JSON when piped. Override the  autodetection with --json or--no-json. Table output caps each section at _MAX_ROWS_DEFAULT rows by  default;pass --verbose/-v to show every row. JSON output is  alwayscomplete and is never truncated by --verbose/-v — it is  meant formachine/script consumption, so it must never silently drop entries. ╭─ Arguments ───────────────────────────────────────────────────╮ │WORKSPACE<str>Path to an HS3 workspace JSON file.  │ │Use '-' or omit to read from stdin.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--json--no-jsonForce JSON (--json) or table   │ │(--no-json) output. Default:   │ │autodetect from the terminal.  │ │--verbose-vShow every row in table output,│ │without the 10-row-per-section │ │cap. Has no effect on --json   │ │output, which is always        │ │complete.                      │ │--helpShow this message and exit.    │ ╰───────────────────────────────────────────────────────────────╯

nll

nll Usage: pyhs3 nll [OPTIONS] [WORKSPACE] Compute the negative log-likelihood at a point in parameter     space.                                                          The printed value is -2 * log_prob -- twice the negated joint log-probability -- not the plain -log_prob some other tools (including RooFit's own createNLL()) report under the same  name.Compare against a RooFit/combine-side number with that  factor of two inmind. Parameter values are layered, later layers winning: the  workspace's ownparameter_points (so an analysis without an  init set is stillevaluable), then the model's free (non-const) parameter values, then--params-file, then repeated --param  name=value (a name givenboth in the file and on the command  line takes the command-line value).A --param naming an  observable, or naming something that is neitheran observable  nor a free parameter of the model (a typo, for example),is  rejected with a warning and ignored -- it can never override  theworkspace's actual observed data -- and the command still  exits 0. Afree parameter with no value available anywhere in  this layering raisesa fatal error naming it, exiting non-zero. --analysis accepts either an analysis name or a likelihood name directly. With neither given, the workspace's sole analysis is  used, or,absent any analyses, its sole likelihood; having more than one of eitherwithout --analysis is a fatal error. ╭─ Arguments ───────────────────────────────────────────────────╮ │WORKSPACE<str>Path to an HS3 workspace JSON file.  │ │Use '-' or omit to read from stdin.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │--param-pNAME=VALUEOverride a parameter      │ │value. Repeatable.        │ │--params-file<file>JSON file mapping         │ │parameter names to values.│ │--analysis<str>Name of the analysis (or  │ │likelihood) to evaluate.  │ │Defaults to the sole one. │ │--helpShow this message and     │ │exit.                     │ ╰───────────────────────────────────────────────────────────────╯

plot

plot Usage: pyhs3 plot [OPTIONS] [WORKSPACE] Render one named data entry from a workspace as a matplotlib    figure.                                                         Requires the plot extra (pip install 'pyhs3[plot]'), which installs hist[plot] -- matplotlib andmplhep, since plotting a hist.Hist needs both; matplotlib alone is not enough. If  matplotlibitself is missing, this reports a clean error rather than a rawtraceback; if matplotlib is present but mplhep specifically ismissing (an unusual partial install), plotting  can still raise a rawModuleNotFoundError -- installing the  plot extra as documentedavoids this case entirely. Only 1D BinnedData/UnbinnedData and 2D BinnedData are supported; other shapes raise a clear error rather than a  misleading plot. ╭─ Arguments ───────────────────────────────────────────────────╮ │WORKSPACE<str>Path to an HS3 workspace JSON file.  │ │Use '-' or omit to read from stdin.  │ ╰───────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────╮ │*--data-name<str>Name of the entry in the       │ │workspace's data list to plot. │ │[required]                     │ │--outfile<path>Output file path. Defaults to  │ │'{data-name}.{fmt}' in the     │ │current directory.             │ │--fmt<str>Output image format: 'png',    │ │'pdf', or 'svg'.               │ │[default: png]                 │ │--helpShow this message and exit.    │ ╰───────────────────────────────────────────────────────────────╯