API

cabinetry.configuration

Provides utilities to handle the cabinetry configuration.

cabinetry.configuration.histogram_is_needed(region: Dict[str, Any], sample: Dict[str, Any], systematic: Dict[str, Any], template: Literal['Up', 'Down'] | None) → bool

Determines whether a histogram is needed for a specific configuration.

The configuration is defined by the region, sample, systematic and template (“Up” or “Down”, None for nominal).

Parameters:

region (Dict[str, Any]) – containing all region information
sample (Dict[str, Any]) – containing all sample information
systematic (Dict[str, Any]) – containing all systematic information
template (Optional[Literal["Up", "Down"]]) – which template to consider: “Up”, “Down”, None for the nominal case

Raises:

NotImplementedError – non-supported systematic variations based on histograms are requested

Returns:

whether a histogram is needed

Return type:

bool

cabinetry.configuration.load(file_path_string: str | Path) → Dict[str, Any]

Loads, validates, and returns a config file from the provided path.

Parameters:: file_path_string (Union[str, pathlib.Path]) – path to config file
Returns:: cabinetry configuration
Return type:: Dict[str, Any]

cabinetry.configuration.print_overview(config: Dict[str, Any]) → None

Prints a compact summary of a config file.

Parameters:: config (Dict[str, Any]) – cabinetry configuration

cabinetry.configuration.region_contains_modifier(region: Dict[str, Any], modifier: Dict[str, Any]) → bool

Checks if a region contains a given modifier (Systematic, NormFactor).

A modifier affects all regions by default, and its “Regions” property can be used to specify a single region or list of regions that contain the modifier. This does not check whether the modifier only acts on samples which the region does not contain.

Parameters:

region (Dict[str, Any]) – containing all region information
modifier (Dict[str, Any]) – containing all modifier information (a Systematic or a NormFactor)

Returns:

True if region contains modifier, False otherwise

Return type:

bool

cabinetry.configuration.region_contains_sample(region: Dict[str, Any], sample: Dict[str, Any]) → bool

Checks if a region contains a given sample.

A sample enters all regions by default, and its “Regions” property can be used to specify a single region or list of regions that contain the sample.

Parameters:

region (Dict[str, Any]) – containing all region information
sample (Dict[str, Any]) – containing all sample information

Returns:

True if region contains sample, False otherwise

Return type:

bool

cabinetry.configuration.region_dict(config: Dict[str, Any], region_name: str) → Dict[str, Any]

Returns the dictionary for a region with the given name.

Parameters:

config (Dict[str, Any]) – cabinetry configuration file
region_name (str) – name of region

Raises:

ValueError – when region is not found in config

Returns:

dictionary describing region

Return type:

Dict[str, Any]

cabinetry.configuration.sample_contains_modifier(sample: Dict[str, Any], modifier: Dict[str, Any]) → bool

Checks if a sample is affected by a given modifier (Systematic, NormFactor).

A modifier affects all samples by default, and its “Samples” property can be used to specify a single sample or list of samples on which the modifier acts.

Parameters:

sample (Dict[str, Any]) – containing all sample information
modifier (Dict[str, Any]) – containing all modifier information (a Systematic or a NormFactor)

Returns:

True if sample is affected, False otherwise

Return type:

bool

cabinetry.configuration.validate(config: Dict[str, Any]) → bool

Returns True if the config file is validated, otherwise raises exceptions.

Checks that the config satisfies the json schema, and performs additional checks to validate the config further.

Parameters:

config (Dict[str, Any]) – cabinetry configuration

Raises:

NotImplementedError – when more than one data sample is found
ValueError – when region / sample / normfactor / systematic names are not unique

Returns:

whether the validation was successful

Return type:

bool

cabinetry.route

Provides features to apply functions to template histograms.

class cabinetry.route.Router

Holds user-defined processing functions and matches functions to templates.

Provides functions for matching a pattern to apply the right function to each template.

template_builders

user-defined processors for template building

Type:: List[Dict[str, Any]]

template_builder_wrapper

wrapper to apply on user- defined template builders

Type:: Optional[WrapperFunc]

register_template_builder(*, region_name: str = '*', sample_name: str = '*', systematic_name: str = '*', template: str | None = '*') → Callable[[Callable[[Dict[str, Any], Dict[str, Any], Dict[str, Any], str | None], Histogram]], Callable[[Dict[str, Any], Dict[str, Any], Dict[str, Any], str | None], Histogram]]

Decorator for registering a template builder function.

The function is added to the list stored in the template_builders member variable.

Parameters:

region_name (str, optional) – name of the region to apply the function to, defaults to “*” (apply to all regions)
sample_name (str, optional) – name of the sample to apply the function to, defaults to “*” (apply to all samples)
systematic_name (str, optional) – name of the systematic to apply the function to, defaults to “*” (apply to all systematics)
template (Optional[str], optional) – name of the template to apply the function to (e.g. “Up” or “Down”), or None to apply to nominal only, defaults to “*” (apply to all templates, including nominal)

Returns:

the function to register a processor

Return type:

Callable[[UserTemplateFunc], UserTemplateFunc]

cabinetry.route.apply_to_all_templates(config: Dict[str, Any], default_func: Callable[[Dict[str, Any], Dict[str, Any], Dict[str, Any], Literal['Up', 'Down'] | None], None], *, match_func: Callable[[str, str, str, Literal['Up', 'Down'] | None], Callable[[Dict[str, Any], Dict[str, Any], Dict[str, Any], Literal['Up', 'Down'] | None], None] | None] | None = None) → None

Applies the supplied function default_func to all templates.

The templates are specified by the configuration file. The function takes four arguments in this order:

the dict specifying region information
the dict specifying sample information
the dict specifying systematic information
the template being considered: “Up”, “Down”, or None for the nominal template

In addition it is possible to specify a function that returns custom overrides. If one is found for a given template, it is used instead of the default.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
default_func (ProcessorFunc) – function to be called for every template by default
match_func – (Optional[MatchFunc], optional): function that returns user-defined functions to override the call to default_func, defaults to None (then it is not used)

cabinetry.histo

Provides a histogram class based on boost-histogram.

class cabinetry.histo.Histogram(*axes: Axis | CppAxis | Histogram | Any, storage: Storage = Double(), metadata: Any = None)

Holds histogram information, extends boost_histogram.Histogram.

property bins: ndarray

Returns the bin edges.

Returns:: bin edges
Return type:: np.ndarray

classmethod from_arrays(bins: List[float] | ndarray, yields: List[float] | ndarray, stdev: List[float] | ndarray) → H

Constructs a histogram from arrays of yields and uncertainties.

The input can be lists of ints or floats, or numpy.ndarrays.

Parameters:

bins (Union[List[float], np.ndarray]) – edges of histogram bins
yields (Union[List[float], np.ndarray]) – yield per histogram bin
stdev (Union[List[float], np.ndarray]) – statistical uncertainty of yield per bin

Raises:

ValueError – when amount of bins specified via bin edges and bin contents do not match
ValueError – when length of yields and stdev do not match

