Install & Compatibility
Where this runs
tested against v0.7.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
8/20 runs
16/20 runs
626MB installed
● package 626MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
set_backend
✓ import pyhf
pyhf.set_backend("numpy")
✗ from pyhf import set_backend; set_backend("numpy")
pyhf.set_backend is a global configuration function and is intended to be called via the pyhf module directly to ensure proper initialization of the backend context.
Model
✓ import pyhf
model = pyhf.Model(...)
fit
✓ import pyhf
result = pyhf.infer.mle.fit(...)
qmu
✓ import pyhf
mu_test_stat = pyhf.infer.test_statistics.qmu(...)
✗ mu_test_stat = pyhf.test_statistics.qmu(...)
The `test_statistics` module and related functions were moved under `pyhf.infer` in v0.6.0 for better organization.
This quickstart demonstrates how to define a simple HistFactory workspace, set a backend, create a pyhf model, and perform a basic maximum likelihood fit to extract best-fit parameters and their uncertainties. It also shows how to set and fix specific parameters for hypothesis testing.
import pyhf
import json
# Define a simple workspace (example adapted from pyhf documentation)
workspace_data = {
"channels": [
{
"name": "singlechannel",
"samples": [
{
"name": "signal",
"data": [12.0],
"modifiers": [
{"name": "mu", "type": "normfactor", "data": None},
{"name": "lumi", "type": "lumi", "data": {"correlated": True, "nom_data": 1.0, "rel_data": 0.1}}
]
},
{
"name": "background",
"data": [100.0],
"modifiers": [
{"name": "lumi", "type": "lumi", "data": {"correlated": True, "nom_data": 1.0, "rel_data": 0.1}},
{"name": "bkg_norm", "type": "normfactor", "data": None}
]
}
]
}
],
"observations": [
{
"name": "singlechannel",
"data": [120.0],
"modifier_data": [
{"name": "lumi", "type": "lumi", "data": 1.0}
]
}
]
}
# Set the backend (e.g., 'numpy', 'tensorflow', 'torch', or 'jax')
pyhf.set_backend("numpy")
# Create a model from the workspace data
workspace = pyhf.Workspace(workspace_data)
model = workspace.model(modifier_settings={'lumi': {'type': 'lumi', 'decorrelate': False}})
# Prepare data and initial parameters for the fit
# The model's data method handles observation and auxiliary data.
actual_data = model.data(workspace.data)
init_pars = model.config.suggested_init()
fixed_pars = model.config.suggested_fixed()
bounds = model.config.suggested_bounds()
# Perform Maximum Likelihood Estimation (MLE)
# This fits the model to the data to find the best-fit parameters.
fit_results = pyhf.infer.mle.fit(
data=actual_data,
pdf=model,
init_pars=init_pars,
fixed_params=fixed_pars,
par_bounds=bounds
)
print(f"Fitted parameters: {fit_results[0]}")
print(f"Parameter uncertainties: {fit_results[1]}")
# Example for hypothesis testing: fixing 'mu' (signal strength) to 0 (background-only hypothesis)
mu_index = model.config.modifier_index('mu') # Get index of the 'mu' parameter
bkg_only_init_pars = list(init_pars) # Create a mutable copy
bkg_only_init_pars[mu_index] = 0.0 # Set mu to 0
bkg_only_fixed_params = list(fixed_pars) # Create a mutable copy
bkg_only_fixed_params[mu_index] = True # Fix mu at 0
bkg_only_fit_results = pyhf.infer.mle.fit(
data=actual_data,
pdf=model,
init_pars=bkg_only_init_pars,
fixed_params=bkg_only_fixed_params,
par_bounds=bounds
)
print(f"Fitted parameters (mu=0 fixed): {bkg_only_fit_results[0]}")
pyhf --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tensorflow' (or 'torch' or 'jax')
An optional backend (TensorFlow, PyTorch, or JAX) was not installed, but pyhf attempted to use it or it was explicitly set as the backend.
fixInstall the desired backend using the extra syntax, e.g., `pip install 'pyhf[tensorflow]'`. Alternatively, explicitly set a different backend like `pyhf.set_backend('numpy')` if it's installed. AttributeError: module 'numpy' has no attribute 'product'
You are using a pyhf version older than 0.7.3 with NumPy version 1.25.0 or newer. `np.product` was deprecated in NumPy 1.25.0.
fixUpgrade pyhf to version 0.7.3 or newer: `pip install --upgrade pyhf`. This version updates pyhf's internal usage of `np.product` to `np.prod`.
pyhf.exceptions.InvalidWorkspace: Schema validation failed:
The provided JSON or XML workspace definition does not conform to the HistFactory schema expected by pyhf, often due to missing required fields or incorrect data types.
fixReview your workspace definition against the official HistFactory schema and pyhf's documentation. Ensure all required fields (e.g., 'channels', 'observations', 'samples') are present and correctly formatted, and that data types match expectations.
TypeError: 'jax.Array' object cannot be interpreted as an integer
This (or similar `TypeError` for other backends like `torch.Tensor`) often occurs when mixing array types from different backends (e.g., passing a JAX array to a NumPy-expecting function) or attempting operations not supported by the current backend's tensor type.
fixEnsure that all tensor operations use the functions provided by `pyhf.tensorlib` and that arrays are consistently managed within the chosen backend. Avoid direct mixing of `numpy.array` with JAX or PyTorch tensors without explicit conversion functions.
Upgrade
Version history
0.7.6latest on PyPI · released Jan 5, 2024
Audit
Dependencies
numpyrequiredCore tensor library
scipyrequiredCore scientific computing library
tensorflowoptionalOptional backend for tensor operations and autodiff
torchoptionalOptional backend for tensor operations and autodiff
jaxoptionalOptional backend for tensor operations and autodiff
jaxliboptionalRequired for JAX backend, often needs specific installation based on hardware
mminuitoptionalOptional backend for optimization routines via iminuit