HistogramAccumulator

gammaloop Class

HistogramAccumulator()

Mutable continuous or discrete histogram accumulator with sample-level statistics.

Notes

The example below deliberately places at most one entry in each bin. If several correlated entries land in one bin, the current helper records their squared weights separately rather than grouping their weights like GammaLoop's native observable pipeline. Do not replay raw event groups through this class until that statistical contract is aligned.

Examples

Merge two pending, statistically independent samples before committing them:

from gammaloop import HistogramAccumulator

left = HistogramAccumulator.continuous("energy", 0.0, 4.0, 4)
right = HistogramAccumulator.continuous("energy", 0.0, 4.0, 4)
left.fill_continuous_sample([(0.5, 2.0)])
right.fill_continuous_sample([(2.5, 3.0)])
left.merge_in_place(right)
left.update_results()

snapshot = left.snapshot()
assert snapshot.sample_count == 2
assert snapshot.bins[0].sum_weights == 2.0
assert snapshot.bins[0].sum_weights_squared == 4.0
assert snapshot.bins[0].sum_weights / snapshot.sample_count == 1.0
assert snapshot.bins[2].sum_weights == 3.0
assert snapshot.bins[2].sum_weights_squared == 9.0
assert right.snapshot().sample_count == 0
assert len(left.rebin(2).snapshot().bins) == 2

Member details

`continuous`

Static method

continuous(title: str, x_min: float, x_max: float, n_bins: int, type_description: str = 'AL', phase: str = 'real', value_transform: str = 'identity', log_x_axis: bool = False, log_y_axis: bool = True) -> HistogramAccumulator

Create an evenly binned continuous histogram accumulator.

Parameters

Name	Type	Default	Description
`title`	`str`	`—`	Human-readable title used by snapshots and exported output.
`x_min`	`float`	`—`	Lower edge of the histogram range.
`x_max`	`float`	`—`	Upper edge of the histogram range.
`n_bins`	`int`	`—`	Number of equal-width in-range bins.
`type_description`	`str`	`'AL'`	HwU `TYPE@` metadata.
`phase`	`str`	`'real'`	Component of each complex event weight to accumulate.
`value_transform`	`str`	`'identity'`	Transformation applied to coordinates before binning.
`log_x_axis`	`bool`	`False`	Request logarithmic horizontal-axis rendering.
`log_y_axis`	`bool`	`True`	Request logarithmic vertical-axis rendering.

`discrete`

Static method

discrete(title: str, min_bin_id: int, max_bin_id: int, ordering: str = 'ascending_bin_id', labels: Optional[Sequence[str]] = None, type_description: str = 'AL', phase: str = 'real', log_y_axis: bool = True) -> HistogramAccumulator

Create a discrete histogram accumulator over an inclusive integer range.

Raises

ValueError: If the range, label count, ordering, or phase is invalid.

Parameters

Name	Type	Default	Description
`title`	`str`	`—`	Human-readable title used by snapshots and exported output.
`min_bin_id`	`int`	`—`	Smallest accepted bin identifier.
`max_bin_id`	`int`	`—`	Largest accepted bin identifier, inclusive.
`ordering`	`str`	`'ascending_bin_id'`	Ordering used when bins are returned or exported.
`labels`	`Optional[Sequence[str]]`	`None`	One label per bin, ordered by ascending bin identifier.
`type_description`	`str`	`'AL'`	HwU `TYPE@` metadata.
`phase`	`str`	`'real'`	Component of each complex event weight to accumulate.
`log_y_axis`	`bool`	`True`	Request logarithmic vertical-axis rendering.

`snapshot`

Method

snapshot() -> HistogramSnapshot

Return an immutable snapshot including committed and pending samples.

`merge_in_place`

Method

merge_in_place(other: HistogramAccumulator) -> None

Move pending samples from another compatible accumulator into this one.

Raises

ValueError: If histogram definitions differ.

Parameters

Name	Type	Default	Description
`other`	`HistogramAccumulator`	`—`	Compatible accumulator whose pending samples are consumed.

`rebin`

Method

rebin(contiguous_bins: int) -> HistogramAccumulator

Return a copy with each run of adjacent continuous bins combined.

Discrete histograms are copied unchanged.

Parameters

Name	Type	Default	Description
`contiguous_bins`	`int`	`—`	Positive number of old bins per new bin; it must divide the bin count.

`rescale`

Method

rescale(factor: float) -> None

Multiply all accumulated weights by a constant in place.

Parameters

Name	Type	Default	Description
`factor`	`float`	`—`	Scale applied to weight sums; squared-weight sums use its square.

`change_bin_ordering`

Method

change_bin_ordering(ordering: str) -> None

Change the display ordering of a discrete histogram.

Raises

ValueError: If this is a continuous histogram or the name is invalid.

Parameters

Name	Type	Default	Description
`ordering`	`str`	`—`	New ordering for snapshots and exported output.

`update_results`

Method

update_results() -> None

Commit pending samples to the accumulator's completed-result counters.

`fill_continuous_sample`

Method

fill_continuous_sample(entries: Sequence[tuple[float, float]]) -> None

Add one independent continuous sample containing coordinate-weight pairs.

Raises

ValueError: If this is not a continuous histogram.

Parameters

Name	Type	Default	Description
`entries`	`Sequence[tuple[float, float]]`	`—`	`(coordinate, projected_weight)` entries for this sample.

`fill_discrete_sample`

Method

fill_discrete_sample(entries: Sequence[tuple[int, float]]) -> None

Add one independent discrete sample containing bin-weight pairs.

Raises

ValueError: If this is not a discrete histogram.

Parameters

Name	Type	Default	Description
`entries`	`Sequence[tuple[int, float]]`	`—`	`(bin_id, projected_weight)` entries for this sample.

View generated signature source: docs/api/python/gammaloop-python.pyi:1015