Returns:

the histogram instance

Return type:

cabinetry.histo.Histogram

classmethod from_config(histo_folder: str | Path, region: Dict[str, Any], sample: Dict[str, Any], systematic: Dict[str, Any], *, template: Literal['Up', 'Down'] | None = None, modified: bool = True) → H

Loads a histogram, using information specified in the configuration file.

To find the histogram, need to provide the folder the histogram is located in and the relevant information from the config: region, sample, systematic, template.

Parameters:

histo_folder (Union[str, patlib.Path]) – folder containing all histograms
region (Dict[str, Any]) – containing all region information
sample (Dict[str, Any]) – containing all sample information
systematic (Dict[str, Any]) – containing all systematic information
template (Optional[Literal["Up", "Down"]], optional) – which template to consider: “Up”, “Down”, None for the nominal case, defaults to None
modified (bool, optional) – whether to load the modified histogram (after post-processing), defaults to True

Returns:

the loaded histogram

Return type:

cabinetry.histo.Histogram

classmethod from_path(histo_path: Path, *, modified: bool = True) → H

Builds a histogram from disk.

Loads the “modified” version of the histogram by default (which received post- processing).

Parameters:

histo_path (pathlib.Path) – where the histogram is located
modified (bool, optional) – whether to load the modified histogram (after post-processing), defaults to True

Returns:

the loaded histogram

Return type:

cabinetry.histo.Histogram

normalize_to_yield(reference_histogram: H) → float

Normalizes a histogram to match the yield of a reference.

Returns the normalization factor used to normalize the histogram.

Parameters:: reference_histogram (cabinetry.histo.Histogram) – reference histogram to normalize to
Returns:: the yield ratio: un-normalized yield / normalized yield
Return type:: float

save(histo_path: Path) → None

Saves a histogram to disk.

Parameters:: histo_path (pathlib.Path) – where to save the histogram

property stdev: ndarray

Returns the stat. uncertainty per histogram bin.

Returns:: stat. uncertainty per bin
Return type:: np.ndarray

validate(name: str) → None

Runs consistency checks on a histogram.

Checks for empty bins and ill-defined statistical uncertainties. Logs warnings if issues are founds, but does not raise exceptions.

Parameters:: name (str) – name of the histogram for logging purposes

property yields: ndarray

Returns the yields per histogram bin.

Returns:: yields per bin
Return type:: np.ndarray

cabinetry.histo.name(region: Dict[str, Any], sample: Dict[str, Any], systematic: Dict[str, Any], *, template: Literal['Up', 'Down'] | None = None) → str

Returns a unique name for each histogram.

If the template is not None, the systematic is required to have a name (guaranteed as long as it follows the config schema).

Parameters:

region (Dict[str, Any]) – containing all region information
sample (Dict[str, Any]) – containing all sample information
systematic (Dict[str, Any]) – containing all systematic information
template (Optional[Literal["Up", "Down"]], optional) – which template to consider: “Up”, “Down”, None for the nominal case, defaults to None

Returns:

unique name for the histogram

Return type:

str

cabinetry.templates

High-level entry point to create, collect and post-process template histograms.

cabinetry.templates.build(config: Dict[str, Any], *, method: str = 'uproot', router: Router | None = None) → None

Produces all required histograms specified by the configuration file.

Inputs to the histogram production are ntuples containing columnar data. Uses either a default method specified via method, or a custom user-defined override through router.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
method (str, optional) – backend to use for histogram production, defaults to “uproot”
router (Optional[route.Router], optional) – instance of cabinetry.route.Router that contains user-defined overrides, defaults to None

cabinetry.templates.collect(config: Dict[str, Any], *, method: str = 'uproot') → None

Collects all required histograms specified by the configuration file.

Histograms must already exist, and this collects and saves them in the format used for further processing. If no default for VariationPath is specified in the general settings, it defaults to an empty string.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
method (str, optional) – backend to use for histogram production, defaults to “uproot”

cabinetry.templates.postprocess(config: Dict[str, Any]) → None

Applies postprocessing to all histograms.

Parameters:: config (Dict[str, Any]) – cabinetry configuration

cabinetry.templates.builder

Creates required template histograms from columnar data.

cabinetry.templates.collector

Collects required template histograms provided by user.

cabinetry.templates.postprocessor

Applies optional post-processing to template histograms.

cabinetry.templates.postprocessor.apply_postprocessing(histogram: Histogram, name: str, *, smoothing_algorithm: str | None = None, nominal_histogram: Histogram | None = None) → Histogram

Returns a new histogram with post-processing applied.

The histogram handed to the function stays unchanged. A copy of the histogram receives post-processing and is then returned. The postprocessing consists of a fix for NaN statistical uncertainties and optional smoothing.

Parameters:

histogram (cabinetry.histo.Histogram) – the histogram to postprocess
name (str) – histogram name for logging
smoothing_algorithm (Optional[str]) – name of smoothing algorithm to apply, defaults to None (no smoothing done)
nominal_histogram (Optional[cabinetry.histo.Histogram]) – nominal histogram (needed for smoothing), defaults to None

Returns:

the histogram with post-processing applied

Return type:

cabinetry.histo.Histogram

cabinetry.templates.utils

Provides utilities for template histogram handling.

cabinetry.workspace

Constructs HistFactory workspaces in JSON format.

class cabinetry.workspace.WorkspaceBuilder(config: Dict[str, Any])

Collects functionality to build a pyhf workspace.

build() → Dict[str, Any]

Constructs a HistFactory workspace in pyhf format.

Returns:: pyhf-compatible HistFactory workspace
Return type:: Dict[str, Any]

channels() → List[Dict[str, Any]]

Returns the channel information: yields per sample and modifiers.

Returns:: channels for pyhf workspace
Return type:: List[Dict[str, Any]]

measurements() → List[Dict[str, Any]]

Returns the measurements object for the workspace.

Constructs the measurements, including POI setting and parameter bounds, initial values and whether they are set to constant. Only supports a single measurement so far.

Returns:: measurements for pyhf workspace
Return type:: List[Dict[str, Any]]

static normalization_modifier(systematic: Dict[str, Any]) → Dict[str, Any]

Returns a normalization modifier (OverallSys in HistFactory).

Parameters:: systematic (Dict[str, Any]) – systematic for which modifier is constructed
Returns:: single normsys modifier for pyhf workspace
Return type:: Dict[str, Any]

normfactor_modifiers(region: Dict[str, Any], sample: Dict[str, Any]) → List[Dict[str, Any]]

Returns the list of NormFactor modifiers acting on a sample in a region.

Parameters:

region (Dict[str, Any]) – specific region to get NormFactor modifiers for
sample (Dict[str, Any]) – specific sample to get NormFactor modifiers for

Returns:

NormFactor modifiers for sample

Return type:

List[Dict[str, Any]]

normplusshape_modifiers(region: Dict[str, Any], sample: Dict[str, Any], systematic: Dict[str, Any]) → List[Dict[str, Any]]

