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.

cabinetry.fit.fit(model: Model, data: List[float], *, minos: str | List[str] | Tuple[str, ...] | None = None, goodness_of_fit: bool = False, 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) FitResults

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