Skip to content

[RF][HS3] Follow the HS3 0.3 specification fixes (HS3 #154) - #24201

Merged
guitargeek merged 24 commits into
root-project:masterfrom
cburgard:hs3-v03-spec-fixes
Nov 19, 2026
Merged

guitargeek merged 24 commits into
root-project:masterfrom
cburgard:hs3-v03-spec-fixes

Conversation

@cburgard

@cburgard cburgard commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

This Pull request:

Brings RooFit's HS3 import and export in line with HS3 PR
#154
("Fixes before v0.3"). That PR implements the decisions on HS3
#156
and the fixes of
#157.
Each commit is one change, with a test.

Commits 12–15 are a separate topic on top: the layouts in which the auxiliary measurements
(constraint terms) of HistFactory models are written. They don't depend on HS3 #154. Commits 17–19 keep documents
before 0.3 that are published on HEPData importable and writable.

Where HS3 0.3 now forbids or changes something that older documents rely on, the new behaviour applies to
documents with hs3_version 0.3 or later, and older documents are read as before, usually with a warning. The code
for the old behaviour (implicit HistFactory constraint terms, staterror gammas configured from the sample errors) is
kept, not removed: older documents need it, and it may be reactivated for constraint types that infer their strength
from the channel.

Note

HS3 #154 was merged on 2026-11-18 (merge commit
5570053).
All commits follow #154, including "data": null for pure models (HS3 commit
c67e621,
with the reading of the old placeholder restricted to "data": [0] in
0109565).

Changes or fixes:

# Commit Change Test
1 Leave infinite bounds of data axes out instead of writing null Continuous data axes omit an infinite bound (HS3 0.3 leaves null undefined); RooFit wrote null, or the largest double for constraint data. Import: an axis with one bound sets that bound only. The validator rejects infinite bounds on binned axes. UnboundedDataAxes
2 Write the location of landau_dist as "mu" HS3 renames mean → mu. Export writes mu; mean is still read (with a warning in ≥ 0.3 documents). LandauLocationKey
3 Follow the HS3 0.3 rules for "extended" on mixture_dist Missing flag with one coefficient per summand: rejected in ≥ 0.3. Explicit false with one coefficient per summand: honoured (built from the normalized coefficients c_i/Σc, not extendable) instead of a warning. Missing flag with n−1 coefficients: still accepted. No coefficients: read and written with a warning (undefined in 0.3). MixtureDistExtendedFlag (extended)
4 Translate TRUE, FALSE, === and !== in imported expressions Mapped to 1, 0, ==, != for TFormula. ExpressionBuiltins
5 Reserved names, and no distributions in generic expressions Objects named PI, EULER, TRUE, FALSE, ifelse or a function of the language: validator error for ≥ 0.3, warning otherwise and on export. A generic expression referring to a distribution: rejected on import (≥ 0.3). The export fails for anything that would be written as such an expression (RooFormulaVar/RooGenericPdf depending on a pdf, RooTFnBinding with a pdf, the transformation helpers of RooLognormal/RooExponential). Whether to allow generic_dist expressions on distributions later is discussed in HS3 #159. ReservedNamesAndDistributionReferences
6 Read and write point data as a RooDataSet with one entry point data (rejected so far) becomes a one-entry 1D RooDataSet; such a data set (one real variable, one unweighted entry) is written as point data with its axis, also for the constraint data of config().exportConstraintData. The provisional uncertainty is ignored with a warning. PointData
7 Data without axes: the single variate of the paired distribution An in-line number in data, or point data without axes, is the value of the single variate of the paired distribution; rejected if that can't be determined. In-line numbers become a point data set <distribution>_data. "data": [0], RooFit's old "no data" placeholder, keeps that meaning in documents before 0.3 in exactly this form (and, until the last commit, in documents RooFit wrote); a 0 in a longer array is a value. DataWithoutAxes
8 Check data axes against domains and paired distributions No fixed (value) axes in data sets; the axis of point data must be the variate of the paired distribution; a paired data axis and an analysis-domain axis for the same variate must give the same range (validator: error for ≥ 0.3, warning otherwise). DataAxesAgainstDomains
9 Require the constraints of HistFactory modifiers in the likelihood constraints of a modifier add no term in 0.3: each named distribution must contribute exactly once to every likelihood with the channel; ≥ 0.3 documents that don't are rejected. RooFit's export already lists them. Older documents: constraints are still added implicitly. HistFactoryConstraintsListedOnce
10 Don't derive the staterror gammas from the errors in HS3 0.3 For ≥ 0.3, the gammas with named constraints keep range and constness from the document and only get the uncertainty that their constraint encodes as initial error; they are configured from the sample errors only in older documents. Gammas without a constraint are left free in any version (master 25dc4e91aa6). RooFit's export writes fixed gammas as constant with a null constraint. StatErrorFromDocument
11 Write a model without data with "data": null A ModelConfig without matching data is written as a pure model, a likelihood with "data": null, instead of "data": [0], and read back as a ModelConfig without data. "data": [0] is still read as "no data" in documents before 0.3; any other 0 is a value. A pure model writes its constraint terms to aux_distributions also with config().exportConstraintData. PureModelLikelihood
12 Lognormals in the parametrization of RooFit as array components A RooLognormal in RooFit's default parametrization (median, shape) is written with mu/sigma naming the functions log(median)/log(shape). It could not be a component of an array_dist, so config().exportArrayDist and config().exportConstraintData had no effect on such constraints. It now can; the suffix convention is in two functions that the standalone and the array code share. ArrayDistOfLognormalsInRooFitParametrization
13 Valid names for functions of literal constants The helper function of a literal constant was named 1.2_lognormal_log or -0.1_exponential_inverted, which are not identifiers. The value is now spelled as one (const_1p2_lognormal_log, const_m0p1_exponential_inverted), with all digits needed to read it back unchanged (before: six). Names of the form const_<number> are reserved for this. The old names are still read. FunctionsOfLiteralConstantsHaveValidNames
14 Don't write helper objects that nothing refers to The RooProdPdf that holds the components of an imported array_dist together was written as a product_dist when arrays were switched off; read back, it kept the constraints from ever being collected into arrays again. Objects that RooFit creates to represent something it has no class for now carry the attribute hs3_helper: they are only written if something refers to them (or the HS3 object they stand for is written), and are otherwise ignored by the export. Not specific to arrays. HelperObjects
15 Test the auxiliary measurements of HistFactory models New test program testHS3AuxiliaryMeasurements: a three-channel HistFactory workspace with partially overlapping constraints (Gaussian, Poisson, and log-normal in two variants) is written in all four combinations of exportArrayDist × exportConstraintData and read back. Checks the layout, one array per constraint type, the workspace, a likelihood scan (fixed and profiled), toys, and every pair of layouts in sequence. testHS3AuxiliaryMeasurements (51 tests)
16 Remove the unused writeBound() from the document writer Commit 1 removed the last callers of writeBound() in HS3Writer.cxx but left the definition, which fails builds with -Werror (dev=ON) on -Wunused-function. Fix on top instead of in commit 1, to avoid rewriting the history; commits 1–15 therefore don't build on their own with dev=ON. builds with the CI flags of dev=ON
17 Accept data axes with a fixed "value" in documents before 0.3 Commit 8 rejected a data axis with value in documents of any version, but ROOT 6.34 wrote the observable of a data set like this (e.g. the top-quark mass likelihood on HEPData, INSPIRE 2894561). The parser now records it and the validator reports it: error for ≥ 0.3, warning otherwise. The value is not used, as before commit 8. DataAxesAgainstDomains (extended)
18 Accept histosys modifiers of the same name in documents before 0.3 The validator (already in master) rejects two histosys modifiers of the same name in a sample. ROOT wrote these for a parameter that interpolates a sample more than once (e.g. two VH likelihoods on HEPData, INSPIRE 2905253, ROOT 6.37). Now a warning before 0.3. They are read as one parameter with stacked effects: the parameter enters the interpolation once per modifier (only the histogram objects of the repeated modifier get a counter in their names). The export combines them into one modifier as before. Still an error for ≥ 0.3. HistFactoryHistoSysOfTheSameNameInOlderDocuments
19 Don't split a formula into modifiers if that makes the channel invalid The HistFactory export writes a RooFormulaVar factor of a sample that is a product as one modifier per factor. A parameter that occurs twice (b*b), or that the sample already has as a normfactor, became two normfactors of the same name, and the export failed (e.g. the ttbar/Z likelihoods on HEPData, INSPIRE 2689657, which could be imported but not written again). The export now checks the channel after splitting; if it is invalid for any reason and valid with the formulas of the channel as custom modifiers, they are written as custom modifiers. FormulaIsNotSplitIfThatMakesTheChannelInvalid
20 Count the contributions of a constraint through its data The exactly-once check of commit 9 counted how often a constraint is listed. It now counts through the paired data: a term once per entry of its data set, a component of a combined_dist through the component of the paired combined data with the same key (nothing if that is missing or empty). A region without data plus the measurement as its own term is one contribution (with a warning); a region without data and no measurement is rejected. Reported in the comments of this PR. HistFactoryConstraintContributionsCountData
21 Constraints with data as components of the combined distribution Export: with exportConstraintData, an array of constraints of a model that is a RooSimultaneous is a component of the combined_dist, with its data set as a component of the combined data set (before: a separate likelihood term). A channel that consists of constraint terms only is written once, as that channel, with the observed values from its global observables if its data is empty. A component of an array is never referred to by its own name. Marked in misc.ROOT_internal.auxiliary_channels. Import: by default, marked components are read as constraint terms with global observables, as before. EXPERIMENTAL config().importConstraintsAsChannels: they stay components of the RooSimultaneous with a one-entry data set, and HistFactory channels are built without them. A distribution that is a component without data and a term with data is read as the term (RooFit left it out of the likelihood before), with a warning. AuxiliaryMeasurementAsRegionOfTheModel, ConstraintsAsChannels, layout tests adapted
22 Describe the layout of constraint data in the configuration Comment of config().exportConstraintData. –
23 Constraints back into their channels on import, and two fixes Import: a constraint term with a global observable becomes a factor of every channel that is a product and uses its parameters, instead of an external constraint of the ModelConfig (the export takes them out of the channels; they did not come back, so the pdf was no longer the sampling distribution of those measurements: in the reported ATLAS Higgs workspace, 19 of 517 global observables were unreachable after a round trip). Penalty terms without an observation and constraints of non-product channels stay external. Export: the observable of a Gaussian constraint is determined before any pdf is written (it could be written with x/mean in the other order than its data set). Experimental import: an observation shared by two likelihoods gets one data set per combined data set. GaussianConstraintObservableBeforeItsChannel, AuxiliaryObservationSharedByTwoLikelihoods; ConstraintDataOfProductConstraints changed
24 Wrap channels that are no products with their constraints on import A component of a combined_dist that is no product (e.g. a single Gaussian) is wrapped in a RooProdPdf <channel>_with_constraints with the constraint terms of its parameters, so that the pdf of the model is the sampling distribution of its auxiliary measurements for such models too; RooFit takes the constraints out of the product when it builds a likelihood, as for a HistFactory channel. The name of the component changes once, in the first round trip. A global observable is recognized by nothing else in the model depending on it; an array of constraints goes into a channel as a whole. ConstraintsStayInTheSamplingDistribution

