Cabinetry

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**: https://github.com/scikit-hep/cabinetry/compare/v0.5.2...v0.6.0

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**: https://github.com/scikit-hep/cabinetry/compare/v0.5.1...v0.5.2

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**: https://github.com/scikit-hep/cabinetry/compare/v0.5.0...v0.5.1

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)

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)

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)