Command Line API

pyhf

Top-level CLI entrypoint.

pyhf [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

--cite, --citation

Print the bibtex citation for this software

cls

Compute CLs value(s) for a given pyhf workspace.

Example:

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | pyhf cls


{
    "CLs_exp": [
        0.07807427911686156,
        0.17472571775474618,
        0.35998495263681285,
        0.6343568235898907,
        0.8809947004472013
    ],
    "CLs_obs": 0.3599845631401915
}
pyhf cls [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--measurement <measurement>
-p, --patch <patch>
--test-poi <test_poi>
--test-stat <test_stat>
Options

q | qtilde

--calctype <calctype>
Options

asymptotics | toybased

--backend <backend>

The tensor backend used for the calculation.

Options

numpy | pytorch | tensorflow | jax | np | torch | tf

--optimizer <optimizer>

The optimizer used for the calculation.

Options

scipy | minuit

--optconf <optconf>

Arguments

WORKSPACE

Optional argument

combine

Combine two workspaces into a single workspace.

See pyhf.workspace.Workspace.combine() for more information.

pyhf combine [OPTIONS] [WORKSPACE_ONE] [WORKSPACE_TWO]

Options

-j, --join <join>

The join operation to apply when combining the two workspaces.

Options

none | outer | left outer | right outer

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--merge-channels, --no-merge-channels

Whether or not to deeply merge channels. Can only be done with left/right outer joins.

Arguments

WORKSPACE_ONE

Optional argument

WORKSPACE_TWO

Optional argument

completions

Generate shell completion code.

pyhf completions [OPTIONS] [[bash|fish|zsh|powershell]]

Arguments

SHELL

Optional argument

contrib

Contrib experimental operations.

Note

Requires installation of the contrib extra.

$ python -m pip install pyhf[contrib]
pyhf contrib [OPTIONS] COMMAND [ARGS]...

download

Download the patchset archive from the remote URL and extract it in a directory at the path given.

Example:

$ pyhf contrib download --verbose https://doi.org/10.17182/hepdata.90607.v3/r3 1Lbb-likelihoods


1Lbb-likelihoods/patchset.json
1Lbb-likelihoods/README.md
1Lbb-likelihoods/BkgOnly.json
Raises:

InvalidArchiveHost: if the provided archive host name is not known to be valid

pyhf contrib download [OPTIONS] ARCHIVE_URL OUTPUT_DIRECTORY

Options

-v, --verbose

Enables verbose mode

-f, --force

Force download from non-approved host

-c, --compress

Keep the archive in a compressed tar.gz form

Arguments

ARCHIVE_URL

Required argument

OUTPUT_DIRECTORY

Required argument

digest

Use hashing algorithm to calculate the workspace digest.

Returns:

digests (dict): A mapping of the hashing algorithms used to the computed digest for the workspace.

Example:

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | pyhf digest
sha256:dad8822af55205d60152cbe4303929042dbd9d4839012e055e7c6b6459d68d73
pyhf digest [OPTIONS] [WORKSPACE]

Options

-a, --algorithm <algorithm>

The hashing algorithm used to compute the workspace digest.

-j, --json, -p, --plaintext

Output the hash values as a JSON dictionary or plaintext strings

Arguments

WORKSPACE

Optional argument

fit

Perform a maximum likelihood fit for a given pyhf workspace.

Example:

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | pyhf fit --value


{
    "mle_parameters": {
        "mu": [
            0.00017298628839781602
        ],
        "uncorr_bkguncrt": [
            1.0000015671710816,
            0.9999665895859197
        ]
    },
    "twice_nll": 23.19636590468879
}
pyhf fit [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--measurement <measurement>
-p, --patch <patch>
--value

Flag for returning the fitted value of the objective function.

--backend <backend>

The tensor backend used for the calculation.

Options

numpy | pytorch | tensorflow | jax | np | torch | tf

--optimizer <optimizer>

The optimizer used for the calculation.

Options

scipy | minuit

--optconf <optconf>

Arguments

WORKSPACE

Optional argument

inspect

Inspect a pyhf JSON document.

Example:

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | pyhf inspect
          Summary
    ------------------
       channels  1
        samples  2
     parameters  2
      modifiers  2

       channels  nbins
     ----------  -----
  singlechannel    2

        samples
     ----------
     background
         signal

     parameters  constraint              modifiers
     ----------  ----------              ----------
             mu  unconstrained           normfactor
uncorr_bkguncrt  constrained_by_poisson  shapesys

    measurement           poi            parameters
     ----------        ----------        ----------
(*) Measurement            mu            (none)
pyhf inspect [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--measurement <measurement>

Arguments

WORKSPACE

Optional argument

json2xml

Convert pyhf JSON back to XML + ROOT files.

pyhf json2xml [OPTIONS] [WORKSPACE]

Options

--output-dir <output_dir>
--specroot <specroot>
--dataroot <dataroot>
--resultprefix <resultprefix>
-p, --patch <patch>

Arguments

WORKSPACE

Optional argument

patchset

Operations involving patchsets.

pyhf patchset [OPTIONS] COMMAND [ARGS]...

apply

Apply a patch from patchset to the background-only workspace specification.

Raises:

InvalidPatchLookup: if the provided patch name is not in the patchset PatchSetVerificationError: if the patchset cannot be verified against the workspace specification

Returns:

workspace (Workspace): The patched background-only workspace.

pyhf patchset apply [OPTIONS] [BACKGROUND_ONLY] [PATCHSET]

Options

--name <name>

The name of the patch to extract.

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

Arguments

BACKGROUND_ONLY

Optional argument

PATCHSET

Optional argument

extract

Extract a patch from a patchset.

Raises:

InvalidPatchLookup: if the provided patch name is not in the patchset

Returns:

jsonpatch (list): A list of jsonpatch operations to apply to a workspace.

pyhf patchset extract [OPTIONS] [PATCHSET]

Options

--name <name>

The name of the patch to extract.

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--with-metadata, --without-metadata

Include patchset metadata in output.

Arguments

PATCHSET

Optional argument

inspect

Inspect the PatchSet (e.g. list individual patches).

Returns:

None

pyhf patchset inspect [OPTIONS] [PATCHSET]

Arguments

PATCHSET

Optional argument

verify

Verify the patchset digests against a background-only workspace specification. Verified if no exception was raised.

Raises:

PatchSetVerificationError: if the patchset cannot be verified against the workspace specification

Returns:

None

pyhf patchset verify [OPTIONS] [BACKGROUND_ONLY] [PATCHSET]

Arguments

BACKGROUND_ONLY

Optional argument

PATCHSET

Optional argument

prune

Prune components from the workspace.

See pyhf.workspace.Workspace.prune() for more information.

pyhf prune [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

-c, --channel <CHANNEL>...>
-s, --sample <SAMPLE>...>
-m, --modifier <MODIFIER>...>
-t, --modifier-type <modifier_type>
Options

histosys | lumi | normfactor | normsys | shapefactor | shapesys | staterror

--measurement <MEASUREMENT>...>

Arguments

WORKSPACE

Optional argument

rename

Rename components of the workspace.

See pyhf.workspace.Workspace.rename() for more information.

pyhf rename [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

-c, --channel <PATTERN> <REPLACE>...>
-s, --sample <PATTERN> <REPLACE>...>
-m, --modifier <PATTERN> <REPLACE>...>
--measurement <PATTERN> <REPLACE>...>

Arguments

WORKSPACE

Optional argument

sort

Sort the workspace.

See pyhf.workspace.Workspace.sorted() for more information.

Example:

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | pyhf sort | jq '.' | md5
8be5186ec249d2704e14dd29ef05ffb0
$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/main/docs/examples/json/2-bin_1-channel.json | jq -S '.channels|=sort_by(.name)|.channels[].samples|=sort_by(.name)|.channels[].samples[].modifiers|=sort_by(.name,.type)|.observations|=sort_by(.name)' | md5
8be5186ec249d2704e14dd29ef05ffb0
pyhf sort [OPTIONS] [WORKSPACE]

Options

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

Arguments

WORKSPACE

Optional argument

xml2json

Entrypoint XML: The top-level XML file for the PDF definition.

pyhf xml2json [OPTIONS] ENTRYPOINT_XML

Options

--basedir <basedir>

The base directory for the XML files to point relative to.

-v, --mount <mount>

Consists of two fields, separated by a colon character ( : ). The first field is the local path to where files are located, the second field is the path where the file or directory are saved in the XML configuration. This is similar in spirit to Docker.

--output-file <output_file>

The location of the output json file. If not specified, prints to screen.

--track-progress, --hide-progress
--validation-as-error, --validation-as-warning

Arguments

ENTRYPOINT_XML

Required argument