Not changed, by decision: the interpolation combinations that FlexibleInterpVar can't evaluate
(add/poly6/poly1, mult/poly6/poly1 for normsys) are still rejected, which HS3 0.3 requires of a reader that
can't evaluate them.

Behaviour changes users may notice

  • Documents with hs3_version 0.3 or later are checked more strictly. They are rejected for:
    • a mixture_dist without extended but with one coefficient per summand;
    • a reserved object name;
    • a generic expression that refers to a distribution (see HS3
      #159
      for allowing it in generic_dist later);
    • HistFactory constraints that the likelihood doesn't list exactly once;
    • a data axis whose range contradicts the domains of the analysis.
  • HistFactory staterror gammas of ≥ 0.3 documents are no longer fixed or ranged from the sample errors.
  • mixture_dist with "extended": false and one coefficient per summand is now not extendable.
  • Export:
    • unbounded data axes omit the bound;
    • landau_dist writes mu;
    • one-entry data sets are written as point data;
    • a ModelConfig without data is written with "data": null (commit 11);
    • log-normal constraints of HistFactory models in RooFit's default parametrization are collected into an
      array_dist and follow config().exportConstraintData (commit 12);
    • functions of literal constants are named const_<number>_<suffix> (commit 13); a parameter named
      const_<number> that needs such a function can't be exported;
    • with config().exportConstraintData, arrays of constraints are components of the model's combined_dist, and
      their data sets (now named <combined data>_<array>) components of the combined data set (commit 21);
    • with config().exportArrayDist = false, the product that held an imported array_dist together is no longer
      written as a product_dist, unless something uses it; its components are written on their own (commit 14).

Changed tests and reference data

  • MixtureDistExtendedFlag (commit 3): its last case expected a warning for "extended": false; it now checks that
    the mixture is not extendable and has the normalized shape. New cases for the missing flag.

  • Commit 9:

    • tutorials/roofit/roofit/rf515_hfJSON.json, and the hand-written 0.3 documents of
      HistFactoryArrayDistConstraints, HistFactoryArrayDistExport, HistFactoryConstraintTermsInLikelihood
      (twoChannelHistFactoryJSON()) and HistFactoryConstraintAlsoExternal: their likelihoods now list the
      constraints in aux_distributions.
  • Commit 11:

    • a hand-written document of ObservablesWithoutData uses "data": null instead of [0];
    • HistFactoryConstraintTermsInLikelihood imports a combined data set for its RooSimultaneous, so that the
      likelihood has data and the test still covers the data sets of constraint terms; expected data names adjusted.
  • StatErrorFromDocument (commit 10), changed in the rebase onto master 3aa99aad3f4: it expected the unconstrained
    gamma of a bin without uncertainty to be fixed in a document before 0.3. Master 25dc4e91aa6 leaves unconstrained
    gammas free in any version, so the test now expects that, and fixes the gamma by hand before the round trip that
    checks that a fixed gamma is written as fixed.

  • ConstraintDataOfProductConstraints (commit 23): it expected a constraint of a product to be an external constraint
    of the ModelConfig after a round trip. It now expects it to be a factor of the model again, and no external
    constraint.

  • Commits 12–15 change no existing test. Known limitation, unchanged: a workspace with
    Measurement::AddLogNormSyst() can't be exported (NormSysWithFunctionAsParameter).

Checklist:

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