Returns modifiers for a correlated shape + normalization effect.

For a variation including a correlated shape + normalization effect, this provides the histosys and normsys modifiers for pyhf (in HistFactory language, this corresponds to a HistoSys and an OverallSys). Symmetrization could happen either at this stage (this is the case currently), or somewhere earlier, such as during template postprocessing. A histosys modifier is not created for single-bin channels, as it has no effect in this case (everything is handled by the normsys modifier already).

Parameters:

region (Dict[str, Any]) – region the systematic variation acts in
sample (Dict[str, Any]) – sample the systematic variation acts on
systematic (Dict[str, Any]) – the systematic variation under consideration

Raises:

ValueError – when both up and down variation specify symmetrization

Returns:

a list with a pyhf normsys modifier and a histosys modifier

Return type:

List[Dict[str, Any]]

observations() → List[Dict[str, Any]]

Returns the observations object (with data yields) for the workspace.

Returns:: observations for pyhf workspace
Return type:: List[Dict[str, Any]]

sys_modifiers(region: Dict[str, Any], sample: Dict[str, Any]) → List[Dict[str, Any]]

Returns the list of all systematic modifiers acting on a sample in a region.

Parameters:

region (Dict[str, Any]) – region considered
sample (Dict[str, Any]) – specific sample to get modifiers for

Raises:

NotImplementedError – when unsupported modifiers act on sample

Returns:

modifiers for pyhf workspace

Return type:

List[Dict[str, Any]]

cabinetry.workspace.build(config: Dict[str, Any], *, with_validation: bool = True) → Dict[str, Any]

Returns a HistFactory workspace in pyhf format.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
with_validation (bool, optional) – validate workspace validity with pyhf, defaults to True

Returns:

pyhf-compatible HistFactory workspace

Return type:

Dict[str, Any]

cabinetry.workspace.load(file_path_string: str | Path) → Dict[str, Any]

Loads a workspace from a file.

Parameters:: file_path_string (Union[str, pathlib.Path]) – path to the file to load the workspace from
Returns:: pyhf-compatible HistFactory workspace
Return type:: Dict[str, Any]

cabinetry.workspace.save(ws: Dict[str, Any], file_path_string: str | Path) → None

Serializes a workspace to a file.

Parameters:

ws (Dict[str, Any]) – pyhf-compatible HistFactory workspace
file_path_string (Union[str, pathlib.Path]) – path to the file to save the workspace in

cabinetry.workspace.validate(ws: Dict[str, Any]) → None

Validates a workspace with pyhf.

Parameters:: ws (Dict[str, Any]) – the workspace to validate

cabinetry.fit

High-level entry point for statistical inference.

Performs a maximum likelihood fit, reports and returns the results.

Depending on the custom_fit keyword argument, this uses either the pyhf.infer API or iminuit directly.

Parameters:

model (pyhf.pdf.Model) – model to use in fit
data (List[float]) – data (including auxdata) the model is fit to
minos (Optional[Union[str, List[str], Tuple[str, ...]]], optional) – runs the MINOS algorithm for all parameters specified, defaults to None (does not run MINOS)
goodness_of_fit (bool, optional) – calculate goodness of fit with a saturated model (perfectly fits data with shapefactors in all bins), defaults to False
init_pars (Optional[List[float]], optional) – list of initial parameter settings, defaults to None (use pyhf suggested inits)
fix_pars (Optional[List[bool]], optional) – list of booleans specifying which parameters are held constant, defaults to None (use pyhf suggestion)
par_bounds (Optional[List[Tuple[float, float]]], optional) – list of tuples with parameter bounds for fit, defaults to None (use pyhf suggested bounds)
strategy (Optional[Literal[0, 1, 2]], optional) – minimization strategy used by Minuit, can be 0/1/2, defaults to None (then uses pyhf default behavior of strategy 0 with user-provided gradients and 1 otherwise)
maxiter (Optional[int], optional) – allowed number of calls for minimization, defaults to None (use pyhf default of 100,000)
tolerance (Optional[float]), optional) – tolerance for convergence, for details see iminuit.Minuit.tol (uses EDM < 0.002*tolerance), defaults to None (use iminuit default of 0.1)
custom_fit (bool, optional) – whether to use the pyhf.infer API or iminuit, defaults to False (using pyhf.infer)

Returns:

object storing relevant fit results

Return type:

FitResults

cabinetry.fit.limit(model: Model, data: List[float], *, bracket: List[float] | Tuple[float, float] | None = None, poi_tolerance: float = 0.01, maxsteps: int = 100, confidence_level: float = 0.95, poi_name: str | None = None, init_pars: List[float] | None = None, fix_pars: List[bool] | None = None, par_bounds: List[Tuple[float, float]] | None = None, strategy: Literal[0, 1, 2] | None = None, maxiter: int | None = None, tolerance: float | None = None) → LimitResults

Calculates observed and expected upper parameter limits.

Limits are calculated for the parameter of interest (POI) defined in the model. Brent’s algorithm is used to automatically determine POI values to be tested. The desired confidence level can be configured, and defaults to 95%. In order to support setting the POI directly without model recompilation, this temporarily changes the POI in the model configuration.

Parameters:

model (pyhf.pdf.Model) – model to use in fits
data (List[float]) – data (including auxdata) the model is fit to
bracket (Optional[Union[List[float], Tuple[float, float]]], optional) – the two POI values used to start the observed limit determination, the limit must lie between these values and the values must not be the same, defaults to None (then uses 0.1 as default lower value and the upper POI bound specified in the measurement as default upper value)
poi_tolerance (float, optional) – tolerance in POI value for convergence to target CLs value (1-confidence_level), defaults to 0.01
maxsteps (int, optional) – maximum number of steps for limit finding, defaults to 100
confidence_level (float, optional) – confidence level for calculation, defaults to 0.95 (95%)
poi_name (Optional[str], optional) – limit is calculated for this parameter, defaults to None (use POI specified in workspace)
init_pars (Optional[List[float]], optional) – list of initial parameter settings, defaults to None (use pyhf suggested inits)
fix_pars (Optional[List[bool]], optional) – list of booleans specifying which parameters are held constant, defaults to None (use pyhf suggestion)
par_bounds (Optional[List[Tuple[float, float]]], optional) – list of tuples with parameter bounds for fit, defaults to None (use pyhf suggested bounds)
strategy (Optional[Literal[0, 1, 2]], optional) – minimization strategy used by Minuit, can be 0/1/2, defaults to None (then uses pyhf default behavior of strategy 0 with user-provided gradients and 1 otherwise)
maxiter (Optional[int], optional) – allowed number of calls for minimization, defaults to None (use pyhf default of 100,000)
tolerance (Optional[float]), optional) – tolerance for convergence, for details see iminuit.Minuit.tol (uses EDM < 0.002*tolerance), defaults to None (use iminuit default of 0.1)

Raises:

ValueError – if no POI is found
ValueError – if lower and upper bracket value are the same
ValueError – if starting brackets do not enclose the limit

