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

--backend <backend>¶

The tensor backend used for the calculation.

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

--optimizer <optimizer>¶

--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.

Arguments

WORKSPACE_ONE¶: Optional argument

WORKSPACE_TWO¶: Optional argument

completions¶

Generate shell completion code.

pyhf completions [OPTIONS] SHELL

Arguments

SHELL¶: 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

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

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