Rebased again onto master 3aa99aad3f4, which includes 25dc4e91aa6 ("Fix HistFactory constraints, gammas and
older-document import"). Commit 10 conflicted with its new configuration of the gammas and was merged as described
in the table; the other conflicts were mechanical. At the tip, testRooFitHS3 (194 tests) and
testHS3AuxiliaryMeasurements (51 tests) pass, again with the HS3 library compiled from the branch against an
existing ROOT build, not through CMake: the new hs3cpp object library of master is not exercised by this. The 283
HS3 documents of the 17 records that HEPData lists under analysis:hs3 (all written by ROOT, HS3 0.1.90 and 0.2)
were surveyed: none has a staterror without a constraint type, so none is affected by the gamma changes. 44 of them
(at least one per resource) were imported before and after the rebase with identical variables; the three that
failed to import are fixed by commits 17–18. With commit 19, all 283 documents are imported, exported and imported
again without error, checked with the elective test of #24228 (run against the HS3 library of this branch); that
test lists four of them as expected failures on master, which have to be removed there or here, whichever is merged
second.

Commits 20–24 (auxiliary measurements as regions, reported in the comments): at the tip, testRooFitHS3 199 tests
and testHS3AuxiliaryMeasurements 63 tests pass (same private build), and all 283 HS3 documents from HEPData are
imported, exported and imported again without error. Limitations: a workspace read with
importConstraintsAsChannels is written without the constraints of its modifiers (same likelihood); without the
mark in misc, a component with one entry is always read as a channel; RooSimultaneous::generate() can't sample
such a model in one call, each component can be sampled by itself.

Before that, rebased onto master 7cc3f1b4474 ("Remove JSON I/O through export keys and factory expressions"): commit 2 now
changes the C++ importer and exporter of landau_dist that this master commit introduced, instead of the removed
export keys and factory expressions. After the rebase, testRooFitHS3 was built and run on each of the 15 commits
(158 tests at commit 1, 170 at the tip, all passing) and testHS3AuxiliaryMeasurements at the tip (51 passing), with
the HS3 library compiled from the branch against an existing ROOT build, not through CMake. The numbers below are
from before the rebase.

Tests run (Linux, GCC 13, RelWithDebInfo, -Droofit=ON -Dtesting=ON) on top of master 27fbb8dd02a:
testRooFitHS3 157 → 167 tests (10 new), testHistFactory 44, all passing. Every commit was built and tested on its
own (testRooFitHS3 and testHistFactory). clang-format clean.

Commits 12–15: testRooFitHS3 167 → 170 tests and the new testHS3AuxiliaryMeasurements (51 tests), all passing;
testRooFitHS3 was run on each of the commits 12–14. These were tested with the HS3 library and the two test
programs compiled from the branch against an existing ROOT build of this PR, not through CMake: the new
ROOT_ADD_GTEST line and a full build of commits 12–15 are untested. testHistFactory doesn't use the HS3 library
and was not rerun.

Not run: the PyROOT tests, the rf515_hfJSON.py tutorial (its JSON is covered by TutorialRF515RoundTrip), and the
optional HS3 test suite.

AI assistance: Claude Code (claude-opus-5-5) implemented the changes, the tests and this description from a list of
required changes that the author reviewed, under review of the author. The commits carry
Assisted-by: claude-code:claude-opus-5-5. Commits 12–24 were written by Claude Code (claude-fable-5-2) from an
audit of the export layouts and a check of the documents on HEPData that the author directed, and carry
Assisted-by: claude-code:claude-fable-5-2. It also did the rebases and their conflict resolutions.

🤖 Generated with Claude Code

@Phmonski

Copy link
Copy Markdown
Contributor

I can still reproduce auxiliary-region import/export failures with ROOT 6.43.01, commit ab36b0ca04cf1eb7ab076c7a47c484ebd9bf6ad9 (including the recent HS3 0.3, constraint-layout and logarithmic-PDF changes). exportArrayDist=True and allowExportSharedVariates=False throughout.

The application is an actual auxiliary measurement whose coordinate is declared in ModelConfig::GetGlobalObservables(). Fixed regularization penalties should retain their existing treatment. The goal is to retain the measurement in the sampling PDF, because XRooFit's Asimov generation does not incorporate a term merely because it appears in ExternalConstraints.

The region layout has an empty nonextended event-data component and one separate auxiliary observation. The group is reachable from the sampling PDF, while its measured values establish the global-observable roles. It restores inference, but exposes the following serialization and validation defects.

  1. Product region: export lists the grouped constraint and its scalar factors as likelihood contributions, then fails with shared variates (aux versus c1/c2). writeLikelihoodTermsOnce() cannot remove every factor without leaving an empty product.
  2. Array region: export can return success, but the likelihood references internal scalar names such as g1_constraint that were not written as distributions. Reimport fails. Scalar-to-array lookup in exportSingleModelConfig() is currently conditional on item.histFactory.
  3. Exactly-once validation: unlistedConstraintsOfDocument() traverses combined components without their paired data. It rejects a valid empty or missing nonextended auxiliary region plus one separate auxiliary observation as two contributions. Conversely, it can accept an empty region with no actual auxiliary observation as one contribution. Genuine duplicate observations must still be rejected.
  4. Component metadata: attributes are exported under scalar names that disappear when those PDFs are folded into an array, and are then lost on reimport.

The combined-distribution rules distinguish an absent region, an empty nonextended sample, and an empty extended sample. Reference reachability alone does not establish how many likelihood factors contribute.

The self-contained reproducer below runs no fits or toy ensemble. It reports four product/array round-trip cases and four HistFactory contribution-counting cases. Expected behaviour:

  • All four product/array cases complete two exports and reimports, retain two globals and the component attribute, and preserve the NLL.
  • histfactory_empty and histfactory_missing import successfully.
  • histfactory_double and histfactory_missing_observation are rejected.

On the unpatched build, all four round-trip cases fail; empty/missing regions are incorrectly rejected and the missing observation is incorrectly accepted.

Self-contained Python reproducer
"""Small HS3 auxiliary-region reproducer

Tests import plus two exports/reimports for product/array auxiliary regions,
and checks that empty/missing regions and real duplicate observations are distinguished.
"""
import os,resource,json,copy,sys
from pathlib import Path
import ROOT as R
R.gROOT.SetBatch(True);R.DisableImplicitMT()
R.RooMsgService.instance().setGlobalKillBelow(R.RooFit.WARNING)

def document(kind='array',hf=False):
    aux={'name':'aux','type':'array_dist','component_type':'gaussian_dist','default_parameters':{'sigma':1.},'components':[{'x':'g1','mean':'theta'},{'x':'g2','mean':'eta'}]}
    physics={'name':'physics','type':'gaussian_dist','x':'x','mean':'mean','sigma':1.}
    defs=[physics,aux,{'name':'model','type':'combined_dist','columns':['channel'],'components':[{'key':['physics'],'dist':'physics'},{'key':['auxiliary'],'dist':'aux'}]}]
    if kind=='product':
        aux.clear();aux.update({'name':'aux','type':'product_dist','factors':['c1','c2']})
        defs += [{'name':'c1','type':'gaussian_dist','x':'g1','mean':'theta','sigma':1.},{'name':'c2','type':'gaussian_dist','x':'g2','mean':'eta','sigma':1.}]
    axis={'name':'x','min':-5.,'max':5.}
    physical_data={'name':'physics_data','type':'unbinned','axes':[axis],'entries':[[-.4],[.2],[.7]]}
    if hf:
        axis.update({'min':0.,'max':2.,'nbins':2})
        physics.clear();physics.update({'name':'physics','type':'histfactory_dist','axes':[axis],'default_interpolation':{'type':'mult','in':'poly6','out':'exp'},'samples':[{'name':'signal','data':{'contents':[10.,15.]},'modifiers':[{'type':'normfactor','parameters':['mu']},{'name':'s1','type':'normsys','parameters':['theta'],'data':{'lo':.9,'hi':1.1},'constraints':['aux']},{'name':'s2','type':'normsys','parameters':['eta'],'data':{'lo':.8,'hi':1.2},'constraints':['aux']}]}]})
        physical_data={'name':'physics_data','type':'binned','axes':[axis],'contents':[10.,15.]}
    axes=[{'name':g,'min':-8.,'max':8.} for g in ['g1','g2']]
    return {'metadata':{'hs3_version':'0.3'},'distributions':defs,'functions':[] if hf else [{'name':'mean','type':'generic','expression':'mu+theta+eta'}],
      'data':[physical_data,{'name':'empty','type':'unbinned','axes':[],'entries':[]},{'name':'combData','type':'combined','columns':['channel'],'components':[{'key':['physics'],'dataset':'physics_data'},{'key':['auxiliary'],'dataset':'empty'}]},{'name':'measurement','type':'unbinned','axes':axes,'entries':[[.2,-.3]]}],
      'likelihoods':[{'name':'likelihood','distributions':['model','aux'],'data':['combData','measurement']}],
      'analyses':[{'name':'ModelConfig','likelihood':'likelihood','domains':['domain'],'parameters_of_interest':['mu']}],
      'domains':[{'name':'domain','type':'product_domain','axes':[{'name':'channel','categories':['physics','auxiliary']},axis,{'name':'mu','min':0. if hf else -3.,'max':3.},{'name':'theta','min':-3.,'max':3.},{'name':'eta','min':-3.,'max':3.},*axes]}],
      'parameter_points':[{'name':'default_values','parameters':[{'name':'mu','value':1.},{'name':'theta','value':0.},{'name':'eta','value':0.},{'name':'g1','value':.2,'const':True},{'name':'g2','value':-.3,'const':True}]}]}

def run_case(doc,roundtrip=False,explicit=False):
    config=R.RooJSONFactoryWSTool.config();config.exportArrayDist=True;config.exportConstraintData=explicit
    workspaces=[];result={'imported':False,'exported':0,'reimported':0}
    try:
        ws=R.RooWorkspace();workspaces.append(ws);assert R.RooJSONFactoryWSTool(ws).importJSONfromString(json.dumps(doc));result['imported']=True
        if not roundtrip:return result
        leaf=ws.pdf('c1') or ws.pdf('g1_constraint');leaf.setStringAttribute('aux_note','retained')
        reference=[];previous=None
        for generation in range(3):
            mc=ws.obj('ModelConfig');assert mc and mc.GetPdf().getPdf('auxiliary')
            assert len(mc.GetGlobalObservables())==2
            assert not mc.GetExternalConstraints() or len(mc.GetExternalConstraints())==0
            leaf=ws.pdf('c1') or ws.pdf('g1_constraint');assert leaf.getStringAttribute('aux_note')=='retained'
            encoded=str(R.RooJSONFactoryWSTool(ws).exportJSONtoString()) if generation<2 else None
            nll=mc.GetPdf().createNLL(ws.data('combData'),R.RooFit.GlobalObservables(mc.GetGlobalObservables()),R.RooFit.Offset(False))
            vals=[]
            for mu,theta,eta in [(1.,0.,0.),(.5,.4,-.5),(1.2,-.4,.5)]:
                for name,value in [('mu',mu),('theta',theta),('eta',eta)]:ws.var(name).setVal(value)
                vals.append(nll.getVal())
            if reference:assert max(abs(a-b) for a,b in zip(vals,reference))<1e-9
            else:reference=vals
            for name,value in [('mu',1.),('theta',0.),('eta',0.)]:ws.var(name).setVal(value)
            del nll
            if encoded:
                result['exported']+=1
                if previous:assert json.loads(previous)==json.loads(encoded),'document changed after first export'
                previous=encoded;ws=R.RooWorkspace();workspaces.append(ws)
                assert R.RooJSONFactoryWSTool(ws).importJSONfromString(encoded);result['reimported']+=1
        result['nll']=reference
    except Exception as exc:result['error']=str(exc)
    return result

results={}
for kind in ['product','array']:
    for explicit in [False,True]:results[kind+('_data' if explicit else '_implicit')]=run_case(document(kind),True,explicit)
for mode in ['empty','missing','double','missing_observation']:
    d=document(hf=True);data={x['name']:x for x in d['data']};lh=d['likelihoods'][0]
    if mode=='missing':data['combData']['components'].pop()
    if mode=='double':data['empty'].update({'axes':copy.deepcopy(data['measurement']['axes']),'entries':[[.2,-.3]]})
    if mode=='missing_observation':
        lh['distributions']=['model'];lh['data']=['combData'];d['data'].remove(data['measurement']);data['physics_data']['contents']=[0.,0.]
    results['histfactory_'+mode]=run_case(d)
output=Path(sys.argv[1]) if len(sys.argv)>1 else Path('reproducer_results.json')
output.write_text(json.dumps({'root':R.gROOT.GetVersion(),'commit':str(R.gROOT.GetGitCommit()),'results':results},indent=2)+'\n')
for name,result in results.items():print(name,json.dumps(result),flush=True)

AI assistance: Codex assisted with the reproducer, proposed implementation and numerical comparison. This draft and the patch need the author's technical review before posting/submission.

@Phmonski

Copy link
Copy Markdown
Contributor

Two issues remain in the RooFit/XRooFit workflow after the latest auxiliary-region changes.

The new grouped-region and contribution-counting tests pass. The following failures concern sampling-PDF preservation and a separate scalar-export ordering problem.

1. The default import still changes the expected p-value.

With importConstraintsAsChannels=False, an auxiliary region is read back as a constraint term. In the model, the 19 non-HistFactory constraints become external again. ModelConfig still declares 517 globals, but only 498 are reachable from its sampling PDF. XRooFit's Asimov generation consequently misses the same 19 observations.

The unchanged application call is:

w = ROOT.Experimental.XRooFit.xRooNode("119.json")
w.loadSnapshot("nominalGlobs")
nll = w["models/ModelConfig"].nll("combData", [ROOT.RooFit.Binned(1)])
hp = nll.hypoPoint(value=0, alt_value=1)
print(hp.pNull_asymp(nSigma=0).value())

The small reproducer below isolates the loss of PDF reachability without needing the Higgs files or running any fits. It prints:

original  globals=2  PDF contains globals=[True, True]    external=[]
roundtrip globals=2  PDF contains globals=[False, False]  external=['aux']
Reproducer 1: auxiliary globals leave the sampling PDF
"""A valid NLL round trip can remove auxiliary globals from the sampling PDF."""
import os,resource
os.environ['OMP_NUM_THREADS']='1'
resource.setrlimit(resource.RLIMIT_AS,(8*1024**3,8*1024**3))
import ROOT as R
R.gROOT.SetBatch(True)
w=R.RooWorkspace('original')
for definition in [
 'sum::mean(mu[1,0,3],theta[0,-3,3],eta[0,-3,3])',
 'Gaussian::physics(x[0,-5,5],mean,1)',
 'Gaussian::c1(g1[0.2,-8,8],theta,1)',
 'Gaussian::c2(g2[-0.3,-8,8],eta,1)',
 'PROD::aux(c1,c2)',
 'SIMUL::model(channel[physics,auxiliary],physics=physics,auxiliary=aux)',
]:
 assert w.factory(definition)
for name in ['g1','g2']:w.var(name).setConstant(True)
columns=R.RooArgSet(w.var('x'),w.cat('channel'))
data=R.RooDataSet('data','data',columns)
w.cat('channel').setLabel('physics')
for value in [-.4,.2,.7]:w.var('x').setVal(value);data.add(columns)
getattr(w,'import')(data)
mc=R.RooStats.ModelConfig('ModelConfig',w)
mc.SetPdf(w.pdf('model'));mc.SetObservables(columns)
mc.SetParametersOfInterest(R.RooArgSet(w.var('mu')))
mc.SetNuisanceParameters(R.RooArgSet(w.var('theta'),w.var('eta')))
mc.SetGlobalObservables(R.RooArgSet(w.var('g1'),w.var('g2')))
getattr(w,'import')(mc)
cfg=R.RooJSONFactoryWSTool.config()
cfg.exportArrayDist=True;cfg.exportConstraintData=True
cfg.importConstraintsAsChannels=False
encoded=str(R.RooJSONFactoryWSTool(w).exportJSONtoString())
v=R.RooWorkspace('roundtrip')
assert R.RooJSONFactoryWSTool(v).importJSONfromString(encoded)
for label,ws in [('original',w),('roundtrip',v)]:
 m=ws.obj('ModelConfig');g=m.GetGlobalObservables();external=m.GetExternalConstraints()
 print(label,'globals=',len(g),'PDF contains globals=',[bool(m.GetPdf().dependsOn(ws.var(n))) for n in ['g1','g2']], 'external=',[p.GetName() for p in external] if external else [],flush=True)

These are actual auxiliary measurements declared as global observables. The needed behaviour is to retain a sampling model that includes them, or make the consuming generation workflow explicitly include external auxiliary measurements. This does not require treating fixed regularizers as fluctuating observations.

2. exportConstraintData=True can write a document that cannot be reimported.

A scalar Gaussian can be emitted before its observed-coordinate hint is registered. The later point dataset then uses a different axis from the Gaussian's exported x:

constraint:      x=theta, mean=g
constraint_data: point(value=0), axis=g

Reimport fails with:

the axis 'g' of the point data set 'constraint_data' is not the variate
 'theta' of the distribution 'constraint' it is paired with

This also occurs in the original 119 GeV export for QCDscale_ggH2in_Pdf_data (QCDscale_ggH2in_In versus QCDscale_ggH2in). Both exportArrayDist and exportConstraintData are true.

The second reproducer fails as written. Changing only PROD::keep_scalar(constraint) to PROD::zz_keep_scalar(constraint) makes the Gaussian use x=g, mean=theta and reimport succeeds. The extra product is outside the fitted model; renaming it should not affect export correctness. The Gaussian exporter already has swapping logic, but its observable hint can arrive after the scalar PDF has been written. Collecting these hints before exporting PDFs would avoid the traversal-order dependency.

Reproducer 2: scalar Gaussian export depends on object traversal order

Run as python point_reproducer.py exported.json.

"""Reproduce the scalar-Gaussian point-data axis mismatch, without Higgs files.

An otherwise unused product keeps this HF constraint scalar even with arrays
on, as happens for shared constraints in the Higgs workspace.
"""
import os,resource,json,sys
from pathlib import Path
os.environ['OMP_NUM_THREADS']='1';resource.setrlimit(resource.RLIMIT_AS,(8*1024**3,8*1024**3))
import ROOT as R
R.gROOT.SetBatch(True);R.DisableImplicitMT()
doc={'metadata':{'hs3_version':'0.3'},'distributions':[
 {'name':'physics','type':'histfactory_dist','axes':[{'name':'x','min':0.,'max':2.,'nbins':2}],
  'default_interpolation':{'type':'mult','in':'poly6','out':'exp'},
  'samples':[{'name':'signal','data':{'contents':[10.,15.]},'modifiers':[
   {'type':'normfactor','parameters':['mu']},{'name':'s','type':'normsys','parameters':['theta'],'data':{'lo':.9,'hi':1.1},'constraints':['constraint']}]}]},
 {'name':'constraint','type':'gaussian_dist','x':'theta','mean':'g','sigma':1.}],
 'data':[{'name':'data','type':'binned','axes':[{'name':'x','min':0.,'max':2.,'nbins':2}],'contents':[10.,15.]}],
 'likelihoods':[{'name':'likelihood','distributions':['physics'],'data':['data'],'aux_distributions':['constraint']}],
 'analyses':[{'name':'ModelConfig','likelihood':'likelihood','domains':['domain'],'parameters_of_interest':['mu']}],
 'domains':[{'name':'domain','type':'product_domain','axes':[{'name':'x','min':0.,'max':2.,'nbins':2},{'name':'mu','min':0.,'max':3.},{'name':'theta','min':-3.,'max':3.},{'name':'g','min':-5.,'max':5.}]}],
 'parameter_points':[{'name':'default_values','parameters':[{'name':'mu','value':1.},{'name':'theta','value':0.},{'name':'g','value':0.,'const':True}]}]}
w=R.RooWorkspace('w');assert R.RooJSONFactoryWSTool(w).importJSONfromString(json.dumps(doc))
w.factory('PROD::keep_scalar(constraint)')
mc=w.obj('ModelConfig');mc.SetGlobalObservables(R.RooArgSet(w.var('g')))
c=R.RooJSONFactoryWSTool.config();c.exportArrayDist=True;c.exportConstraintData=True
encoded=str(R.RooJSONFactoryWSTool(w).exportJSONtoString());d=json.loads(encoded)
Path(sys.argv[1]).write_text(encoded+'\n')
print('constraint:',next(x for x in d['distributions'] if x['name']=='constraint'),flush=True)
print('measurement:',next(x for x in d['data'] if x['name']=='constraint_data'),flush=True)
v=R.RooWorkspace('roundtrip');assert R.RooJSONFactoryWSTool(v).importJSONfromString(encoded)
print('REIMPORT SUCCEEDED',flush=True)

The experimental importConstraintsAsChannels=True was also tried on the existing region encoding. It fails when the shared auxiliary observation is moved into both observed and stored-Asimov combined datasets: the component is reported as already belonging to another combined dataset. No high-dimensional generation was attempted in that mode.

AI assistance: Codex assisted with the reproducers and validation summary. Please review the technical details before posting.

@cburgard
cburgard marked this pull request as ready for review November 18, 2026 16:47
@cburgard

Copy link
Copy Markdown
Contributor Author

Here's a quick summary of my last 2 commits:

  1. Constraints go back into their channels on import. A constraint term with a global observable becomes a factor of every channel that uses its parameters. A channel that is not a product, such as the plain Gaussian in your first reproducer, is wrapped in a product named <channel>_with_constraints. Terms without an observation, like a fixed regularisation, stay external constraints, as you asked.
  2. Export order. Which of x and mean of a Gaussian constraint is the observable is now decided from the ModelConfigs' global observables before any pdf is written, so it no longer depends on the names of the pdfs. That was your second reproducer and the QCDscale_ggH2in case.
  3. importConstraintsAsChannels. An observation shared by two likelihoods now gets its own data set in each combined data set, which fixes the "already a component of another combined data set" failure.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Test Results

    13 files      13 suites   2d 6h 33m 11s ⏱️
 3 865 tests  3 864 ✅ 0 💤 1 ❌
46 706 runs  46 705 ✅ 0 💤 1 ❌

For more details on these failures, see this check.

Results for commit dd6905a.

♻️ This comment has been updated with latest results.

HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156) allows a continuous data axis
to omit `min` or `max`, which means that the axis is unbounded there, and
leaves JSON `null` undefined for bounds. RooFit wrote `null` for an
infinite bound of the axes of unbinned data, and the largest representable
number for the axes of constraint data. Both now leave the bound out, like
for domain axes. On import, an axis with only one bound sets that bound
and leaves the other side unbounded; before, the range was only set if
both bounds were given. `null` is still read for older documents.