Returns:

observed and expected limits, CLs values, and scanned points

Return type:

LimitResults

cabinetry.fit.print_results(fit_results: FitResults) → None

Prints the best-fit parameter results and associated uncertainties.

Parameters with zero uncertainty (those held fixed in the fit) are in addition denoted with “(constant)”.

Parameters:: fit_results (FitResults) – results of fit to be printed

cabinetry.fit.ranking(model: Model, data: List[float], *, fit_results: FitResults | None = None, poi_name: str | None = None, init_pars: List[float] | None = None, fix_pars: List[bool] | None = None, par_bounds: List[Tuple[float, float]] | None = None, strategy: Literal[0, 1, 2] | None = None, maxiter: int | None = None, tolerance: float | None = None, custom_fit: bool = False) → RankingResults

Calculates the impact of nuisance parameters on the parameter of interest (POI).

The impact is given by the difference in the POI between the nominal fit, and a fit where the nuisance parameter is held constant at its nominal value plus/minus its associated uncertainty. The “pre-fit impact” is obtained by varying the nuisance parameters by their uncertainty given by their constraint term.

Parameters:

model (pyhf.pdf.Model) – model to use in fits
data (List[float]) – data (including auxdata) the model is fit to
fit_results (Optional[FitResults], optional) – nominal fit results to use for ranking, if not specified will repeat nominal fit, defaults to None
poi_name (Optional[str], optional) – impact is calculated with respect to this parameter, defaults to None (use POI specified in workspace)
init_pars (Optional[List[float]], optional) – list of initial parameter settings, defaults to None (use pyhf suggested inits)
fix_pars (Optional[List[bool]], optional) – list of booleans specifying which parameters are held constant, defaults to None (use pyhf suggestion)
par_bounds (Optional[List[Tuple[float, float]]], optional) – list of tuples with parameter bounds for fit, defaults to None (use pyhf suggested bounds)
strategy (Optional[Literal[0, 1, 2]], optional) – minimization strategy used by Minuit, can be 0/1/2, defaults to None (then uses pyhf default behavior of strategy 0 with user-provided gradients and 1 otherwise)
maxiter (Optional[int], optional) – allowed number of calls for minimization, defaults to None (use pyhf default of 100,000)
tolerance (Optional[float]), optional) – tolerance for convergence, for details see iminuit.Minuit.tol (uses EDM < 0.002*tolerance), defaults to None (use iminuit default of 0.1)
custom_fit (bool, optional) – whether to use the pyhf.infer API or iminuit, defaults to False (using pyhf.infer)

Raises:

ValueError – if no POI is found

Returns:

fit results for parameters, and pre- and post-fit impacts

Return type:

RankingResults

cabinetry.fit.scan(model: Model, data: List[float], par_name: str, *, par_range: Tuple[float, float] | None = None, n_steps: int = 11, init_pars: List[float] | None = None, fix_pars: List[bool] | None = None, par_bounds: List[Tuple[float, float]] | None = None, strategy: Literal[0, 1, 2] | None = None, maxiter: int | None = None, tolerance: float | None = None, custom_fit: bool = False) → ScanResults

Performs a likelihood scan over the specified parameter.

If no parameter range is specified, center the scan around the best-fit result for the parameter that is being scanned, and scan over twice its uncertainty in each direction. The reported likelihood values are the differences between -2 log(L) at each point in the scan and the global minimum.

Parameters:

model (pyhf.pdf.Model) – model to use in fits
data (List[float]) – data (including auxdata) the model is fit to
par_name (str) – name of parameter to scan over
par_range (Optional[Tuple[float, float]], optional) – upper and lower bounds of parameter in scan, defaults to None (automatically determine bounds)
n_steps (int, optional) – number of steps in scan, defaults to 10
init_pars (Optional[List[float]], optional) – list of initial parameter settings, defaults to None (use pyhf suggested inits)
fix_pars (Optional[List[bool]], optional) – list of booleans specifying which parameters are held constant, defaults to None (use pyhf suggestion)
par_bounds (Optional[List[Tuple[float, float]]], optional) – list of tuples with parameter bounds for fit, defaults to None (use pyhf suggested bounds)
strategy (Optional[Literal[0, 1, 2]], optional) – minimization strategy used by Minuit, can be 0/1/2, defaults to None (then uses pyhf default behavior of strategy 0 with user-provided gradients and 1 otherwise)
maxiter (Optional[int], optional) – allowed number of calls for minimization, defaults to None (use pyhf default of 100,000)
tolerance (Optional[float]), optional) – tolerance for convergence, for details see iminuit.Minuit.tol (uses EDM < 0.002*tolerance), defaults to None (use iminuit default of 0.1)
custom_fit (bool, optional) – whether to use the pyhf.infer API or iminuit, defaults to False (using pyhf.infer)

Raises:

ValueError – if parameter is not found in model

Returns:

includes parameter name, scanned values and 2*log(likelihood) offset

Return type:

ScanResults

cabinetry.fit.significance(model: Model, data: List[float], *, poi_name: str | None = None, init_pars: List[float] | None = None, fix_pars: List[bool] | None = None, par_bounds: List[Tuple[float, float]] | None = None, strategy: Literal[0, 1, 2] | None = None, maxiter: int | None = None, tolerance: float | None = None) → SignificanceResults

Calculates the discovery significance of a positive signal.

Observed and expected p-values and significances are both calculated and reported.

Parameters:

model (pyhf.pdf.Model) – model to use in fits
data (List[float]) – data (including auxdata) the model is fit to
poi_name (Optional[str], optional) – significance is calculated for this parameter, defaults to None (use POI specified in workspace)
init_pars (Optional[List[float]], optional) – list of initial parameter settings, defaults to None (use pyhf suggested inits)
fix_pars (Optional[List[bool]], optional) – list of booleans specifying which parameters are held constant, defaults to None (use pyhf suggestion)
par_bounds (Optional[List[Tuple[float, float]]], optional) – list of tuples with parameter bounds for fit, defaults to None (use pyhf suggested bounds)
strategy (Optional[Literal[0, 1, 2]], optional) – minimization strategy used by Minuit, can be 0/1/2, defaults to None (then uses pyhf default behavior of strategy 0 with user-provided gradients and 1 otherwise)
maxiter (Optional[int], optional) – allowed number of calls for minimization, defaults to None (use pyhf default of 100,000)
tolerance (Optional[float]), optional) – tolerance for convergence, for details see iminuit.Minuit.tol (uses EDM < 0.002*tolerance), defaults to None (use iminuit default of 0.1)

Returns:

observed and expected p-values and significances

Return type:

SignificanceResults

cabinetry.fit.results_containers

Provides containers for inference results.

class cabinetry.fit.results_containers.FitResults(bestfit: ndarray, uncertainty: ndarray, labels: List[str], corr_mat: ndarray, best_twice_nll: float, goodness_of_fit: float = -1, minos_uncertainty: Dict[str, Tuple[float, float]] = {})

