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] 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/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