CLI

After installing cabinetry, a command line interface is available. Below is an example workflow that builds template histograms defined by the config file config_example.yml, and applies post-processing to them. A pyhf workspace is then constructed and a maximum likelihood fit is performed. The resulting correlation matrix and pull plot are saved to the default output folder figures/.

cabinetry templates config_example.yml
cabinetry postprocess config_example.yml
cabinetry workspace config_example.yml workspaces/example_workspace.json
cabinetry fit --pulls --corrmat workspaces/example_workspace.json

The --help flag can be used to obtain more information on the command line:

cabinetry --help

shows the available commands, while

cabinetry fit --help

shows what the fit command does, and which options it accepts.

It is possible to read the cabinetry config and workspaces from stdin, and to write workspaces to stdout:

# read config from stdin
cat config_example.yml | cabinetry workspace - workspaces/example_workspace.json
# read workspace from stdin
cat workspaces/example_workspace.json | cabinetry fit -
# write workspace to stdout
cabinetry workspace config_example.yml -

cabinetry

Entrypoint to the cabinetry CLI.

cabinetry [OPTIONS] COMMAND [ARGS]...

Options

--version: Show the version and exit.

data-mc

Visualizes distributions of fit model and observed data.

WS_SPEC: path to workspace

cabinetry data-mc [OPTIONS] WS_SPEC

Options

--config <config>: cabinetry configuration file

--postfit: visualize post-fit model (default: pre-fit model)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

fit

Fits a workspace and optionally visualizes the results.

WS_SPEC: path to workspace used in fit

cabinetry fit [OPTIONS] WS_SPEC

Options

--asimov: fit Asimov dataset (default: False)

--minos <minos>: run MINOS for a parameter (default: disabled)

--goodness_of_fit: calculate goodness-of-fit (default: False)

--pulls: produce pull plot (default: False)

--corrmat: produce correlation matrix (default: False)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

limit

Calculates upper limits and visualizes CLs distribution.

WS_SPEC: path to workspace used in fit

cabinetry limit [OPTIONS] WS_SPEC

Options

--asimov: fit Asimov dataset (default: False)

--tolerance <tolerance>: tolerance for convergence to CLs=1-confidence_level (default: 0.01)

--confidence_level, --cl <confidence_level>: confidence level for parameter limits (default: 0.95)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

modifier-grid

Visualizes modifier structure of a model.

WS_SPEC: path to workspace

cabinetry modifier-grid [OPTIONS] WS_SPEC

Options

--split_by_sample: split grids by sample (default: split by channel)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

postprocess

Post-processes template histograms.

CONFIG: path to cabinetry configuration file

cabinetry postprocess [OPTIONS] CONFIG

Arguments

CONFIG: Required argument

ranking

Ranks nuisance parameters and visualizes the result.

WS_SPEC: path to workspace used in fit

cabinetry ranking [OPTIONS] WS_SPEC

Options

--asimov: fit Asimov dataset (default: False)

--max_pars <max_pars>: maximum amount of parameters in plot (default: 10)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

scan

Performs and visualizes a likelihood scan over a parameter.

Parameter bounds are determined automatically, unless both the lower_bound and upper_bound parameters are provided.

WS_SPEC: path to workspace used in fit

PAR_NAME: name of parameter to scan over

cabinetry scan [OPTIONS] WS_SPEC PAR_NAME

Options

--lower_bound <lower_bound>: lower parameter bound in scan (default: auto)

--upper_bound <upper_bound>: upper parameter bound in scan (default: auto)

--n_steps <n_steps>: number of steps in scan (default: 11)

--asimov: fit Asimov dataset (default: False)

--figfolder <figfolder>: folder to save figures to (default: “figures”)

Arguments

WS_SPEC: Required argument

PAR_NAME: Required argument

significance

Calculates observed and expected discovery significance.

WS_SPEC: path to workspace used in fit

cabinetry significance [OPTIONS] WS_SPEC

Options

--asimov: fit Asimov dataset (default: False)

Arguments

WS_SPEC: Required argument

templates

Produces template histograms.

CONFIG: path to cabinetry configuration file

cabinetry templates [OPTIONS] CONFIG

Options

--method <method>: backend for histogram production (default: uproot)

Arguments

CONFIG: Required argument

workspace

Produces a pyhf workspace.

CONFIG: path to cabinetry configuration file

WS_SPEC: where to save the workspace containing the fit model

cabinetry workspace [OPTIONS] CONFIG WS_SPEC

Arguments

CONFIG: Required argument

WS_SPEC: Required argument

yields

Creates yield tables of fit model and observed data.

WS_SPEC: path to workspace

cabinetry yields [OPTIONS] WS_SPEC

Options

--postfit: show post-fit model (default: pre-fit model)

--tablefolder <tablefolder>: folder to save tables to (default: “tables”)

--tablefmt <tablefmt>: format in which to save the table (default: “simple”)

Arguments

WS_SPEC: Required argument