Collects fit results in one object.

Parameters:

bestfit (np.ndarray) – best-fit results of parameters
uncertainty (np.ndarray) – uncertainties of best-fit parameter results, evaluated with Hessian
labels (List[str]) – parameter labels
corr_mat (np.ndarray) – parameter correlation matrix
best_twice_nll (float) – -2 log(likelihood) at best-fit point
goodess_of_fit (float, optional) – goodness-of-fit p-value, defaults to -1
minos_uncertainty (Dict[str, Tuple[float, float]]) – uncertainties of best-fit parameter results indexed by parameter name, calculated with MINOS

best_twice_nll: float: Alias for field number 4

bestfit: ndarray: Alias for field number 0

corr_mat: ndarray: Alias for field number 3

goodness_of_fit: float: Alias for field number 5

labels: List[str]: Alias for field number 2

minos_uncertainty: Dict[str, Tuple[float, float]]: Alias for field number 6

uncertainty: ndarray: Alias for field number 1

class cabinetry.fit.results_containers.LimitResults(observed_limit: float, expected_limit: ndarray, observed_CLs: ndarray, expected_CLs: ndarray, poi_values: ndarray, confidence_level: float)

Collects parameter upper limit results in one object.

Parameters:

observed_limit (float) – observed limit
expected_limit (np.ndarray) – expected limit, including 1 and 2 sigma bands
observed_CLs (np.ndarray) – observed CLs values
expected_CLs (np.ndarray) – expected CLs values, including 1 and 2 sigma bands
poi_values (np.ndarray) – POI values used in scan
confidence_level (float) – confidence level used for parameter limits

confidence_level: float: Alias for field number 5

expected_CLs: ndarray: Alias for field number 3

expected_limit: ndarray: Alias for field number 1

observed_CLs: ndarray: Alias for field number 2

observed_limit: float: Alias for field number 0

poi_values: ndarray: Alias for field number 4

class cabinetry.fit.results_containers.RankingResults(bestfit: ndarray, uncertainty: ndarray, labels: List[str], prefit_up: ndarray, prefit_down: ndarray, postfit_up: ndarray, postfit_down: ndarray)

Collects nuisance parameter ranking results in one object.

The best-fit results per parameter, the uncertainties, and the labels should not include the parameter of interest, since no impact for it is calculated.

Parameters:

bestfit (np.ndarray) – best-fit results of parameters
uncertainty (np.ndarray) – uncertainties of best-fit parameter results
labels (List[str]) – parameter labels
prefit_up (np.ndarray) – pre-fit impact in “up” direction
prefit_down (np.ndarray) – pre-fit impact in “down” direction
postfit_up (np.ndarray) – post-fit impact in “up” direction
postfit_down (np.ndarray) – post-fit impact in “down” direction

bestfit: ndarray: Alias for field number 0

labels: List[str]: Alias for field number 2

postfit_down: ndarray: Alias for field number 6

postfit_up: ndarray: Alias for field number 5

prefit_down: ndarray: Alias for field number 4

prefit_up: ndarray: Alias for field number 3

uncertainty: ndarray: Alias for field number 1

class cabinetry.fit.results_containers.ScanResults(name: str, bestfit: float, uncertainty: float, parameter_values: ndarray, delta_nlls: ndarray)

Collects likelihood scan results in one object.

Parameters:

name (str) – name of parameter in scan
bestfit (float) – best-fit parameter value from unconstrained fit
uncertainty (float) – uncertainty of parameter in unconstrained fit
parameter_values (np.ndarray) – parameter values used in scan
delta_nlls (np.ndarray) – -2 log(L) difference at each scanned point

bestfit: float: Alias for field number 1

delta_nlls: ndarray: Alias for field number 4

name: str: Alias for field number 0

parameter_values: ndarray: Alias for field number 3

uncertainty: float: Alias for field number 2

class cabinetry.fit.results_containers.SignificanceResults(observed_p_value: float, observed_significance: float, expected_p_value: float, expected_significance: float)

Collects results from a discovery significance calculation in one object.

Parameters:

observed_p_value (float) – observed p-value
observed_significance (float) – observed significance
expected_p_value (float) – expected/median p-value
expected_significance (float) – expected/median significance

expected_p_value: float: Alias for field number 2

expected_significance: float: Alias for field number 3

observed_p_value: float: Alias for field number 0

observed_significance: float: Alias for field number 1

cabinetry.visualize

High-level entry point for visualizing fit models and inference results.

cabinetry.visualize.correlation_matrix(fit_results: FitResults, *, figure_folder: str | Path = 'figures', pruning_threshold: float = 0.0, close_figure: bool = True, save_figure: bool = True) → Figure

Draws a correlation matrix.

Parameters:

fit_results (fit.FitResults) – fit results, including correlation matrix and parameter labels
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
pruning_threshold (float, optional) – minimum correlation for a parameter to have with any other parameters to not get pruned, defaults to 0.0
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

Returns:

the correlation matrix figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.data_mc(model_prediction: ModelPrediction, data: List[float], *, config: Dict[str, Any] | None = None, figure_folder: str | Path = 'figures', log_scale: bool | None = None, log_scale_x: bool = False, channels: str | List[str] | None = None, colors: Dict[str, str] | None = None, close_figure: bool = False, save_figure: bool = True) → List[Dict[str, Any]] | None

Draws pre- and post-fit data/MC histograms for a pyhf model and data.

The config argument is optional, but required to determine correct axis labels and binning. The information is not stored in the model, and default values are used if no config is supplied. This allows quickly plotting distributions for models that were not created with cabinetry, and for which no config exists.

Parameters:

model_prediction (model_utils.ModelPrediction) – model prediction to show
data (List[float]) – data to include in visualization, can either include auxdata (the auxdata is then stripped internally) or only observed yields
config (Optional[Dict[str, Any]], optional) – cabinetry configuration needed for binning and axis labels, defaults to None (uses a default binning and labels then)
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
log_scale (Optional[bool], optional) – whether to use logarithmic vertical axis, defaults to None (automatically determine whether to use linear/log scale)
log_scale_x (bool, optional) – whether to use logarithmic horizontal axis, defaults to False
channels (Optional[Union[str, List[str]]], optional) – name of channel to show, or list of names to include, defaults to None (uses all channels)
colors (Optional[Dict[str, str]], optional) – map of sample names and colors to use in plot, defaults to None (uses default colors)
close_figure (bool, optional) – whether to close each figure, defaults to False (enable when producing many figures to avoid memory issues, prevents automatic rendering in notebooks)
save_figure (bool, optional) – whether to save figures, defaults to True

Raises:

ValueError – if color specification is incomplete

Returns:

list of dictionaries, where each dictionary: contains a figure and the associated region name, or None if no figure was produced

Return type:

Optional[List[Dict[str, Any]]]

cabinetry.visualize.data_mc_from_histograms(config: Dict[str, Any], *, figure_folder: str | Path = 'figures', log_scale: bool | None = None, log_scale_x: bool = False, channels: str | List[str] | None = None, colors: Dict[str, str] | None = None, close_figure: bool = False, save_figure: bool = True) → List[Dict[str, Any]]

