libtcspc.Histogram¶

final class libtcspc.Histogram(num_bins, max_per_bin, reset_event_type=None, *, buffer_provider=None, overflow='error', emit_concluding=False, numeric_traits=None)[source]¶

Bases: Node

Processor that accumulates a histogram from bin increment events.

Each BinIncrementEvent increments the corresponding bin; a HistogramEvent carrying a view of the current histogram is emitted on each increment. A round of accumulation ends on a reset_event_type; if concluding events are enabled, a ConcludingHistogramEvent is emitted on each reset.

Parameters:

num_bins (int or Param[int]) – Number of bins in the histogram.
max_per_bin (int or Param[int]) – Maximum count per bin before the overflow policy applies.
reset_event_type (EventType or None) – Event type that resets (starts a new round). None (the default) means no reset event.
buffer_provider (BucketSource or Param[PyBucketSource] or None) – Source of buckets holding the histogram. If None, a default RecyclingBucketSource is used.
overflow (str) – Overflow behavior: "error" (default), "stop", "saturate", or "reset".
emit_concluding (bool) – If True, emit a ConcludingHistogramEvent on each reset. Default False.
numeric_traits (NumericTraits or None) – Numeric traits specifying bin_index_type and bin_type. Defaults to NumericTraits().

Notes

Events handled:

BinIncrementEvent: increment the corresponding bin and emit a HistogramEvent carrying a view of the current histogram.
reset_event_type (if given): end the current round and start a new one; if emit_concluding is set, a ConcludingHistogramEvent is emitted first.
All other event types: pass through unchanged.
On bin overflow: handled per overflow (when "saturate", a WarningEvent is emitted).
End of input: pass through; the current histogram is not emitted as a concluding event.

The histogram-carrying output events can be sent directly to a Python sink, where they are delivered as EventInstance values whose data_bucket attribute reads as a read-only NumPy array. Alternatively, insert ExtractBucket to obtain just the histogram as a bare NumPy array.