[RF][HS3] Support the HS3 histfactory function (deferred until HS3 #143 and the bin width discussion are settled) #23985

Feature description

HS3 #129 (merged) adds a histfactory function to the standard, next to the existing histfactory_dist:

• It has the same components as histfactory_dist (axes, default_interpolation, samples with data and modifiers). Only the type differs.
• It evaluates the HistFactory prediction, i.e. the expected bin yields $\lambda_i(\theta)$. histfactory_dist is now defined as $\prod_i \mathrm{Pois}(n_i \mid \lambda_i(\theta))$ on top of that prediction.
• The constraint terms belong to the prediction: a likelihood that contains a histfactory_dist, or a distribution that depends on a histfactory function, includes the constraint terms of all its modifiers, in addition to aux_likelihood.

RooFit currently supports only histfactory_dist. A document containing a histfactory function fails to import with "no handling for type 'histfactory' implemented". For histfactory_dist, RooFit already conforms to #129: it puts the modifier constraint terms into the RooProdPdf of the channel.

Supporting the function would roughly require:

• an importer for histfactory, sharing the sample/modifier code of the histfactory_dist importer, that produces a RooRealSumFunc of the samples;
• an exporter that recognizes HistFactory-structured RooRealSumFuncs and writes them as histfactory;
• adding the constraint terms of every histfactory function that a likelihood depends on when building the ModelConfig, and not repeating them in aux_distributions on export;
• possibly an opt-in setting to export existing RooProdPdf/RooRealSumPdf HistFactory channels as a histfactory function plus a wrapper distribution.

This is deferred until two open questions are settled: what the function returns at a point x, discussed in HS3 #143, and the bin width discussion in #23301.

The spec defines the function per bin ($\lambda_i(\theta)$), but doesn't say what it returns when evaluated at a point $x$. Two readings fit the current text: the yield of the bin containing $x$ ($\lambda_i$), or the yield per unit bin volume ($\lambda_i/\lvert B_i\rvert$). They differ by exactly the bin volume. This matters as soon as the function is used in a likelihood. The standard's distributions that could consume it (bincounts_density_dist, rate_density_dist) integrate their input over $x$, $\nu_i = \int_{B_i} f(x)\,\mathrm{d}x$. So:

• If the function returns bin yields, using it in a likelihood requires an explicit bin-volume factor $1/\lvert B_i\rvert$ in the serialized model. How bin volumes are represented is open on both sides:
  • in HS3, binvolume/inverse_binvolume are proposed in #121, which is blocked by [RF] Introduce a first-class RooBinIndex for reusable bin-index computation #23301;
  • in RooFit, the representation of RooBinWidthFunction is under discussion in [RF] Make RooBinWidthFunction depend directly on observables #23298 and [RF] Introduce a first-class RooBinIndex for reusable bin-index computation #23301.
• If the function returns yields per unit bin volume, bincounts_density_dist with the function as density is equivalent to histfactory_dist, and no bin-volume object appears in the serialized model. Bin widths then only matter inside RooFit's importer and exporter.

histfactory_dist never ran into this: it is evaluated at the count vector, never at a point x.

HS3 #143 proposes to make this explicit with a field on the function, yield_per: "bin" | "volume", and asks the community for input. The outcome determines the RooFit implementation:

• the bin-width division inside the samples, which today is part of the RooRealSumPdf built for histfactory_dist;
• the wrapper distribution used by the opt-in export setting;
• whether RooFit needs a serialized bin-volume function at all.

Alternatives considered

• Writing $1/\lvert B_i\rvert$ as a standard generic function (piecewise constant via ifelse), plus a marker in misc.ROOT_internal so that RooFit maps it back to RooBinWidthFunction.
• Writing $1/\lvert B_i\rvert$ as a second, modifier-free histfactory function whose contents are the inverse bin volumes.
• Fixing one reading without a field: either the yield per unit bin volume, so that bincounts_density_dist can consume the function directly; or the bin yield, together with a new HS3 distribution that consumes per-bin expected counts directly (a bin-space counterpart of bincounts_density_dist).

The first two are conformant workarounds that serialize the bin-volume conversion explicitly. The last requires a spec change and is one of the options under discussion in HS3 #143. None of them seemed worth committing to before HS3 #143 and the bin width discussion have concluded.

Additional context

• HS3: #143 (what the histfactory function returns at a point; proposal yield_per), #129 (adds the histfactory function), #141 (clarifies yields vs. intensity), #121 (bin-volume primitives), #124 (modifier constraints)
• ROOT: [RF] Make RooBinWidthFunction depend directly on observables #23298 (RooBinWidthFunction depending on observables), [RF] Introduce a first-class RooBinIndex for reusable bin-index computation #23301 (RooBinIndex), [RF][HS3] HS3 v0.3 conformance: follow HS3 #135 and #124 #23840 (HS3 conformance fixes, which explicitly leave out the histfactory function)