Draws pre-fit data/MC histograms, using histograms created by cabinetry.

The uncertainty band drawn includes only statistical uncertainties.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
log_scale (Optional[bool], optional) – whether to use logarithmic vertical axis, defaults to None (automatically determine whether to use linear/log scale)
log_scale_x (bool, optional) – whether to use logarithmic horizontal axis, defaults to False
channels (Optional[Union[str, List[str]]], optional) – name of channel to show, or list of names to include, defaults to None (uses all channels)
colors (Optional[Dict[str, str]], optional) – map of sample names and colors to use in plot, defaults to None (uses default colors)
close_figure (bool, optional) – whether to close each figure, defaults to False (enable when producing many figures to avoid memory issues, prevents automatic rendering in notebooks)
save_figure (bool, optional) – whether to save figures, defaults to True

Raises:

ValueError – if color specification is incomplete

Returns:

list of dictionaries, where each dictionary contains a: figure and the associated region name

Return type:

List[Dict[str, Any]]

cabinetry.visualize.limit(limit_results: LimitResults, *, figure_folder: str | Path = 'figures', close_figure: bool = True, save_figure: bool = True) → Figure

Visualizes observed and expected CLs values as a function of the POI.

Parameters:

limit_results (fit.LimitResults) – results of upper limit determination
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

Returns:

the CLs figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.modifier_grid(model: Model, *, figure_folder: str | Path = 'figures', split_by_sample: bool = False, close_figure: bool = True, save_figure: bool = True) → Figure

Visualizes the modifier structure of a model in a 2d grid.

Parameters:

model (pyhf.pdf.Model) – model to visualize
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
split_by_sample (bool, optional) – whether to use (channel, parameter) grids for each sample, defaults to False (if enabled, uses (sample, parameter) grids for each channel)
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

cabinetry.visualize.pulls(fit_results: FitResults, *, figure_folder: str | Path = 'figures', exclude: str | List[str] | Tuple[str, ...] | None = None, close_figure: bool = True, save_figure: bool = True) → Figure

Draws a pull plot of parameter results and uncertainties.

Parameters:

fit_results (fit.FitResults) – fit results, including correlation matrix and parameter labels
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
exclude (Optional[Union[str, List[str], Tuple[str, ...]]], optional) – parameter or parameters to exclude from plot, defaults to None (nothing excluded)
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

Returns:

the pull figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.ranking(ranking_results: RankingResults, *, figure_folder: str | Path = 'figures', max_pars: int | None = None, close_figure: bool = True, save_figure: bool = True) → Figure

Produces a ranking plot showing the impact of parameters on the POI.

The parameters are shown in decreasing order of greatest post-fit impact.

Parameters:

ranking_results (fit.RankingResults) – fit results, and pre- and post-fit impacts
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
max_pars (Optional[int], optional) – number of parameters to include, defaults to None (which means all parameters are included)
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

Returns:

the ranking figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.scan(scan_results: ScanResults, *, figure_folder: str | Path = 'figures', close_figure: bool = True, save_figure: bool = True) → Figure

Visualizes the results of a likelihood scan.

Parameters:

scan_results (fit.ScanResults) – results of a likelihood scan
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
close_figure (bool, optional) – whether to close figure, defaults to True
save_figure (bool, optional) – whether to save figure, defaults to True

Returns:

the likelihood scan figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.templates(config: Dict[str, Any], *, figure_folder: str | Path = 'figures', close_figure: bool = False, save_figure: bool = True) → List[Dict[str, Any]]

Visualizes template histograms (after post-processing) for systematic variations.

The original template histogram for systematic variations (before post-processing) is also included in the visualization.

Parameters:

config (Dict[str, Any]) – cabinetry configuration
figure_folder (Union[str, pathlib.Path], optional) – path to the folder to save figures in, defaults to “figures”
close_figure (bool, optional) – whether to close each figure, defaults to False (enable when producing many figures to avoid memory issues, prevents automatic rendering in notebooks)
save_figure (bool, optional) – whether to save figures, defaults to True

Returns:

list of dictionaries, where each dictionary contains a: figure and the associated region / sample / systematic names

Return type:

List[Dict[str, Any]]

cabinetry.visualize.plot_model

Visualizes fit models with matplotlib.

cabinetry.visualize.plot_model.data_mc(histogram_dict_list: List[Dict[str, Any]], total_model_unc: ndarray, bin_edges: ndarray, *, figure_path: Path | None = None, log_scale: bool | None = None, log_scale_x: bool = False, label: str = '', colors: Dict[str, str] | None = None, close_figure: bool = False) → Figure

Draws a data/MC histogram with uncertainty bands and ratio panel.

Uncertainties for data points are drawn using the “Garwood” frequentist coverage interval as provided by hist via hist.intervals.poisson_interval.

Parameters:

histogram_dict_list (List[Dict[str, Any]]) – list of samples (with info stored in one dict per sample)
total_model_unc (np.ndarray) – total model uncertainty, if specified this is used instead of calculating it via sum in quadrature, defaults to None
bin_edges (np.ndarray) – bin edges of histogram
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
log_scale (Optional[bool], optional) – whether to use a logarithmic vertical axis, defaults to None (automatically determine whether to use linear or log scale)
log_scale_x (bool, optional) – whether to use logarithmic horizontal axis, defaults to False
label (str, optional) – label written on the figure, defaults to “”
colors (Optional[Dict[str, str]], optional) – map of sample names and colors to use in plot, defaults to None (uses default colors)
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Raises:

ValueError – when total model yield is negative in any bin

Returns:

