Events class (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: Direct input of event data.
pathlib.Path or str: Path to an event data file. Supported file formats:
- .csv: Pupil Cloud format CSV file.
- .raw / .txt: Native 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.
typestr: Inferred event type based on data columns.

Methods

`apply_homographies`(homographies[, ...])	Compute fixation locations in surface coordinates using provided homographies based on fixation pixel coordinates and append them to the events data.
`copy`()	Create a deep copy of the instance.
`crop`([tmin, tmax, by, inplace])	Extract a subset of events within a specified temporal range.
`filter_by_duration`([dur_min, dur_max, ...])	Filter events by their durations.
`filter_by_name`(names[, col_name, reset_id, ...])	Filter events by matching values in a specified column.
`restrict`(other[, inplace])	Align events to match a stream's temporal range.
`save`(output_path)	Save the data to a CSV file.

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")
>>> saccades = Events("fixations ps1.raw", type="saccades")
>>> events = Events("event.txt")

Create from DataFrame:

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

data: DataFrame#

file: Path | None#

type: str#

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.

property end_ts: ndarray#

End timestamps of events in nanoseconds.

Raises:

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

property durations: ndarray#

Duration of events in milliseconds.

Raises:

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

property id: ndarray#: Event IDs.

property id_name: str | None#

Name of the event ID column based on event type.

Returns:

str or None: The ID column name (e.g., "blink id", "fixation id", "saccade id", "event id") for known event types, or None for custom event types.

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

Extract a subset of events within a specified temporal range.

The by parameter determines how tmin and tmax are interpreted: - "timestamp": Absolute Unix timestamps in nanoseconds (based on event start times) - "sample": Zero-based event indices

Both bounds are inclusive. If either bound is omitted, it defaults to the events’ natural boundary (earliest or latest event).

Parameters:

tminnumbers.Number, optional: Lower bound of the range to extract (inclusive). If None, starts from the first event. Defaults to None.
tmaxnumbers.Number, optional: Upper bound of the range to extract (inclusive). If None, extends to the last event. Defaults to None.
by{“timestamp”, “sample”}, optional: Unit used to interpret tmin and tmax. Defaults to "timestamp".
inplacebool, optional: If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None: A new Events instance with modified data if inplace=False, otherwise None.

Raises:

ValueError: If both tmin and tmax are None, or if no events fall within the specified range.

Examples

Crop fixations to the first 5 seconds:

>>> fixations_5s = fixations.crop(tmin=rec.gaze.first_ts,
...                                tmax=rec.gaze.first_ts + 5e9,
...                                by="timestamp")

Extract the first 100 blinks:

>>> first_100 = blinks.crop(tmin=0, tmax=99, by="sample")

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

Align events to match a stream’s temporal range.

This method filters events to include only those whose start times fall between the first and last timestamps of the reference stream. It is equivalent to calling crop(tmin=other.first_ts, tmax=other.last_ts, by="timestamp").

Useful for limiting event analysis to periods when a particular data stream is available.

Parameters:

otherStream: Reference stream whose temporal boundaries define the cropping range.
inplacebool, optional: If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None: A new Events instance with modified data if inplace=False, otherwise None.

Examples

Analyze only blinks that occurred during recorded gaze data:

>>> blinks_with_gaze = blinks.restrict(gaze)

filter_by_duration(dur_min: Number | None = None, dur_max: Number | None = None, reset_id: bool = False, 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 (inclusive). If None, no minimum duration filter is applied. Defaults to None.
dur_maxnumber, optional: Maximum duration (in milliseconds) of events to keep (inclusive). If None, no maximum duration filter is applied. Defaults to None.
reset_idbool, optional: Whether to reset event IDs after filtering. Defaults to False.
inplacebool, optional: If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None: A new Events instance with modified data if inplace=False, otherwise None.

filter_by_name(names: str | list[str], col_name: str = 'name', reset_id: bool = False, inplace: bool = False) → Events | None#

Filter events by matching values in a specified column. Designed primarily for filtering Recording.events by their names.

This method selects only the events whose value in col_name matches one or more of the provided names. If no events match, a ValueError is raised.

Parameters:

namesstr or list of str: Event name or list of event names to keep. Matching is exact and case-sensitive.
col_namestr, optional: Name of the column in self.data to use for filtering. Must exist in the Events instance’s DataFrame. Defaults to "name".
reset_id: bool = False, optional: Whether to reset event IDs after filtering. Defaults to False.
inplacebool, optional: If True, replace current data. Otherwise returns a new instance. Defaults to False.

Returns:

Events or None: A new Events instance with modified data if inplace=False, otherwise None.

apply_homographies(homographies: Stream, max_gap_ms: Number = 500, overwrite: bool = False, inplace: bool = False) → Events | None#

Compute fixation locations in surface coordinates using provided homographies based on fixation pixel coordinates and append them to the events data.

Since homographies are estimated per video frame and might not be available for every frame, they need to be resampled/interpolated to the timestamps of the fixation data before application.

The events data must contain the required fixation columns: fixation x [px] and fixation y [px]. The output events will contain two new columns: fixation x [surface coord] and fixation y [surface coord].

Parameters:

homographiesStream

Stream indexed by “timestamp [ns]” with columns “homography (0,0)” through “homography (2,2)”, corresponding to the 9 elements of the estimated 3x3 homography matrix for each retained frame.

Returned by pyneon.find_homographies().

max_gap_msint, optional

Maximum allowed distance (in milliseconds) to both adjacent original timestamps (left and right). A requested new timestamp will be ignored if its distance to the immediate left OR right original timestamp is greater than or equal to max_gap_ms (no interpolation will be performed at that timestamp). Defaults to 500.

overwritebool, optional

Only applicable if surface fixation columns already exist. If True, overwrite existing columns. If False, raise an error. Defaults to False.

inplacebool, optional

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

Returns:

Events or None: A new Events instance with modified data if inplace=False, otherwise None.

Events class (blinks, fixations, saccades, events)#

This Page