Binned axes keep finite bounds; the validator now reports a binned axis
with an infinite bound.

Assisted-by: claude-code:claude-opus-5-5
HS3 0.3 (HS3 PR root-project#154) renames the key of the location parameter of
landau_dist from `mean` to `mu`, since it is neither the mean, which
doesn't exist, nor the most probable value of the distribution. RooLandau
is now written with `mu`. Documents before 0.3 used `mean`, which is still
read; in a document of version 0.3 or later it is read with a warning.

Assisted-by: claude-code:claude-opus-5-5
HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156) makes the `extended` flag of
`mixture_dist` required:

* With one coefficient per summand, the flag alone decides whether the
  mixture has a Poisson term, and a document without it is invalid. Such
  documents of version 0.3 or later are now rejected; older documents are
  read as before, as an extendable RooAddPdf.
* An explicit `"extended": false` with one coefficient per summand was
  read as an extendable RooAddPdf with a warning, since a RooAddPdf with
  one coefficient per summand can always be extended. It is now honoured:
  the RooAddPdf is built from the normalized coefficients c_i / sum(c),
  written as RooFormulaVars "<name>_fraction_<i>", of which the last one
  follows from the others. This is the same shape and can't be extended.
* With one coefficient fewer than summands, a missing flag is still
  accepted, as the standard allows.
