graphed_histogram.boost

The deferred boost_histogram.Histogram — fills RECORD; runners aggregate.

Each .fill(...) records one step the runner performs later, recorded the same way a correction lookup or an ONNX model evaluation is; its evaluator returns a FILLED boost histogram for one chunk. The step’s identity is the content hash of the canonical axes/storage spec plus its inputs, so identical fills collapse to one. Evaluation is graphed’s own machinery — there is no compute() here: plan() exports a plan (one fill task per partition over a graphed.write.PartitionedSource; the whole-dataset loader is never invoked) whose combine is add_histograms(), and ANY runner’s run(plan).value IS the aggregated histogram; session.materialize(fill_node) evaluates a fill on the spot. On fixed axes, Int64 counts are exact under any combine tree, and float sums’ bits are fixed by the runner family and the partition count. Growth axes combine to the reference stated in the docs’ “Growth axes” section.

Functions

graphed_histogram.boost.add_histograms(a, b)

The combine: native +, after widening each pair of growing Regular axes on one grid (equal bin width, edges a whole number of bins apart, equal metadata) to their bin-aligned union. Every pair native + refuses otherwise stays refused.

Returns a new boost_histogram.Histogram carrying a’s metadata; neither operand changes. Growth categories come out as a’s, then b’s new ones, so a must hold the lower-keyed partitions (the docs’ “Growth axes” section).

Parameters:

• a (boost_histogram.Histogram)

• b (boost_histogram.Histogram)

Return type:

boost_histogram.Histogram

graphed_histogram.boost.factory(*arrays, histref, weight=None, sample=None)

A deferred histogram from a reference histogram’s axes/storage plus one staged fill (the dask-histogram factory shape).

Parameters:

• arrays (Array)

• histref (boost_histogram.Histogram)

• weight (Array | None)

• sample (Array | None)

Return type:

Histogram

graphed_histogram.boost.fill_nodes_by_label(hist)

Per-label fill nodes: {label: node} in fold order, nominal first.

Histogram.fill_nodes() is a flat list with no label attribution, and one fill call’s siblings are the only place the correspondence exists — so a histogram carrying several fill calls has no single answer and says so rather than hiding one of them.

Parameters:

hist (Histogram)

Return type:

dict[str, Array]

graphed_histogram.boost.histogram(x, *, bins=10, range=None, weights=None)

numpy-like 1-D entry point: a deferred Regular-axis histogram (Int64-exact when unweighted).

Parameters:

• x (Array)

• bins (int)

• range (Sequence[float] | None)

• weights (Array | None)

Return type:

Histogram

graphed_histogram.boost.histogram2d(x, y, *, bins=10, range=None, weights=None)

Parameters:

• x (Array)

• y (Array)

• bins (int | Sequence[int])

• range (Sequence[Sequence[float]] | None)

• weights (Array | None)

Return type:

Histogram

graphed_histogram.boost.histogramdd(sample, *, bins=10, range=None, weights=None)

Parameters:

• sample (Sequence[Array])

• bins (int | Sequence[int])

• range (Sequence[Sequence[float]] | None)

• weights (Array | None)

Return type:

Histogram

graphed_histogram.boost.label_listing(histograms)

The plan-level {output: [labels]} listing: each output → its variation labels in FOLD order (nominal first, then vary-tag insertion order); an unvaried output → ["nominal"].

MODE-INDEPENDENT: an axis-mode output lists the SAME labels as its sibling twin, because both modes populate _label_maps with the same fold-ordered set. The labels come from the fill’s DECLARED label set the builder holds (_output_labels), NOT from the (output, None) slot key — which carries no label, so a key-reading listing would answer [None]/[] for an axis-mode output.

Parameters:

histograms (Mapping[str, Histogram])

Return type:

dict[str, list[str]]

graphed_histogram.boost.plan(histograms, *, steps_per_file=1, backend=None, partitions=None)

One plan that aggregates SEVERAL deferred histograms sharing a source in a SINGLE pass.

All their fills compile into ONE IR, so a sub-graph feeding multiple histograms (e.g. a trijet selection feeding both a pT and a b-tag histogram) is read and evaluated ONCE — not once per histogram as separate Histogram.plan() calls would. The dask-histogram compute(dict_of_hists) analogue; run(plan).value is a flat slot-keyed mapping — a bare output name for an output no variation reaches, (output, label) for a varied one — which graphed_histogram.unpack() turns into the user-facing per-output shape. Column projection covers the union of all histograms’ fills.

Parameters:

• histograms (Mapping[str, Histogram] | Sequence[Histogram])

