Events classes (blinks, fixations, saccades, events)

class pyneon.Events(source: DataFrame | Path | str, type: str | None = None)

Bases: BaseTabular

Container for discrete event data (e.g., blinks, fixations, saccades, or message events).

Parameters:

sourcepandas.DataFrame or pathlib.Path or str

Source of the event data. Can be either:

• pandas.DataFrame: Must contain appropriate event columns.

• pathlib.Path or str: Path to an event data file. Supported file formats:

• .csv: Pupil Cloud format file.

• .raw / .txt: Native Pupil Labs format (requires corresponding .time and .dtype files in the same directory).

Note: Native format columns are automatically renamed to Pupil Cloud format for consistency. For example, mean_gaze_x -> fixation x [px].

type{“fixations”, “saccades”}, optional

Required only when loading from native fixations ps1.raw file, to explicitly specify whether to interpret the data as fixation or saccade events. Ignored for other formats.

Attributes:

filepathlib.Path or None

Path to the source file(s). None if initialized from a DataFrame.

datapandas.DataFrame

Event data with standardized column names.

type{“blinks”, “fixations”, “saccades”, “events”, “custom”}

Inferred event type based on data columns.

id_namestr or None

Column name holding event IDs (e.g., blink id, fixation id, saccade id). None for events and custom types.

Methods

copy()	Create a deep copy of the instance.
crop([tmin, tmax, by, inplace])	Crop data to a specific time range based on timestamps or row numbers.
filter_by_duration([dur_min, dur_max, ...])	Filter events by their durations.
restrict(other[, inplace])	Temporally crop the events to the range of timestamps a stream.

Examples

Load from Pupil Cloud CSV:

>>> blinks = Events("blinks.csv")

Load from native format:

>>> blinks = Events("blinks ps1.raw")
>>> fixations = Events("fixations ps1.raw", type="fixations")
>>> events = Events("event.txt")

Create from DataFrame:

>>> df = pd.DataFrame({"start timestamp [ns]": [...], "end timestamp [ns]": [...]})
>>> saccades = Events(df)

property columns: Index

Column names of the stream data.

copy()

Create a deep copy of the instance.

crop(tmin: Number | None = None, tmax: Number | None = None, by: Literal['timestamp', 'row'] = 'timestamp', inplace: bool = False) → Events | None

Crop data to a specific time range based on timestamps or row numbers.

Parameters:

tminnumber, optional

Start timestamp/row to crop the data to. If None, the minimum timestamp/row in the data is used. Defaults to None.

tmaxnumber, optional

End timestamp/row to crop the data to. If None, the maximum timestamp/row in the data is used. Defaults to None.

by“timestamp” or “row”, optional

Whether tmin and tmax are UTC timestamps in nanoseconds or row numbers of the stream data. Defaults to “timestamp”.

inplacebool, optional

If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None

Cropped events if inplace=False, otherwise None.

property dtypes: Series

Data types of the columns in the stream data.

property durations: ndarray

Duration of events in milliseconds.

Raises:

ValueError

If no duration [ms] column is found in the instance.

property end_ts: ndarray

End timestamps of events in nanoseconds.

Raises:

ValueError

If no end timestamp [ns] column is found in the instance.

filter_by_duration(dur_min: Number | None = None, dur_max: Number | None = None, reset_id: bool = True, inplace: bool = False) → Events | None

Filter events by their durations. Useful for removing very short or long events.

Parameters:

dur_minnumber, optional

Minimum duration (in milliseconds) of events to keep. If None, no minimum duration filter is applied. Defaults to None.

dur_maxnumber, optional

Maximum duration (in milliseconds) of events to keep. If None, no maximum duration filter is applied. Defaults to None.

reset_idbool, optional

Whether to reset event IDs after filtering. Also resets the DataFrame index. Defaults to True.

inplacebool, optional

If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None

Filtered events if inplace=False, otherwise None.

property id: ndarray

Event ID.

Raises:

ValueError

If no ID column (e.g., <xxx> id) is found in the instance.

restrict(other: Stream, inplace: bool = False) → Events | None

Temporally crop the events to the range of timestamps a stream. Equivalent to crop(other.first_ts, other.last_ts).

Parameters:

otherStream

Stream to restrict to.

inplacebool, optional

If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None

Restricted events if inplace=False, otherwise None.

property shape: tuple[int, int]

property start_ts: ndarray

Start timestamps of events in nanoseconds.

Raises:

ValueError

If no start timestamp [ns] or timestamp [ns] column is found in the instance.