EventDetector

DAQ-based Event Detection Module

This module provides classes for detecting events in data acquisition (DAQ) systems. It includes:

• A Event dataclass to represent detected events
• Base EventDetector class for event detection logic
• Subclasses EventDetectorLevelLow and EventDetectorLevelHigh for specific event detection criteria
• An EventController class to manage multiple event detectors and process events

Classes:

Name	Description
Event	A dataclass representing a detected event with associated metadata.
EventDetector	Base class for implementing various event detection algorithms. EventDetectorLevelLow: Detects events where data drops below a specified limit. EventDetectorLevelHigh: Detects events where data exceeds a specified limit.
EventController	Manages multiple event detectors and processes events over time.

Event dataclass

Represents a detected event with associated metadata.

Attributes:

Name	Type	Description
start_ts	float	Timestamp (in seconds) when the event started.
stop_ts	float	Timestamp (in seconds) when the event stopped. None if ongoing.
start_sidx	int	Start sample index of the event.
stop_sidx	int	Stop sample index of the event. None if ongoing.
extrem_value	float	Extreme value associated with the event (minimum for Level Low, maximum for Level High).
channel	str	Name of the channel from which the event was detected.
type	str	Type of event ('LEVEL_LOW' or 'LEVEL_HIGH').
id	UUID	Unique identifier for the event.

EventController

Bases: object

Manages multiple event detectors and processes detected events over time.

Attributes:

Name	Type	Description
PROCESSING_DELAY_SECONDS		Time (in seconds) after the latest sample to process events.
_time_channel		The channel providing timestamp data.
_sample_rate		Sampling rate of the system (samples per second).
_event_detectors	List[EventDetector]	List of registered event detectors.
_last_processed_sidx		The last sample index processed.
_unfinished_events	Dict[UUID:Event]	Dictionary mapping event IDs to unfinished Event objects.

__init__(time_channel, sample_rate)

Initializes the EventController.

Parameters:

Name	Type	Description	Default
time_channel	AcqBuffer	The channel providing timestamp data.	required
sample_rate	float	Sampling rate of the system (samples per second).	required

EventDetector

Bases: object

Base class for implementing event detection algorithms.

Attributes:

Name	Type	Description
limit		The threshold value that defines the event boundary.
threshold		The buffer around the limit used to detect event completion.
observed_channel		The channel being monitored for events.
last_channel_data		The most recent data from the observed channel.
last_channel_sidx		The most recent sample index from the observed channel.
_unfinished_event		Metadata for an event that is still ongoing.
_type		Type of event detection algorithm ('LEVEL_LOW' or 'LEVEL_HIGH').

__init__(limit, threshold, observed_channel)

Initializes the EventDetector with specified parameters.

Parameters:

Name	Type	Description	Default
limit	float	The threshold value that defines the event boundary.	required
threshold	float	The buffer around the limit used to detect event completion.	required
observed_channel	DataChannelBuffer	The channel being monitored for events.	required

EventDetectorLevelHigh

Bases: EventDetector

Detects events where data exceeds a specified limit (LEVEL_HIGH).

Inherits from EventDetector and overrides the _type to 'LEVEL_HIGH'.

__init__(limit, threshold, observed_channel)

Initializes the Level High event detector.

Parameters:

Name	Type	Description	Default
limit	float	The upper threshold value.	required
threshold	float	The buffer above the limit used to detect event completion.	required
observed_channel	DataChannelBuffer	The channel being monitored for events.	required

EventDetectorLevelLow

Bases: EventDetector

Detects events where data drops below a specified limit (LEVEL_LOW).

Inherits from EventDetector and overrides the _type to 'LEVEL_LOW'.

__init__(limit, threshold, observed_channel)

Initializes the Level Low event detector.

Parameters:

Name	Type	Description	Default
limit	float	The lower threshold value.	required
threshold	float	The buffer below the limit used to detect event completion.	required
observed_channel	DataChannelBuffer	The channel being monitored for events.	required