neuralset.events.etypes.BaseDataEvent

class neuralset.events.etypes.BaseDataEvent(*, start: float, timeline: str, duration: Annotated[float, Ge(ge=0)] = 0.0, extra: dict[str, Any] = {}, filepath: Path | str = '', frequency: float = 0)

Base class for events whose data needs to be read from a file.

This class handles file path validation and provides an abstract interface for reading data from files. Supports both regular file paths and method URIs for dynamic data loading.

Parameters:

• filepath (Path or str) – Path to the data file or a method URI (format: method:<name>?timeline=<timeline>)

• frequency (float, optional) – Sampling frequency in Hz (default: 0, auto-detected when possible)

Raises:

ValueError – If filepath is empty or if method URI is missing the timeline parameter

Notes

• File existence is checked unless the path contains a colon (e.g., method URIs)

• Method URIs allow loading data through registered timeline methods

• Subclasses must implement _read() for actual file reading logic

Examples

# Regular file path
event = Audio(start=0, timeline="t1", filepath="/path/to/audio.wav")

# Method URI
event = Audio(start=0, timeline="t1",
             filepath="method:load_audio?timeline=experiment")

read() → Any

Read and return the data from the file or method URI.

Returns:

The loaded data (type depends on the specific Event subclass)

Return type:

Any

Examples

audio_event = Audio(start=0, timeline="t1", filepath="audio.wav")
audio_tensor = audio_event.read()  # Returns torch.Tensor

study_relative_path() → Path

Returns the filepath if ‘study’ is not in event.extra else returns the part of the filepath after the study directory if it is identified in the path