HistFactory Models
NextStat is fully compatible with the pyhf JSON workspace format. You can take any existing pyhf workspace and run it through NextStat without modification.
Workspace Format
A workspace JSON file contains channels, samples, measurements, and observations. NextStat parses this format identically to pyhf, producing the same Poisson likelihood with constraint terms.
Likelihood Construction
The negative log-likelihood includes:
- Poisson terms for each bin (observed vs expected)
- Gaussian constraints for normalization and shape systematics
- Poisson constraints for shape factors
- Barlow-Beeston auxiliary terms for bin-by-bin statistical uncertainties
Supported Modifiers
| Modifier | Type |
|---|---|
| normfactor | Unconstrained normalization |
| normsys | Gaussian-constrained normalization |
| histosys | Shape variation (up/down histograms) |
| shapesys | Per-bin Poisson-constrained |
| staterror | Barlow-Beeston lite |
| lumi | Luminosity uncertainty |
HS3 Support (ROOT 6.37+)
NextStat natively loads HS3 v0.2 (HEP Statistics Serialization Standard) JSON workspaces produced by ROOT 6.37+. Format auto-detection is instant (prefix scan of the first ~2 KB).
# Auto-detects pyhf vs HS3 nextstat fit --input workspace-postFit_PTV.json # Python — auto-detect model = nextstat.HistFactoryModel.from_workspace(hs3_json) # Python — explicit HS3 model = nextstat.HistFactoryModel.from_hs3(hs3_json, analysis="combPdf_obsData")
HS3 roundtrip export is also supported: model.to_hs3() produces HS3 JSON with bestfit parameter points, preserving original metadata.
Interpolation Codes
| Input | NormSys | HistoSys |
|---|---|---|
| pyhf JSON (default) | Code4 (smooth) | Code4p (smooth) |
pyhf JSON + --interp-defaults pyhf | Code1 (exponential) | Code0 (piecewise linear) |
| HS3 JSON (always) | Code1 (exponential) | Code0 (piecewise linear) |
ConstraintTerm Semantics
NextStat supports the full set of HistFactory constraint term types parsed from XML <ConstraintTerm> metadata:
- LogNormal — alpha-transform (
normsys_alpha_effective) - Gamma — Poisson constraint for ShapeSys modifiers
- Uniform — flat prior, no constraint penalty
- NoConstraint — free parameter (normfactor behavior)
Arrow / Polars Ingestion
Build a HistFactoryModel from columnar data (PyArrow, Polars, DuckDB, Spark) or Parquet files:
import nextstat, pyarrow as pa
# From PyArrow Table
model = nextstat.from_arrow(table, poi="mu")
# From Parquet
model = nextstat.from_parquet("histograms.parquet", poi="mu")
# Export yields back to Arrow
yields = nextstat.to_arrow(model, what="yields")See Arrow / Polars docs for schema requirements and full API reference.
Parity with pyhf
NextStat maintains a strict parity contract with pyhf. The NLL difference on all test workspaces is < 1e-8 (deterministic CPU mode). The optimizer (L-BFGS-B) often finds better minima than pyhf's default SLSQP, especially on models with 100+ nuisance parameters.