* A mixture without coefficients, which RooFit reads as the sum of its
  extended summands, is not defined in HS3 0.3. It is still read and
  written, with a warning for documents of version 0.3 or later and on
  export.

The MixtureDistExtendedFlag test is extended accordingly; its last case,
which expected the warning for an explicit "false", now checks that the
mixture is not extendable and has the normalized shape.

Assisted-by: claude-code:claude-opus-5-5
The HS3 expression language has the boolean literals `TRUE` and `FALSE`
and the exact comparisons `===` and `!==`. RooFit translated only `PI`,
`EULER` and `ifelse()` for TFormula, so the others were looked up as
objects or failed to parse. They are now translated to `1`, `0`, `==` and
`!=`; the comparisons of TFormula are exact. HS3 PR root-project#154 also makes these
names reserved (decision on HS3 root-project#156).

Assisted-by: claude-code:claude-opus-5-5
HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156) reserves the names of the
expression language, i.e. PI, EULER, TRUE, FALSE, ifelse and its
functions, which no distribution, function or parameter may carry. A
reference in an expression evaluates to the value of a parameter,
variable or function; a reference to a distribution is invalid.

* The validator reports objects with a reserved name: an error for
  documents of version 0.3 or later, a warning otherwise and on export,
  like the other checks of the documents RooFit writes.
* A generic expression of a document of version 0.3 or later that refers
  to a distribution is rejected on import; older documents are read as
  before.