the data/MC figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_model.modifier_grid(grid_list: List[ndarray], axis_labels: List[List[str]], category_map: Dict[int, str], figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws a grid of modifiers per channel, sample and parameter.

Parameters:

grid_list (List[np.ndarray]) – list of 2d grids with modifier information
axis_labels (List[List[str]]) – list with axis labels for the three axes in order (first axis is grid label, second and third are axes per grid)
category_map (Dict[int, str]) – translation of integer values in grid to labels
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

cabinetry.visualize.plot_model.templates(nominal_histo: Dict[str, ndarray], up_histo_orig: Dict[str, ndarray], down_histo_orig: Dict[str, ndarray], up_histo_mod: Dict[str, ndarray], down_histo_mod: Dict[str, ndarray], bin_edges: ndarray, variable: str, *, figure_path: Path | None = None, label: str = '', close_figure: bool = False) → Figure

Draws a nominal template and the associated up/down variations.

If a variation template is an empty dict, it is not drawn.

Parameters:

nominal_histo (Dict[str, np.ndarray]) – the nominal template
up_histo_orig (Dict[str, np.ndarray]) – original “up” variation
down_histo_orig (Dict[str, np.ndarray]) – original “down” variation
up_histo_mod (Dict[str, np.ndarray]) – “up” variation after post-processing
down_histo_mod (Dict[str, np.ndarray]) – “down” variation after post-processing
bin_edges (np.ndarray) – bin edges of histogram
variable (str) – variable name for the horizontal axis
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
label (str, optional) – label written on the figure, defaults to “”
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the template figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_result

Visualizes inference results with matplotlib.

cabinetry.visualize.plot_result.correlation_matrix(corr_mat: ndarray, labels: List[str] | ndarray, *, figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws a correlation matrix.

Parameters:

corr_mat (np.ndarray) – the correlation matrix to plot
labels (Union[List[str], np.ndarray]) – names of parameters in the correlation matrix
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the correlation matrix figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_result.limit(observed_CLs: ndarray, expected_CLs: ndarray, poi_values: ndarray, cls_target: float, *, figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws observed and expected CLs values as function of the parameter of interest.

Parameters:

observed_CLs (np.ndarray) – observed CLs values
expected_CLs (np.ndarray) – expected CLs values, including 1 and 2 sigma bands
poi_values (np.ndarray) – parameter of interest values used in scan
cls_target (float) – target CLs value to visualize as horizontal line
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the CLs figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_result.pulls(bestfit: ndarray, uncertainty: ndarray, labels: List[str] | ndarray, *, figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws a pull plot.

Parameters:

bestfit (np.ndarray) – best-fit parameter results
uncertainty (np.ndarray) – parameter uncertainties
labels (Union[List[str], np.ndarray]) – parameter names
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the pull figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_result.ranking(bestfit: ndarray, uncertainty: ndarray, labels: List[str] | ndarray, impact_prefit_up: ndarray, impact_prefit_down: ndarray, impact_postfit_up: ndarray, impact_postfit_down: ndarray, *, figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws a ranking plot.

Parameters:

bestfit (np.ndarray) – best-fit parameter results
uncertainty (np.ndarray) – parameter uncertainties
labels (Union[List[str], np.ndarray]) – parameter labels
impact_prefit_up (np.ndarray) – pre-fit impact in “up” direction per parameter
impact_prefit_down (np.ndarray) – pre-fit impact in “down” direction per parameter
impact_postfit_up (np.ndarray) – post-fit impact in “up” direction per parameter
impact_postfit_down (np.ndarray) – post-fit impact in “down” direction per parameter
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the ranking figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.plot_result.scan(par_name: str, par_mle: float, par_unc: float, par_vals: ndarray, par_nlls: ndarray, *, figure_path: Path | None = None, close_figure: bool = False) → Figure

Draws a figure showing the results of a likelihood scan.

Parameters:

par_name (str) – name of parameter used in scan
par_mle (float) – best-fit result for parameter
par_unc (float) – best-fit parameter uncertainty
par_vals (np.ndarray) – values used in scan over parameter
par_nlls (np.ndarray) – -2 log(L) offset at each scan point
figure_path (Optional[pathlib.Path], optional) – path where figure should be saved, or None to not save it, defaults to None
close_figure (bool, optional) – whether to close each figure immediately after saving it, defaults to False (enable when producing many figures to avoid memory issues, prevents rendering in notebooks)

Returns:

the likelihood scan figure

Return type:

matplotlib.figure.Figure

cabinetry.visualize.utils

Provides visualization utilities.

cabinetry.tabulate

Creates yield tables.

cabinetry.tabulate.yields(model_prediction: ModelPrediction, data: List[float], *, channels: str | List[str] | None = None, per_bin: bool = True, per_channel: bool = False, table_folder: str | Path = 'tables', table_format: str = 'simple', save_tables: bool = True) → Dict[str, List[Dict[str, Any]]]

Generates yield tables, showing model prediction and data.

Channels can be filtered via the optional channels argument. Either yields per bin, or yields per channel, or both can be shown.

Parameters:

model_prediction (model_utils.ModelPrediction) – model prediction to show in table
data (List[float]) – data to include in table, can either include auxdata (the auxdata is then stripped internally) or only observed yields
channels (Optional[Union[str, List[str]]], optional) – name of channel to show, or list of names to include, defaults to None (uses all channels)
per_bin (bool, optional) – whether to show a table with yields per bin, defaults to True
per_channel (bool, optional) – whether to show a table with yields per channel, defaults to False
table_folder (Union[str, pathlib.Path], optional) – path to the folder to save tables in, defaults to “tables”
table_format (str, optional) – format in which to save the tables, can be any of the formats tabulate supports (e.g. html, latex, plain, simple, tsv), defaults to “simple”
save_tables (bool, optional) – whether to save tables, defaults to True

Returns:

dictionary with yield tables for use with the tabulate package

Return type:

Dict[str, List[Dict[str, Any]]]

cabinetry.model_utils

Provides utilities for pyhf models.

class cabinetry.model_utils.ModelPrediction(model: Model, model_yields: List[List[List[float]]], total_stdev_model_bins: List[List[List[float]]], total_stdev_model_channels: List[List[float]], label: str)

Model prediction with yields and total uncertainties per bin and channel.

Parameters:

model (pyhf.pdf.Model) – model to which prediction corresponds to
model_yields (List[List[List[float]]]) – yields per channel, sample and bin, indices: channel, sample, bin
total_stdev_model_bins (List[List[List[float]]]) – total yield uncertainty per channel, sample and bin, indices: channel, sample, bin (last sample: sum over samples)
total_stdev_model_channels (List[List[float]]) – total yield uncertainty per channel and sample, indices: channel, sample (last sample: sum over samples)
label (str) – label for the prediction, e.g. “pre-fit” or “post-fit”

label: str: Alias for field number 4

model: Model: Alias for field number 0

model_yields: List[List[List[float]]]: Alias for field number 1

total_stdev_model_bins: List[List[List[float]]]: Alias for field number 2

total_stdev_model_channels: List[List[float]]: Alias for field number 3

cabinetry.model_utils.asimov_data(model: Model, *, fit_results: FitResults | None = None, poi_name: str | None = None, poi_value: float | None = None, include_auxdata: bool = True) → List[float]

Returns the Asimov dataset (optionally with auxdata) for a model.

Initial parameter settings for normalization factors in the workspace are treated as the default settings for that parameter. Fitting the Asimov dataset will recover these initial settings as the maximum likelihood estimate for normalization factors. Initial settings for other modifiers are ignored. If the fit_results keyword argument is used, the Asimov dataset is built to recover the fit results given when fitted again.

Parameters:

model (pyhf.Model) – the model from which to construct the dataset
fit_results (Optional[FitResults], optional) – parameter configuration to use when building the Asimov dataset (using the best-fit result), defaults to None (then a pre-fit Asimov dataset is built)
poi_name (Optional[str], optional) – name of parameter to set to a custom value via poi_value, defaults to None (use POI specified in workspace)
poi_value (Optional[float], optional) – custom value to set POI specified via poi_name to, defaults to None (no custom value set)
include_auxdata (bool, optional) – whether to also return auxdata, defaults to True

Returns:

the Asimov dataset

Return type:

List[float]

cabinetry.model_utils.asimov_parameters(model: Model) → ndarray

Returns a list of Asimov parameter values for a model.

For normfactors and shapefactors, initial parameter settings (specified in the workspace) are treated as nominal settings. This ignores custom auxiliary data set in the measurement configuration in the workspace.

Parameters:: model (pyhf.pdf.Model) – model for which to extract the parameters
Returns:: the Asimov parameters, in the same order as model.config.suggested_init()
Return type:: np.ndarray

cabinetry.model_utils.match_fit_results(model: Model, fit_results: FitResults) → FitResults

Matches results from a fit to a model by adding or removing parameters as needed.

If the fit results contain parameters missing in the model, these parameters are not included in the returned fit results. If the fit results do not include parameters used in the model, they are added to the fit results. The best-fit value for such parameters are the Asimov values as returned by asimov_parameters (initial parameter settings for unconstrained parameters), and the associated uncertainties as given by prefit_uncertainties (zero uncertainty for unconstrained or fixed parameters). These parameters furthermore are assumed to have no correlation with any other parameters. If required, parameters are re-ordered to match the target model.

Parameters:

model (pyhf.pdf.Model) – model to match fit results to
fit_results (FitResults) – fit results to be updated in order to match model

Returns:

fit results matching the model

Return type:

FitResults

cabinetry.model_utils.model_and_data(spec: Dict[str, Any], *, asimov: bool = False, include_auxdata: bool = True) → Tuple[Model, List[float]]

Returns model and data for a pyhf workspace specification.

Parameters:

spec (Dict[str, Any]) – a pyhf workspace specification
asimov (bool, optional) – whether to return the Asimov dataset, defaults to False
include_auxdata (bool, optional) – whether to also return auxdata, defaults to True

Returns:

a HistFactory-style model in pyhf format
the data (plus auxdata if requested) for the model

Return type:

Tuple[pyhf.pdf.Model, List[float]]

cabinetry.model_utils.prediction(model: Model, *, fit_results: FitResults | None = None, label: str | None = None) → ModelPrediction

Returns model prediction, including model yields and uncertainties.

If the optional fit result is not provided, the pre-fit Asimov yields and uncertainties are calculated. If the fit result is provided, the best-fit parameter values, uncertainties, and the parameter correlations are used to obtain the post- fit model and its associated uncertainties.

Parameters:

model (pyhf.pdf.Model) – model to evaluate yield prediction for
fit_results (Optional[FitResults], optional) – parameter configuration to use, includes best-fit settings and uncertainties, as well as correlation matrix, defaults to None (then the pre-fit configuration is used)
label (Optional[str], optional) – label to include in model prediction, defaults to None (then will use “pre-fit” if fit results are not included, and “post- fit” otherwise)

Returns:

model, yields and uncertainties per channel, sample, bin

Return type:

ModelPrediction

cabinetry.model_utils.prefit_uncertainties(model: Model) → ndarray

Returns a list of pre-fit parameter uncertainties for a model.

For unconstrained parameters the uncertainty is set to 0. It is also set to 0 for fixed parameters (similarly to how the post-fit uncertainties are defined to be 0).

Parameters:: model (pyhf.pdf.Model) – model for which to extract the parameters
Returns:: pre-fit uncertainties for the parameters, in the same order as model.config.suggested_init()
Return type:: np.ndarray

cabinetry.model_utils.unconstrained_parameter_count(model: Model) → int

Returns the number of unconstrained parameters in a model.

The number is the sum of all independent parameters in a fit. A shapefactor that affects multiple bins enters the count once for each independent bin. Parameters that are set to constant are not included in the count.

Parameters:: model (pyhf.pdf.Model) – model to count parameters for
Returns:: number of unconstrained parameters
Return type:: int

cabinetry.model_utils.yield_stdev(model: Model, parameters: ndarray, uncertainty: ndarray, corr_mat: ndarray) → Tuple[List[List[List[float]]], List[List[float]]]

Calculates symmetrized model yield standard deviation per channel / sample / bin.

Returns both the uncertainties per bin (in a list of channels and samples), and the uncertainty of the total yield per channel (again, for a list of channels and samples). To calculate the uncertainties for the total yield per channel, the function internally treats the sum of yields per channel like another channel with one bin. Similarly, the sum over samples is treated as another sample. The results of this function are cached to speed up subsequent calls with the same arguments.

Parameters:

model (pyhf.pdf.Model) – the model for which to calculate the standard deviations for all bins
parameters (np.ndarray) – central values of model parameters
uncertainty (np.ndarray) – uncertainty of model parameters
corr_mat (np.ndarray) – correlation matrix

Returns:

list of channels, each channel is a list of samples, and each sample a list of standard deviations per bin (the last sample corresponds to a sum over all samples)
list of standard deviations per channel, each channel is a list containing the standard deviations per sample (the last sample corresponds to a sum over all samples)

Return type:

Tuple[List[List[List[float]]], List[List[float]]]

cabinetry.smooth

Implements histogram smoothing algorithms.

cabinetry.smooth.smooth_353qh_twice(hist: T) → T

Runs the 353QH algorithm twice and returns smooth version of the input.

For documentation see these proceedings https://cds.cern.ch/record/186223/ on page 292. The algorithm runs twice to avoid over-smoothing peaks and valleys. The algorithm is not aware of statistical uncertainties per entry in the array. See also https://root.cern.ch/doc/master/classTH1.html#aeb935cae10dbf9cd484bee1b6a549f83 for the ROOT implementation.

Parameters:: hist (Union[list, np.ndarray]) – array to smooth
Returns:: smooth version of input
Return type:: Union[list, np.ndarray]

cabinetry.contrib

Basic implementations of functionality that can be provided by external tools.

cabinetry.contrib.histogram_creator

Creates histograms from ntuples with uproot.

cabinetry.contrib.histogram_creator.with_uproot(ntuple_paths: List[Path], pos_in_file: str, variable: str, bins: ndarray, *, weight: str | None = None, selection_filter: str | None = None) → Histogram

Reads an ntuple with uproot, fills and returns a histogram with the observable.

The paths may contain wildcards.

Parameters:

ntuple_paths (List[pathlib.Path]) – list of paths to ntuples
pos_in_file (str) – name of tree within ntuple
variable (str) – variable to bin histogram in
bins (np.ndarray) – bin edges for histogram
weight (Optional[str], optional) – event weight to extract, defaults to None (no weights applied)
selection_filter (Optional[str], optional) – filter to be applied on events, defaults to None (no filter)

Returns:

histogram containing data

Return type:

bh.Histogram

cabinetry.contrib.histogram_reader

Reads histograms with uproot.

cabinetry.contrib.histogram_reader.with_uproot(histo_path: str) → Histogram

Reads a histogram with uproot and returns it.

Parameters:: histo_path (str) – path to histogram, use a colon to distinguish between path to file and path to histogram within file (example: file.root:h1)
Returns:: histogram containing data
Return type:: bh.Histogram