neuralset.events.etypes.Event

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

Base class for all event types.

Every event has a time span (start, duration) and belongs to a timeline. Concrete subclasses (Meg, Image, Word, Fmri, …) add type-specific fields. Events are collected into a pandas DataFrame for bulk processing; the stop column (start + duration) is added by standardize_events().

When instantiated via from_dict(), extra fields not in the schema are silently grouped under extra rather than raising.

Parameters:

• start (float) – Start time of the event in seconds.

• timeline (str) – Timeline identifier to which this event belongs.

• duration (float, optional) – Duration of the event in seconds (default: 0.0).

• extra (dict, optional) – Dictionary for storing additional arbitrary fields (default: {}).

• admonition: (..) – Design rationale — start/duration: Events use start/duration rather than onset/offset because offset is ambiguous — it can mean “end time” or “time shift from a reference” (e.g. Video.offset, fMRI HRF delays, MEG first_samp). duration is unambiguous and is used directly to compute sample counts, rather than to_ind(stop) - to_ind(start) which can vary with alignment.

• onset/offset (not) – Events use start/duration rather than onset/offset because offset is ambiguous — it can mean “end time” or “time shift from a reference” (e.g. Video.offset, fMRI HRF delays, MEG first_samp). duration is unambiguous and is used directly to compute sample counts, rather than to_ind(stop) - to_ind(start) which can vary with alignment.

classmethod from_dict(row: Any) → E

Create event from dictionary/row/named-tuple while grouping non-specified fields.

Fields not defined in the event class schema are automatically grouped under the extra dict attribute.

Parameters:

row (dict, NamedTuple, or pandas.Series) – Input data containing event fields. Must include a ‘type’ field indicating the event class name.

Returns:

Instance of the appropriate Event subclass based on the ‘type’ field

Return type:

Event

Notes

• NaN values in the input are ignored

• if the input has an Index attribute, it’s stored in _index for debugging

Examples

data = {'type': 'Word', 'start': 1.0, 'timeline': 'exp1', 'text': 'hello'}
event = Event.from_dict(data)  # returns a Word instance

property stop: float

Compute the end time of the event.

Returns:

The stop time calculated as start + duration

Return type:

float

to_dict() → dict[str, Any]

Export the event as a dictionary usable for CSV dump.

The extra dictionary field is flattened into separate fields to simplify queries through pandas DataFrames.

Returns:

Flattened dictionary representation of the event with ‘type’ field included

Return type:

dict

Examples

event = Word(start=1.0, timeline="exp", text="hello")
event_dict = event.to_dict()
df = pd.DataFrame([event_dict])