[cburgard]

Important

Depends on #23840. This branch is stacked on it: please review only the last 3 commits. It stays in draft until HS3 PR #126 is merged, and will be rebased when the PRs below it are merged.

Rebased onto master after the merge of #23996, including the follow-up commits added there during review (e.g. isHS3VersionBefore() instead of isLegacyHS3Version(), analyses named after their ModelConfig).

This Pull request:

Axis handling of RooFit's HS3 import/export, following two HS3 changes:

• HS3 PR #108 (merged): categorical axes in domains and data sets.
• HS3 PR #126 "Refactor axes": the storage order of multi-dimensional binned contents and of every other per-bin array is defined, with the last axis varying fastest.

The export of datasets and distributions with categories is not touched: it still uses the ROOT-internal combined form, until the HS3 representation of combined data (HS3 PR #119) is final. That is #24005, stacked on this one.

Changes or fixes:

1. Read categorical axes of domains and data (HS3 #108)

RooFit used to read a categorical domain axis ({"name": ..., "categories": [...]}) as an unbounded RooRealVar, losing the categories, and could not read categorical axes of data.

Where	Change
Domains	A categorical axis creates a RooCategory, one state per category, in the order of the document and with the position as index. An existing RooCategory of that name must have the same labels. The axis must not have min/max/nbins/edges; the labels must be unique non-empty strings. A string value in a parameter point sets the state.
Unbinned data	The entries of a categorical axis are labels of the category (declared by a domain).
Binned data	A categorical axis has one bin per category. HS3 identifies categories by name, so the data may list them in another order than the domain.
histfactory_dist	Categorical axes are rejected with an explicit error.

Category order in binned data. RooDataHist::calcTreeIndex() determines the bin of a category from the order of the states of the category it is given, not of its own. Data whose category lists the states in another order than the workspace category therefore gave swapped bins when looked up through the workspace category (as RooHistFunc/RooHistPdf, plotting or slicing do), even though the stored data was right. The data's category now takes over the states and their order from the workspace category, and readBinnedData() permutes contents and errors from the order of the document by label.

Test: CategoricalAxesInDomainsAndData (including data that lists the categories in another order than the domain, and invalid documents).

2. Pin the flattening order of binned contents (HS3 #126)

RooDataHist already stores its bins with the last variable varying fastest, and RooFit writes the axes in the order of the variables of the RooDataHist, so binned data needs no change. Test: FlatteningOrderOfBinnedContents.

HistFactory channels write the axes from the first sample's histogram, but the contents of every sample from its own histogram. If two histograms of a channel had their observables in different orders, the contents were silently written along different axes. This is now an explicit error.

3. Per-bin parameters of ParamHistFunc in HS3 bin order (HS3 #126)

ParamHistFunc orders its parameters like the bins of a TH1 (first variable fastest), the opposite of RooDataHist and of HS3. For two or more dimensions:

• the parameters of ParamHistFunc (step) and of the staterror and shapesys/shapefactor modifiers of histfactory_dist were written in a different order than the bin contents;
• on import, the relative uncertainty of bin k was paired with the k-th gamma in TH1 order, so the gammas of multi-dimensional HistFactory channels got the constraints of other bins.

The parameters are now converted at the HS3 boundary: written in bin order, paired with per-bin values in bin order, and only then put into TH1 order for the ParamHistFunc. One-dimensional functions are unchanged. Documents before HS3 0.3 with multi-dimensional ParamHistFuncs don't define the order; none are known, so they are rejected with an error instead of being guessed.

Tests: ExportedBinOrderFollowsAxes checks the order in the written file for binned data, RooHistFunc and ParamHistFunc, each built with both orders of its variables and a known value per bin, plus the round trip. HistFactoryMultiDimensionalBinOrder checks a two-dimensional channel with staterror: each gamma gets the uncertainty of its own bin, the ParamHistFunc returns the right gamma in every bin, the export keeps the order, and pre-0.3 documents are rejected.

Note: step (RooHistFunc, ParamHistFunc) is a RooFit-specific type, not part of the standard. RooParamHistFunc gets an HS3 export in #24002, as a product of the two kinds of step.

Checklist:

• tested changes locally
• updated the docs (if necessary)

Tests run (Linux, Ubuntu 26.04, GCC 15.2, RelWithDebInfo, -Droofit=ON -Dtesting=ON): testRooFitHS3 111 → 115 tests (4 new), testJSONInterface 1, testHistFactory 69, all passing; each commit built and tested on its own. clang-format clean.

AI assistance: Claude Code (claude-opus-5-5) implemented the changes, the tests and this description under review of the author. The commits carry Assisted-by: claude-code:claude-opus-5-5.

🤖 Generated with Claude Code