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