• steps_per_file (int)

• backend (Callable[[], Any] | str | None)

• partitions (Sequence[Partition] | None)

Return type:

Plan[dict[str | tuple[str, str | None], boost_histogram.Histogram]]

graphed_histogram.boost.unpack(value)

The result unpacker: the executed plan’s flat slot-keyed value as the per-output shape.

The shape is decided by the KEY FORM, which is total and per output — a bare output name is that output’s bare histogram, (output, label) keys gather into {label: hist}, and (output, None) is the axis-mode histogram, which carries its variations on an axis rather than in the mapping. A varied sibling output always carries at least two labels, so no output’s shape is ambiguous, in a mixed plan exactly as in a single-mode one. graphed.labels/universe/nominal read both shapes uniformly.

Parameters:

value (Mapping[SlotKey, bh.Histogram])

Return type:

dict[str, bh.Histogram | dict[str, bh.Histogram]]

Classes

class graphed_histogram.boost.FillEvaluator(spec, n_axes, has_weight, has_sample, n_weights=1, variation=None)

Bases: object

The External evaluator: fill ONE chunk into a fresh zero histogram (picklable).

Sibling mode (variation is None, the default — old pickles restore into it) fills once. In variation-axis mode variation is the ordered tuple of labels this node writes: the value and sample= columns are FIXED for the node and only the weight block varies across the loop, so the evaluator fills each label’s own weight block against that label’s scalar category value on the pre-declared "variation" axis. That is how every label resolving to the SAME value and sample= members collapses into ONE node — the weight-only labels onto nominal’s, a joint label onto the shifted member its point names.

Parameters:

• spec (str)

• n_axes (int)

• has_weight (bool)

• has_sample (bool)

• n_weights (int)

• variation (tuple[str, ...] | None)

class graphed_histogram.boost.Histogram(*args, **kwargs)

Bases: Histogram

A boost_histogram.Histogram whose fills are DEFERRED graphed computations.

fill records and returns self (fills accumulate). Evaluation is graphed’s, not a method of this class: plan() exports a plan for any runner — the runner’s result IS the aggregated histogram — and session.materialize(fill_node) evaluates one fill on the spot (an in-memory source’s whole dataset in one chunk). The eager boost API (axes, storage, views of the EMPTY state) remains available.

Parameters:

• axes (Any)

• storage (Any)

• metadata (Any)

evaluators()

content hash -> evaluator, for resolving this histogram’s External nodes.

Return type:

dict[str, Callable[[…], object]]

fill(*args, weight=None, sample=None, threads=None, unweighted=False, variation_axis=False)

Record this fill and return self.

The fill is the first place independent axis, weight and sample= handles meet, so it unifies their event contexts itself, re-indexes every ancestor-context input into the winning context’s row space, and auto-applies that context’s ambient weight — the event weight you registered once and then forgot about. unweighted=True opts out of BOTH weight sources and, applying no factor, carries none of their labels.

Default lowering is one SIBLING node per label. variation_axis=True opts into AXIS mode: labels group by the value/sample= member they RESOLVE to, and each group folds into ONE evaluator-loop node over a frontend-declared "variation" StrCategory axis. The group resolving to nominal’s member is the weight-only collapse; a label whose point names a shifted axis coordinate its own name does not leaves that group and joins the node of the member it names (still 1 + |S| nodes). The MODE is a property of the histogram — fixed by the first fill and remembered; a later fill in the OTHER mode is a hard error.

Parameters:

• args (Any)

• weight (Any | Sequence[Any] | None)

• sample (Any | None)

• threads (int | None)

• unweighted (bool)

• variation_axis (bool)

Return type:

Histogram

plan(*, steps_per_file=1, backend=None, partitions=None)

A plan: one fill task per partition, combined by add_histograms(). Run it later with any runner.

Thin specialization of graphed.aggregate_plan() — this histogram’s fills are the outputs, summed per partition and added across them; backend is each worker’s evaluation backend (factory/class or "module:attr" import ref for behavior-carrying backends, which do not pickle); partitions lets the caller shape partitioning itself. For several histograms that share a sub-graph, plan them together with plan() so the shared work runs ONCE.

Parameters:

• steps_per_file (int)

• backend (Callable[[], Any] | str | None)

• partitions (Sequence[Partition] | None)

Return type:

Plan[boost_histogram.Histogram]

class graphed_histogram.boost.HistogramForm(spec_hash)

Bases: object

The recorded form of a fill node: a histogram, identified by its spec hash.

Parameters:

spec_hash (str)