Command Line API

pyhf

Top-level CLI entrypoint.

pyhf [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

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>
--testpoi <testpoi>
--teststat <teststat>
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/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