* The export fails for anything that would be written as an expression
  that refers to a pdf, since it can't be a valid document: a
  RooFormulaVar or RooGenericPdf that depends on a pdf, a RooTFnBinding
  with a pdf as observable or parameter, and the helper functions that
  transform a parameter of a RooLognormal or RooExponential if that
  parameter is a pdf.

Whether a later version should allow generic_dist expressions that
operate on distributions is discussed in HS3 root-project#159.

Assisted-by: claude-code:claude-opus-5-5
HS3 point data is the observation of a single variable. With its axis, it
is the same as unbinned data with a single entry (HS3 PR root-project#154). RooFit
rejected it on import. It is now read as a RooDataSet with one entry of
one variable, and such a data set (one real variable, one unweighted
entry) is written as point data with its axis. The observed values of
single constraint observables, which config().exportConstraintData
writes, are also point data now. The "uncertainty" of point data is
ignored with a warning, since HS3 doesn't define how it enters a
likelihood.

Point data without an axis gets its variable from the paired
distribution, which follows in a separate commit.

Assisted-by: claude-code:claude-opus-5-5
…ution

HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156) states how a number given
in-line in the "data" of a likelihood, or a point data set without axes,
is bound to a variable: it is the value of the single variate of the
paired distribution. If the variate can't be determined, the document is
rejected. RooFit parsed in-line numbers but never used them, and rejected
point data.

* A point data set without axes that a likelihood pairs with a
  distribution with a single variate is read as a RooDataSet with one
  entry of that variable. If it is paired with distributions of different
  variates, or the variate can't be determined, the document is rejected.
* An in-line number becomes a point data set "<distribution>_data" (with
  a suffix if the name is taken) of the variate of its distribution, which
  is then used like a data set the term refers to, e.g. as the observed
  value of a constraint term.

The variate is determined like for the check of distinct variates; a
distribution for which it is not a single name, like a product of
distributions, is rejected.

