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://git.io/JJYDE | 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] SHELL

Arguments

SHELL¶: Required 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/master/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://git.io/JJYDE | 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/master/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

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/master/docs/examples/json/2-bin_1-channel.json | pyhf sort | jq '.' | md5
8be5186ec249d2704e14dd29ef05ffb0

$ curl -sL https://raw.githubusercontent.com/scikit-hep/pyhf/master/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.

--output-file <output_file>¶: The location of the output json file. If not specified, prints to screen.

--track-progress, --hide-progress¶

Arguments

ENTRYPOINT_XML¶: Required argument