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 patchsetPatchSetVerificationError
: 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/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