libtcspc.ScanHistograms¶

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

Bases: Node

Processor that accumulates an array of histograms over a scan.

Each BinIncrementClusterEvent updates the next element of the histogram array; a HistogramArrayProgressEvent is emitted per cluster, and a HistogramArrayEvent upon completion of each scan. A round ends on a reset_event_type; if concluding events are enabled, a ConcludingHistogramArrayEvent is emitted on each reset.

Parameters:

num_elements (int or Param[int]) – Number of histograms (elements) in the array.
num_bins (int or Param[int]) – Number of bins per element.
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 array. If None, a default RecyclingBucketSource is used.
overflow (str) – Overflow behavior: "error" (default), "stop", "saturate", or "reset".
emit_concluding (bool) – If True, emit a ConcludingHistogramArrayEvent on each reset. Default False.
reset_after_scan (bool) – If True, reset after each completed scan. Default False.
clear_every_scan (bool) – If True, clear the array at the start of each scan. Default False.
numeric_traits (NumericTraits or None) – Numeric traits specifying bin_index_type and bin_type. Defaults to NumericTraits().

Notes

Events handled:

BinIncrementClusterEvent: update the next element of the histogram array and emit a HistogramArrayProgressEvent; emit a HistogramArrayEvent when a scan completes.
reset_event_type (if given): end the current round and start a new one; if emit_concluding is set, a ConcludingHistogramArrayEvent 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; an incomplete scan 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 array as a bare NumPy array.