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:_
python
cabinetry.visualize.data_mc(model, data, fit_results=fit_results)
_new:_
python
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)