EventBuilder

class vallenae.processor.EventBuilder(fhcdt, dt1x_max, dtnx_max, channels=None, allow_multiple_hits_per_channel=False)

Group hits into Event data sets using the VisualAE Event Builder algorithm.

Channel functions (Normal / Guard / Combined / Unused) are honoured. A guard hit (or a combined hit when it would be the first-hit channel) while no event is open inhibits event opening for the next fhcdt; a guard or combined hit during an open event is included in that event’s Event.hits (the downstream location processor is responsible for excluding it from location calculation).

The Event Builder is a synchronous state machine. Hits must be fed in time-sorted order. Out-of-order input raises ValueError.

Parameters:

• fhcdt (float) – First Hit Channel Discrimination Time, in seconds. The gap required before a hit qualifies as Start-of-Event (SoE). Every hit on a listed channel resets this gap timer.

• dt1x_max (float) – Maximum time between SoE and last hit in event, in seconds. Defines the overall event window starting at the SoE.

• dtnx_max (float) – Maximum time between consecutive hits in event, in seconds. The hit-to-hit continuity window. Setting dtnx_max == dt1x_max effectively deactivates this criterion.

• channels (Mapping[int, ChannelFunction] | Container[int] | None) –

  Channels to consider. Accepts three forms:

  • None (default): accept all channels; treat every hit as ChannelFunction.NORMAL. Hits on unknown channels are included as normal hits.

  • An iterable of channel numbers (e.g. [1, 2, 3]): only those channels participate, all as ChannelFunction.NORMAL. Hits on other channels are dropped.

  • A mapping of channel number to ChannelFunction: full per-channel control. Channels not present are treated as ChannelFunction.UNUSED and dropped.

• allow_multiple_hits_per_channel (bool) – If False (default), a second hit on a channel already represented in the open event closes the event with EventCloseReason.DUPLICATE_CHANNEL; the duplicate hit is not used for the closing event nor for the next one. If True, subsequent hits on a channel are kept in the event.

Example

>>> from vallenae.processor import EventBuilder
>>> builder = EventBuilder(fhcdt=2e-3, dt1x_max=2e-3, dtnx_max=2e-3)
>>> events = list(builder.process_all(pridb.iread_hits()))

__init__(fhcdt, dt1x_max, dtnx_max, channels=None, allow_multiple_hits_per_channel=False)

Methods

__init__(fhcdt, dt1x_max, dtnx_max[, ...])
flush()	Emit the in-flight event (if any) and reset state.
process(hit)	Feed a single hit into the state machine.
process_all(hits)	Feed an iterable of hits and yield events as they close.

Attributes

allow_multiple_hits_per_channel
channels
fhcdt
dt1x_max
dtnx_max

process(hit)

Feed a single hit into the state machine.

Returns events that became ready as a direct consequence of this hit (0 or 1 events). Use flush at the end of the stream to drain any still-open event.

Return type:

list[Event]

process_all(hits)

Feed an iterable of hits and yield events as they close.

Equivalent to calling process on each hit followed by flush at the end. The end-of-stream flush is automatic.

Return type:

Iterator[Event]

flush()

Emit the in-flight event (if any) and reset state.

Returns the closed event with EventCloseReason.END_OF_STREAM, or an empty list if no event was open. After calling, the builder is ready for a fresh stream. Idempotent — a second call without intervening input returns [].

Return type:

list[Event]