RooFit writes "data": [0] for a ModelConfig without data, with the number
0 as the only entry, which is not an observation. In this exact form it
stays that in documents before 0.3 (HS3 PR root-project#154), and for now also in
documents that carry RooFit's information about the ModelConfig of the
analysis, since that is what RooFit still writes. A 0 in a longer array is
a value like any other.

Assisted-by: claude-code:claude-opus-5-5
HS3 0.3 (HS3 PR root-project#154, decisions on HS3 root-project#156 and root-project#157) adds rules for the
axes of data sets:

* A fixed axis (with "value") is only allowed in domains. A data axis with
  "value" is rejected.
* The axis of point data is named like the variate of the paired
  distribution. A point data set whose axis is not that variate is
  rejected.
* A variate is normalized over the axis of the paired data set, or else
  over its axis in the domains of the analysis. If both exist, they must
  give the same range; an absent bound is equal only to an absent bound.
  The validator reports a difference: an error for documents of version
  0.3 or later, a warning for older ones.

RooFit itself keeps taking ranges from the default domain, or from the
first domain that lists a variable, for all analyses of a workspace; with
the new check, a document of version 0.3 can't contradict that for the
observables of its data sets.

Assisted-by: claude-code:claude-opus-5-5
…elihood

In HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156), a likelihood consists of
exactly the terms it lists, and the `constraints` of a HistFactory
modifier are a requirement that adds no term: every likelihood that
contains the channel must have each named distribution contribute exactly
once, through `distributions` or `aux_distributions`, or as a factor of a
`product_dist` or a component of a `combined_dist` reached from them.

For documents of version 0.3 or later, a likelihood that lists a named
constraint never, or more than once, is now rejected. RooFit's own export
already lists these terms in `aux_distributions`.

For older documents, nothing changes: RooFit still adds the constraints
named by the modifiers itself (likelihoodTerms()). That code stays, both
for older documents and for constraint types that might be able to infer
their terms from the channel in the future.

The rf515_hfJSON tutorial and the hand-written documents of version 0.3 of
the tests HistFactoryArrayDistConstraints, HistFactoryArrayDistExport,
HistFactoryConstraintTermsInLikelihood (twoChannelHistFactoryJSON()) and
HistFactoryConstraintAlsoExternal relied on the constraints being added
implicitly; their likelihoods now list them in "aux_distributions".

Assisted-by: claude-code:claude-opus-5-5
In HS3 0.3 (HS3 PR root-project#154, decision on HS3 root-project#156), the constraints that a
`staterror` modifier names are authoritative: a reader evaluates it like
a `shapefactor` and derives neither the constraint nor whether a gamma is
fixed from the `errors` of the samples. The relative uncertainty computed
from the errors is guidance for writers only.

RooFit computed the relative uncertainties from the samples and used
them to set the range, the error and the constness of the gammas with
named constraints. For documents of version 0.3 or later, this is no
longer done: the gammas keep the range from the domains and the
constness from the parameter points, and only get the uncertainty that
their constraint encodes as initial error. The derivation is kept for
older documents, and for the legacy constraint types, which create their
constraint terms from it. Gammas without a constraint are left free in
any version.

RooFit's export writes a fixed gamma, e.g. in a bin without uncertainty,
as constant with a null constraint, and the ranges of the gammas in the
domains, so the configuration survives a round trip. The new test
StatErrorFromDocument checks both.

Assisted-by: claude-code:claude-opus-5-5
A ModelConfig with a pdf, but without any data set in the workspace, is a
"pure model": it can be used to generate toys or an Asimov data set, but
there is no likelihood to evaluate before that. RooFit wrote it as a
likelihood with the number 0 in "data", which HS3 0.3 reads as an
observation of value 0 for the single variate of the distribution
(HS3 PR root-project#154).

Following HS3 PR root-project#154 (commit c67e621), a likelihood with "data": null now
marks such a pure model: it groups the distributions of a model so that an
analysis, and thus a ModelConfig, can refer to them, and it can't be used
as a likelihood before a data set is created.

* The typed document gets a term without data (std::monostate) and a flag
  for a pure-model likelihood; the parser reads and the writer writes
  "data": null.
* A ModelConfig without data is exported as a pure model.
* On import, a pure model gives a ModelConfig without data, like the
  number 0 did. The number 0 is still read as "no data" in documents
  before 0.3 in the exact form "data": [0], which is the only one older
  versions of RooFit wrote; a 0 in a longer array, or in documents of
  version 0.3 or later, is an observation like any other number.

A pure model has no data at all, so the constraint terms of its channels
are always written to "aux_distributions", with their observed values as
constant parameters, also with config().exportConstraintData, which
pairs them with data sets only in a likelihood with data.

Test changes: a hand-written document of the ObservablesWithoutData test,
which used the number 0 like RooFit, now uses "data": null. The
HistFactoryConstraintTermsInLikelihood test, which covers the data sets of
the constraint terms, had a ModelConfig without matching data; it now
imports a combined data set for its RooSimultaneous, so that the
likelihood has data, and its expected data names are adjusted.

Assisted-by: claude-code:claude-opus-5-5
…ents

A RooLognormal is by default parametrized by its median and shape
parameter, and is written as a lognormal_dist of the functions
"<median>_lognormal_log" and "<shape>_lognormal_log". Such a pdf could
not be a component of an array distribution, with two consequences for
the log-normal constraints of HistFactory models:

 - config().exportArrayDist had no effect on them: they were always
   written on their own, so there was no array per type of constraint;
 - config().exportConstraintData had no effect on them either, because
   the observable of a constraint is found by the same function: they
   stayed in "aux_distributions" instead of being paired with data.

The HS3 standard lets the components of an array distribution name
functions, so they are now written as components. On import, the
components already go through the importer of lognormal_dist, which
restores the parametrization of RooFit.

The convention of the suffix is now in two functions next to each other,
lognormalLogName() and lognormalParameters(), which the exporter and
importer of lognormal_dist and the array distribution all use.

Assisted-by: claude-code:claude-fable-5-2
A parameter of a RooFit class that is parametrized differently than its
HS3 distribution (RooLognormal, RooExponential) is written as a function
named after the parameter, e.g. "k_lognormal_log" for log(k). For a
literal constant, this gave names like "1.2_lognormal_log" or
"-0.1_exponential_inverted", which are no identifiers: HS3 requires the
names of functions to match [A-Za-z_][A-Za-z0-9_]*.

The value of a literal constant is now spelled as an identifier:
"const_1p2_lognormal_log", "const_m0p1_exponential_inverted",
"const_1em05_...". It is written with as many digits as it takes to read
it back unchanged. Before, the name of the RooConstVar was used, which
has six significant digits, so that the value changed in a round trip.
A negative value is put in parentheses in the expression ("-(-0.1)"
instead of "--0.1").

Names of the form "const_<number>" are thereby reserved: a function of a
parameter with such a name can't be written, because it could not be
told apart when reading. The names that older versions wrote are still
read.

Assisted-by: claude-code:claude-fable-5-2
RooFit has no class for an array distribution. When a document is read,
the components become individual pdfs, and a RooProdPdf holds them
together so that the array can be written again. HistFactory channels
use the components directly; the product is not part of any model.

If such a workspace was written without array distributions
(config().exportArrayDist = false), the product was written as a
product_dist that no likelihood contains, only because it is a pdf of
the workspace that nothing uses. Read back, it is an ordinary product
that refers to every constraint by name, so the constraints could never
be collected into arrays again: the flag had no effect anymore on any
later export.

The objects that RooFit creates to represent something of a document
that it has no class for are now marked with the attribute "hs3_helper".
A helper is no statement of the user about the model:

 - it is only written if another object that is written refers to it, if
   a ModelConfig names it, or if the HS3 object that it stands for is
   written (the array distribution), but not just because it is in the
   workspace;
 - a helper that is not written is ignored where the export looks at the
   users of an object: its components are top-level objects, which are
   written on their own, and it does not keep a constraint from being a
   component of an array.

The attribute is set by the importer of array_dist and is not written.
It is not specific to array distributions: other importers that build
composite structures can mark their parts in the same way. Objects of
users, also a product that a user marked as array distribution, are
written as before.

Assisted-by: claude-code:claude-fable-5-2
A HistFactory workspace built by MakeModelAndMeasurementFast() is
written to HS3 in every layout of the auxiliary measurements that
config().exportArrayDist and config().exportConstraintData select: the
constraint terms in "aux_distributions" or paired with data, on their
own or collected into one array distribution per type. The model has
three channels whose sets of constrained parameters overlap partially,
with Gaussian and Poisson constraints; two variants add a log-normal
constraint in either parametrization of RooLognormal.

For every model and layout, the test checks that

 - the document has the layout that the flags select, with exactly one
   array distribution per type of constraint, and every constraint term
   once in each likelihood;
 - the workspace that is read back has the same ModelConfig, data,
   variables and constraints, and gives the same document when written
   again;
 - a likelihood scan gives the same values, with the nuisance parameters
   fixed and profiled;
 - toys are identical for all layouts, a toy of either model gives the
   same likelihood in the original and the imported model, and the
   sampled distributions agree over many toys;
 - the global observables stay constant RooRealVars, the likelihood
   stays the same, and the layout is the one that was asked for, when the
   layout changes between two exports, for every pair of layouts.

The names of the constraint pdfs and which of x and mean of a Gaussian
is the global observable are not part of the model and not compared.

Assisted-by: claude-code:claude-fable-5-2
Since "Leave infinite bounds of data axes out instead of writing null",
no axis writes an infinite bound as null anymore, and writeBound() in
HS3Writer.cxx has no caller. Builds with -Werror (dev=ON) fail with
-Wunused-function.

Assisted-by: claude-code:claude-fable-5-2
HS3 0.3 allows a fixed axis (with "value") only in domains, and the
parser rejected a data axis with "value" in documents of any version.
ROOT 6.34 wrote the observable of a data set like this, e.g. in the
likelihood of the ATLAS top-quark mass measurement on HEPData (INSPIRE
2894561, HS3 0.2), which could no longer be imported.

The parser now only records that the axis has a "value", and the
validation reports it: as an error for documents of version 0.3 or
later, and as a warning for older ones, like the other rules that came
with 0.3. As before the check was added, the value itself is not used.

Assisted-by: claude-code:claude-fable-5-2
…ore 0.3

The validation rejects a sample with two histosys modifiers of the same
name, because their histograms are named after the modifier. ROOT wrote
such documents, though: a parameter that interpolates a sample more than
once became several histosys modifiers of the same name. Two of the
likelihoods of the ATLAS VH measurement on HEPData (INSPIRE 2905253,
HS3 0.2, written by ROOT 6.37) are like this and could no longer be
imported.

For documents before HS3 0.3, this is now a warning instead of an
error, and the import tells the histograms of the repeated modifiers
apart by a counter. Each modifier becomes one entry of the
PiecewiseInterpolation, as written. The export already combines several
histosys modifiers of one parameter into one, so writing the model
again gives a document that is valid in the current version. Documents
of version 0.3 or later with such modifiers are rejected as before.

Assisted-by: claude-code:claude-fable-5-2
…nel invalid

The HistFactory export writes a RooFormulaVar among the factors of a
sample that is a product as one modifier per factor: a bare parameter
becomes a normfactor. A parameter that occurs twice in the formula, e.g.
in "b*b", became two normfactors of the same name, which can't be
combined into one, so the export failed. The same happens if the sample
already has a normfactor of that parameter. The likelihoods of the ATLAS
ttbar/Z cross-section measurement on HEPData (INSPIRE 2689657), which
use the square of a b-tagging efficiency like this, could be imported
but not written again.

The export now checks the channel after splitting formulas, with the
checks of a HistFactory distribution and the combination of duplicate
modifiers. If it is invalid for any reason, and valid when the formulas
of the channel are written as custom modifiers like other functions,
they are written as custom modifiers. A channel that is invalid either
way is reported as before.

Assisted-by: claude-code:claude-fable-5-2
The check that every constraint named by a HistFactory modifier
contributes exactly once to a likelihood (HS3 0.3) counted how often the
constraint is listed, also as a component of a combined distribution.
But a distribution contributes one factor per entry of the data it is
paired with. A constraint that is a region of the model, so that it is
part of the sampling distribution, and also a term of its own paired
with the measurement, was rejected as contributing twice, although the
region has no data. Before the check was added, such documents were
read. Conversely, a constraint that is only a region without data was
accepted as one contribution, although nothing is observed.

The contributions are now counted with the paired data: a term counts
once per entry of its data set, and a component of a combined
distribution through the component of the paired combined data set with
the same key, i.e. not at all if that is missing or has no entries.

* A region without data plus the measurement as a separate term is one
  contribution. Since listing a constraint in the model and again on its
  own is probably not intended, there is a warning.
* A component of a combined distribution without any data component
  gives a warning.
* The measurement both as the data of the region and as a separate term
  is still rejected, as two contributions.
* A region without data and no measurement is now rejected: it is no
  observation.

Reported on the pull request, with a reproducer whose four HistFactory
cases are the new test HistFactoryConstraintContributionsCountData.

Assisted-by: claude-code:claude-fable-5-2
…ution

An auxiliary measurement that is part of the model, a region whose pdf
consists of constraint terms, could not be written: for a product, the
group and its factors were both listed in the likelihood, and the export
stopped at the shared variates; for an array, the likelihood named the
components of the array, which have no name in the document, and the
document could not be read back. Reported on the pull request.

Export:

* With config().exportConstraintData, an array of constraints of a model
  that is a RooSimultaneous is written as a component of the combined
  distribution, and the data set with its observed values as a component
  of the combined data set, instead of as a separate term of the
  likelihood. The two are the same likelihood, but the combined
  distribution is then the sampling distribution of all measurements.
  Each combined data set gets a data set of its own, named like its
  other components. Single constraints stay terms of the likelihood, as
  do the constraints of models with several index columns.
* A channel of the model that consists of constraint terms only is
  written once, as that channel. If its data set has no entries, the
  observed values are taken from its global observables.
* A component of an array is never referred to by its own name, whatever
  kind of channel its constraint belongs to.
* The components that are auxiliary measurements are marked in
  misc.ROOT_internal.auxiliary_channels.

Import:

* By default, marked components are read as before: as constraint terms
  with global observables. Without the mark, RooFit can't tell an
  auxiliary measurement from a channel with one event.
* EXPERIMENTAL, with the new config().importConstraintsAsChannels: they
  stay components of the RooSimultaneous, with their data set of one
  entry in the combined data set. HistFactory channels are then built
  without the constraints that are measurements of their own. A
  workspace read like this is written without the "constraints" of its
  modifiers; the likelihood is the same.
* A distribution that is a component without data and also a term with
  data contributes once. RooFit left such a term out of the likelihood,
  because a component without data is no constraint term for it. It is
  now read as the term (or, with the option, as the component with the
  data of the term), with a warning.

The layout tests are adapted, check the constraint terms of every
channel after a round trip, and have a case for the experimental import.
The new test AuxiliaryMeasurementAsRegionOfTheModel has the reported
round trips, with the likelihood compared to its analytic value in every
generation.

Assisted-by: claude-code:claude-fable-5-2
The comment of config().exportConstraintData still described the layout
before the previous commit.

Assisted-by: claude-code:claude-fable-5-2
Follow-up to the auxiliary measurements, from a second report on the
pull request with a published workspace (ATLAS Higgs combination).

* On import, a constraint term with a global observable becomes a factor
  of every channel that is a product and depends on one of its other
  parameters, instead of an external constraint of the ModelConfig. The
  export takes the constraints out of the channel products, since a
  likelihood lists each term once; the import now puts them back, as
  HistFactory builds its models. The pdf of the model is then the
  sampling distribution of the auxiliary measurements again. In the
  reported workspace, 19 of 517 global observables were no longer
  reachable from the pdf after a round trip, which changed expected
  p-values from Asimov data sets generated from it. Terms without a
  global observable, e.g. the regularization of an unfolding, and the
  constraints of channels that are not products stay external
  constraints.
* A Gaussian constraint is written with its global observable as "x".
  Which of x and mean that is was recorded when the channel that names
  the constraint was written, which could be after the constraint
  itself: the document then paired the constraint with a data set of
  another axis and could not be read. It is now determined from the
  global observables of the ModelConfigs before any pdf is written.
* EXPERIMENTAL import of constraints as channels: an observation that is
  a term of two likelihoods gets a data set for each of their combined
  data sets, since a data set can only be a component of one.

ConstraintDataOfProductConstraints expected the constraint to be an
external constraint after a round trip; it now expects it in the model.
New tests: GaussianConstraintObservableBeforeItsChannel and
AuxiliaryObservationSharedByTwoLikelihoods.

Assisted-by: claude-code:claude-fable-5-2
…n import

The previous commit puts the constraint terms of a model back into its
channels on import, but only into channels that are products. A channel
of another kind, e.g. a single Gaussian, kept its constraints as
external constraints of the ModelConfig, so that the pdf of the model
was still not the sampling distribution of the auxiliary measurements
(the first reproducer of the report on the pull request).

A component of a combined distribution that is no product is now wrapped
in a RooProdPdf "<channel>_with_constraints" with the constraint terms
of its parameters, which are the other terms of the likelihoods that
have the combined distribution. This is done when the combined
distribution is read, since the components of a RooSimultaneous can't be
replaced later. RooFit takes the constraints out of such a product when
it builds a likelihood, as for a HistFactory channel; the new test
ConstraintsStayInTheSamplingDistribution compares that likelihood, built
from the pdf and the global observables alone, with its analytic value.
Written again, the wrapper is a product_dist of its channel, so the name
of the component changes once, in the first round trip.

A global observable of a constraint is now recognized by nothing else in
the model depending on it, not by being constant: its value can come
from the data set of the constraint, which is read later. An array of
constraints goes into a channel as a whole, since its components have no
names in a document.

Assisted-by: claude-code:claude-fable-5-2
cburgard added a commit to cburgard/root that referenced this pull request Nov 19, 2026
HS3 root-project#161 was revised: the likelihood is the plain product of its terms,
and union composition applies only within a listed distribution (combined
and array distributions). Distributions that share factors, e.g. the
models of a combination with common constraint terms, are joined in a
combined distribution, which may contain combined distributions itself.

* Distinct variates: each term of a likelihood is the union of its parts
  (components of combined distributions, recursively, and of array
  distributions), in which identical parts count once; a variate of two
  terms is shared, also by identical parts. Components of a combined
  distribution whose sub-data set is missing or empty contribute nothing
  and are left out. The axes of identical factors may occur in several
  sub-data sets of the paired combined data set. A violation is reported
  together with the violations of the "constraints" of HistFactory
  modifiers, and the error says how to join such distributions.
* External arrays are no longer split into their components: two arrays
  that share components can't both be terms of a likelihood any more.
* Combined data sets may have combined data sets as components; their
  columns become columns of the outer data set, with the label "" in the
  rows of the other components.
* The import of a likelihood flattens its model into one RooSimultaneous
  over a RooSuperCategory, also for a single term with nested combined
  distributions, with "" in the columns that don't apply to a channel.
  Array channels of one component type, each with one data entry, are
  merged into one array with the union of their components, and their
  entries into one; differing observed values of a shared variate are an
  error. The replaced combined distributions are helpers, which the
  export only writes if something else uses them.
* Skipping helpers on export is weakly transitive: an object that only
  skipped helpers use is not written either (e.g. the arrays that were
  merged), except that a skipped array dissolves into its components,
  which are then written on their own. HistFactory modifiers name an
  array that is written.
* The HistFactory checks of root-project#24201 descend into nested combined
  distributions, and a nested combined distribution is not wrapped with
  constraints like other channels that are no products.

Tests: identical array components within a combined distribution give
the likelihood of one array; as two terms of a likelihood they are
rejected. Two HistFactory models written with exportConstraintData are
joined in a nested combined distribution, flattened, and give the
likelihood of the single model of both channels; as two terms, they are
rejected.

Assisted-by: claude-code:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@guitargeek
guitargeek merged commit 2bacb4b into root-project:master Nov 19, 2026
46 of 57 checks passed
@guitargeek
guitargeek deleted the hs3-v03-spec-fixes branch November 19, 2026 16:54
cburgard added a commit to cburgard/root that referenced this pull request Nov 19, 2026
HS3 root-project#161 was revised: the likelihood is the plain product of its terms,
and union composition applies only within a listed distribution (combined
and array distributions). Distributions that share factors, e.g. the
models of a combination with common constraint terms, are joined in a
combined distribution, which may contain combined distributions itself.

* Distinct variates: each term of a likelihood is the union of its parts
  (components of combined distributions, recursively, and of array
  distributions), in which identical parts count once; a variate of two
  terms is shared, also by identical parts. Components of a combined
  distribution whose sub-data set is missing or empty contribute nothing
  and are left out. The axes of identical factors may occur in several
  sub-data sets of the paired combined data set. A violation is reported
  together with the violations of the "constraints" of HistFactory
  modifiers, and the error says how to join such distributions.
* External arrays are no longer split into their components: two arrays
  that share components can't both be terms of a likelihood any more.
* Combined data sets may have combined data sets as components; their
  columns become columns of the outer data set, with the label "" in the
  rows of the other components.
* The import of a likelihood flattens its model into one RooSimultaneous
  over a RooSuperCategory, also for a single term with nested combined
  distributions, with "" in the columns that don't apply to a channel.
  Array channels of one component type, each with one data entry, are
  merged into one array with the union of their components, and their
  entries into one; differing observed values of a shared variate are an
  error. The replaced combined distributions are helpers, which the
  export only writes if something else uses them.
* Skipping helpers on export is weakly transitive: an object that only
  skipped helpers use is not written either (e.g. the arrays that were
  merged), except that a skipped array dissolves into its components,
  which are then written on their own. HistFactory modifiers name an
  array that is written.
* The HistFactory checks of root-project#24201 descend into nested combined
  distributions, and a nested combined distribution is not wrapped with
  constraints like other channels that are no products.

Tests: identical array components within a combined distribution give
the likelihood of one array; as two terms of a likelihood they are
rejected. Two HistFactory models written with exportConstraintData are
joined in a nested combined distribution, flattened, and give the
likelihood of the single model of both channels; as two terms, they are
rejected.

Assisted-by: claude-code:claude-opus-5-5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants