v0.6.0

This minor release adds support for Python 3.11 and drops support for Python 3.7. It also adds support for customizing colors in data/MC figures (#399) and extends flexibility for histogram input path specification by allowing for SamplePath in systematic variations (#437).

Post-fit yield uncertainty calculations are now significantly faster and use less memory for complex workspaces (examples in #409, implementation in #408). Modifiers of histosys type are now only created when they have an effect (#398). There are also a few smaller bug fixes related to visualizing templates and type checking.

Breaking changes:

• dropped support for Python 3.7 (see #402)

Full list of changes:

• chore: updating version to 0.6.0 (#438)
• feat: support SamplePath overrides for histogram inputs (#437)
• feat: turn warnings about missing post-processed histograms into info messages (#436)
• chore: use 2x faster black mirror (#426)
• build: temporarily restrict latest typeguard to avoid dependency clash (#429)
• fix: handling spaces in histogram names for template visualization (#423)
• docs: improve yield prediction index descriptions (#420)
• build: drop explicit awkward dependency (#419)
• perf: drop use of awkward in yield uncertainty calculation (#408)
• fix: raise minimum Python version for type checking to 3.9 (#416)
• docs: fix return value type in docstring (#411)
• feat: denote constant parameters when printing fit results (#407)
• fix: adopt typeguard version 4.0 (#406)
• build: drop support for Python 3.7 (#402)
• fix: typing for file opened for writing with click (#403)
• feat: add Python 3.11 support (#400)
• feat: support custom colors for data/MC plots (#399)
• feat: skip histosys modifier creation for single-bin regions (#398)

Full Changelog: v0.5.2...v0.6.0

v0.5.2

This patch release fixes the pre-fit parameter uncertainty determination for partially fixed parameters such as staterror (#390) and the handling of negative model predictions in plots (#394). It also adds yield tables to the command line interface (#395) and improves editor autocompletion (#386).

Full list of changes:

• chore: updating version to 0.5.2 (#397)
• fix: handle negative model predictions in visualizations (#394)
• fix: parameter uncertainties for partially fixed parameters (#396)
• feat: command line interface for yield tables (#395)
• test: add test for builtin dir() (#393)
• fix: temporarily pin typeguard<3 (#392)
• chore: fix editor autocompletion (#386)
• build: revert flake8 pin (#384)
• style: apply Black's 2023 style (#383)
• fix: saturated likelihood evaluation with custom auxiliary data (#378)
• build: temporarily pin flake8<6 (#380)
• refactor: correlation matrix tick label rotation and alignment (#376)

Full Changelog: v0.5.1...v0.5.2

v0.5.1

This patch release adds the required lower bound to the matplotlib dependency and improves the ordering of nuisance parameters in the ranking visualization.

Full list of changes:

• chore: updating version to 0.5.1 (#375)
• feat: sort nuisance parameters by decreasing maximum impact in ranking plot (#373)
• build: raise minimum required matplotlib version to 3.5.0 (#370)
• ci: run mypy in Python 3.8 mode instead of Python 3.7 mode (#371)

Full Changelog: v0.5.0...v0.5.1

v0.5.0

This release adopts the pyhf 0.7 API (#301, #367) and adds support for Python 3.10 (#334). Yield tables are now returned (#338) and can be saved in various customizable formats (#351). They also include per-sample uncertainties now, which are calculated automatically (#356). New keyword arguments are available for configuring the optimizer via the fit API (#330, #360).

When building workspaces, specification of the POI is now optional (#348). New poi_name keyword arguments in the fit API allow setting the POI for ranking, limit and significance (#348, #364, #365). The automatic creation of staterror modifiers can be disabled per sample (#359). A new visualization utility has been added to visualize the modifier structure of models (#333). See below for the full list of additions.

The new features result in a few breaking changes, which are listed next.

Breaking changes:

• fit.limit keyword arguments tolerance and maxiter have been renamed to poi_tolerance and maxsteps (see #360).
  • This was required to support the optimizer configuration across the fit API with the same names used in pyhf (which include tolerance and maxiter).
• model_utils.ModelPrediction uncertainty structure now supports per-sample uncertainties, the shapes have changed accordingly.
  • model_utils.yield_stdev and model_utils.prediction return this new structure (see #356).
• tabulate.yields now returns a dictionary with yield tables, it previously returned None (see #338).

Full list of changes:

• chore: updating version to 0.5.0 (#368)
• build: Update lower bound of pyhf to v0.7.0 (#367)
• fix: compatibility with matplotlib 3.6 (#366)
• feat: customizable POI for significance (#365)
• fix: set POI for limit calculations via dedicated pyhf API (#364)
• feat: post-fit Asimov data generation (#363)
• feat: minimizer configuration for general inference (#360)
• build: Update lower bound of pyhf to v0.7.0rc2 (#361)
• feat: support disabling staterror per sample in workspace creation (#359)
• feat: restore optimizer settings after fits (#362)
• feat: rename model prediction variable in examples (#358)
• feat: yield uncertainties per sample (#356)
• feat: add suggested optional mypy checks (#355)
• fix: remove unnecessary dependencies for mypy (#353)
• feat: visualization of modifier structure in models (#333)
• test: disallow calling functions without type annotations (#352)
• feat: minimizer configuration for fit.fit (#330)
• feat: save yield tables (#351)
• feat: return yield tables (#338)
• feat: add version to command line interface (#350)
• fix: avoid mixing different versions of awkward in uproot5 tests (#349)
• feat: make POI optional in config and allow POI customization for inference (#348)
• feat: add Python 3.10 support (#334)
• fix: pyhf 0.7 compatibility (#301)
• docs: add conda-forge badge (#345)
• feat: explicitly set post-fit parameter errors to 0 for fixed parameters (#346)
• ci: update versions of GitHub actions and pre-commit (#343)
• ci: update GitHub actions (#337)
• fix: correct link to flake8 (#336)
• fix: bump black to 22.3.0 due to click 8.1 release (#335)
• build: remove wheel from build-system requirements (#331)

v0.4.1

This release fixes the contribution from staterror modifiers in the calculation of yield uncertainties (#323). The calculation of yield uncertainties is now vectorized, resulting in a significant speedup (#315). The calculation is two orders of magnitude faster for a moderately complex model. A change to the caching used in this calculation ensures that caching works even when recreating a model (#322).

The release furthermore includes a few improvements to the cabinetry.fit API: parameter settings (initial value, constant, bounds) can now be propagated (just like in pyhf, #320 and #321), and MINOS results are included in the container returned by maximum likelihood fits (#306).

Full list of changes:

• chore: updating version to 0.4.1 (#328)
• test: dedicated test for model keys (#327)
• perf: vectorize yield uncertainty calculation (#316)
• fix: per-channel yield uncertainty contribution from staterror-staterror terms (#324)
• perf: cache yield_stdev using spec and interpcodes of model (#322)
• feat: parameter customization for general inference (#321)
• feat: parameter customization for maximum likelihood fits (#320)
• test: increase log level for matplotlib in tests (#319)
• test: relax yield uncertainty tolerance in integration test (#318)
• style: apply black 22.1 formatting (#317)
• feat: customizable confidence level for upper parameter limits (#313)
• docs: update link to vCHEP 2021 proceedings (#314)
• fix: channel splitting for multi-channel model predictions (#312)
• fix: ranking plot axis limits for impacts (#309)
• feat: include MINOS uncertainties in fit results container (#306)
• fix: legend order in limit plot (#304)
• refactor: use pyhf API to split yields by channel (#303)
• fix: Use https protocol over unauthenticated git protocol (#302)
• fix: update uproot version for file writing fix (#300)
• fix: update uproot version to ensure trees are readable by old ROOT versions (#299)

v0.4.0

This release adds support for histogram inputs to workspace building and introduces a few breaking API changes. It also provides a new utility to match fit results to pyhf models (cabinetry.model_utils.match_fit_results). All keyword arguments are now keyword-only arguments: their associated keyword always needs to be used.

Histogram inputs for workspace building can be used with the new cabinetry.templates.collect API. The configuration schema has been expanded to support histogram inputs, and works in a very similar fashion to the specification of paths for ntuple inputs. See the documentation for more information.

The cabinetry.template_builder and cabinetry.template_postprocessor API has changed: the high-level functionality is now available via cabinetry.templates, and the lower-level functionality is provided in the submodules templates.builder and templates.postprocessor.

Breaking changes:

• contrib.histogram_creation has been renamed to contrib.histogram_creator, and the from_uproot function contained within to with_uproot (see #289). This function now returns a histogram instead of a tuple (see #281).
• Refactored template_builder and template_postprocessor, moved high-level functionality into new templates module and lower-level features into submodules templates.creator and templates.postprocessor (see #289).
  • template_builder.create_histograms -> templates.create
  • template_postprocessor.run -> templates.postprocess
• The SamplePaths configuration option is now called SamplePath (see #289).
• All keyword arguments in the API are now keyword-only arguments (see #294).

Full list of changes:

• chore: updating version to 0.4.0 (#298)
• build: exclude root files from source distribution (#297)
• feat: add codespell to pre-commit and fix typos (#296)
• feat: add pydocstyle to pre-commit and add missing docstrings (#295)
• feat: turn keyword arguments into keyword-only arguments (#294)
• feat: region- and sample-specific paths are optional for histogram inputs (#293)
• ci: run typeguard and backend tests for all Python versions (#292)
• feat: histogram inputs (#289)
• build: add utils to source distribution (#290)
• feat: utility to match fit results to arbitrary model (#288)
• feat: sample-specific Filter overrides (#286)
• fix: ratio panel in data/MC plots for bins with zero predicted yields (#287)
• feat: make Filter property of regions optional (#285)
• chore: update links after Scikit-HEP migration (#282)
• feat: return histogram instead of tuple from histogram creation backend (#281)
• ci: update package list (#280)

v0.3.0

This release adds the possibility to access figures produced by cabinetry for further customization and introduces a list of breaking API changes. It also adds more features to the specification of systematic uncertainties, labels to kinematic distributions, caching for yield uncertainty calculations, and additional validation for cabinetry configurations. The minimum required pyhf version for this version of cabinetry is 0.6.3, and Python 3.9 is now officially supported.

The cabinetry.visualize API has changed in several ways. Model predictions are no longer automatically produced within visualize.data_mc, but now have to be produced via model_utils.prediction. An optional fit_results argument allows to create post-fit distributions, and if it is not set, pre-fit distributions are produced. Example:

old:

cabinetry.visualize.data_mc(model, data, fit_results=fit_results)

new:

model_pred = cabinetry.model_utils.prediction(model, fit_results=fit_results)
cabinetry.visualize.data_mc(model_pred, data)

The yield table functionality has been removed from visualize.data_mc and is instead available via tabulate.yields, which also takes a model prediction as input. See #267 for more information about these changes.

Functions in the visualize module now return the figures they produce. The following functions return a single figure: correlation_matrix, pulls, ranking, scan, limit. The functions data_mc and templates can create more than one figure, and therefore return a list of dictionaries containing figures and relevant associated information (region name, or region / sample / systematic name, respectively).

Users may modify, customize and save the returned figures. A new save_figure argument has been added to the visualize API to turn off automatic saving if desired.

Breaking changes:

• Many functions in the public cabinetry API have been renamed. get_ prefixes have been removed from all function, and capitalization has been removed. Functionality from the contrib.visualize_matplotlib module has been split into visualize.plot_model, visualize.plot_results and visualize.utils (see #250). The following list shows changes other than the cases of removed get_ prefixes (see #263 for a full list).
  • histo.build_name -> hist.name
  • model_utils.build_Asimov_data -> model_utils.asimov_data
  • model_utils.calculate_stdev -> model_utils.yield_stdev
  • smooth.smooth_353QH_twice -> smooth.smooth_353qh_twice
  • visualize.data_MC_from_histograms -> visualize.data_mc_from_histograms
  • contrib.visualize_matplotlib.data_MC -> visualize.plot_model.data_mc
  • workspace.WorkspaceBuilder.get_NF_modifiers -> workspace.WorkspaceBuilder.normfactor_modifiers
  • WorkspaceBuilder.get_Normalization_modifier -> WorkspaceBuilder.normalization_modifier
• The template order in visualize.plot_model.templates has changed, it is now original up / down template, then modified up/down template (see #246).
• The method keyword argument has been removed from the visualize API, it previously only supported the default "matplotlib" (see #250).
• The internal handling of nominal templates in cabinetry has changed. As a consequence of this, the "_Nominal" suffix is no longer used in histogram names (see #260).
• In addition to this, the cabinetry.route.Router.register_template_builder API has changed: None is no longer accepted for region/sample/systematic, the corresponding behavior is now achieved via the default "*". The template can be set to None, in which case only nominal templates will be matched (see #260 and the documentation).
• Both workspace.WorkspaceBuilder.get_yield_for_sample and workspace.WorkspaceBuilder.get_unc_for_sample have been removed, as the functionality is more conveniently achieved via histo.Histogram.from_config directly and only nominal templates were supported (see #262).
• The order of keyword arguments in histo.Histogram.from_config changed: template and modified flipped places (see #262).
• The visualization.data_mc API has changed, this function no longer takes the optional fit results argument and now requires a model prediction (which can be created via model_utils.prediction) instead of a model (see #267).
• Yield tables have been removed from visualization.data_mc and moved to tabulate.yields (see #267).
• The inference result containers in the fit module have been moved to a fit.results_containers submodule: FitResults, RankingResults, ScanResults, LimitResults, SignificanceResults (see #267).
• The function model_utils.parameter_names was removed, it is now available via the model config in pyhf: model.config.par_names (see #248).
• The with_aux keyword arguments in model_utils.model_and_data and model_utils.asimov_data have been renamed to include_auxdata for consistency with pyhf (see #248).
• The test setup extra no longer includes all pyhf backends, they can now be installed via the new pyhf_backends setup extra (see #248).

Full list of changes:

• chore: updating version to 0.3.0 (#279)
• feat: Add MANIFEST.in (#278)
• feat: add Python 3.9 support (#277)
• fix: compatibility with pyhf 0.6.3 (parameter label API, auxdata) (#248)
• docs: multiple minor docstring fixes (#274)
• test: additional call argument formatting harmonization (#273)
• style: apply optional formatting to magic commas and strings (#272)
• feat: close single figures by default (#271)
• feat: use uproot4 for file writing (#256)
• refactor: correlation matrix and NLL access (#270)
• test: harmonize call argument formatting (#269)
• refactor: list conversions (#268)
• feat: model prediction API and yield table changes (#267)
• feat: yield uncertainty caching (#266)
• feat: return figures from visualizations (#264)
• feat: remove get prefixes from API and additional improvements (#263)
• refactor: streamline histogram loading (#262)
• build: list direct dependencies explicitly (#261)
• refactor: improved nominal template handling (#260)
• feat: validate uniqueness of names in config (#259)
• fix: configs without systematics (#258)
• feat: manual correlation of systematics (#257)
• fix: add missing template settings to config schema (#255)
• feat: variable overrides in systematic templates (#254)
• test: install Ghostscript in nightly tests (#253)
• refactor: use absolute imports (#252)
• feat: make matplotlib core dependency and refactor visualization code (#250)
• refactor: small string handling improvements (#249)
• feat: labels for data/MC and template visualizations (#246)
• test: increase integration test tolerance (#247)
• build: PEP 517/518 support (#245)

v0.2.3

This release fixes Asimov dataset generation for models with lumi modifiers. It also enables figure rendering in notebooks.

Full list of changes:

• chore: updating version to 0.2.3 (#244)
• docs: update readme and add talks to documentation (#243)
• fix: Asimov generation with lumi modifiers (#241)
• feat: notebook rendering for figures (#240)

v0.2.2

This release enables the use of all pyhf backends and adds a helper function to set up custom logging output. It also fixes Asimov dataset generation for models with shapesys modifiers.

To set a pyhf backend, use the pyhf API: pyhf.set_backend. This backend is no longer overridden within cabinetry and therefore used for inference and other operations in pyhf.

Full list of changes:

• chore: updating version to 0.2.2 (#239)
• fix: Asimov generation with shapesys modifiers (#238)
• feat: helper function for log formatting (#237)
• feat: support all pyhf backends (#228)
• fix: workaround for coverage bug (#234)
• fix: simplify example workspace and small type check fix (#235)
• chore: add standard venv names and notebook checkpoints to gitignore (#229)
• fix: compatibility with mypy 0.900 (#232)
• fix: NamedTuple compatibility in typeguard, Codecov token for upload (#230)
• refactor: histogram normalization (#226)
• test: extend coverage for workspace building (#225)

v0.2.1

This release fixes the goodness-of-fit calculation for models without auxiliary data. It also adopts the boost-histogram v1 API, and adds a command line interface for data/model plots. The config schema is expanded to allow for region-dependent samples, systematics, and normalization factors.

Breaking changes:

• workspace.WorkspaceBuilder.get_NF_modifiers signature has changed, the function now takes a region argument in addition to a sample argument.
• configuration.sample_affected_by_modifier is now called configuration.sample_contains_modifier for consistency with similar functions.

Full list of changes:

• chore: updating version to 0.2.1 (#224)
• ci: run mypy again with Python 3.7 (#223)
• feat: region-dependent modifiers (#220)
• chore: remove black version restriction and update pre-commit hook versions (#222)
• feat: make Samples property of modifiers optional (#218)
• feat: region-dependent samples (#217)
• ci: remove Codecov token (#215)
• fix: goodness-of-fit with no auxiliary data (#208)
• fix: skip typeguard 2.12 for NamedTuple compatibility (#209)
• fix: typing for registering custom template builders (#205)
• fix: compatibility with matplotlib 3.4 (#207)
• feat: boost-histogram 1.0 compatibility and typing updates (#204)
• feat: command line interface for data-MC plots (#203)
• chore: remove upper version limits for dependencies (#202)