Data stream classes (gaze, eye states, IMU)#

class pyneon.Stream(data: DataFrame | Path, sampling_freq_nominal: int | None = None)#

Bases: BaseTabular

Base for a continuous data stream (gaze, eye states, IMU). Indexed by timestamp [ns].

Parameters:

data (pandas.DataFrame or pathlib.Path) – DataFrame or path to the CSV file containing the stream data. The data must be indexed by timestamp [ns].

file#

Path to the CSV file containing the stream data.

Type:

pathlib.Path

data#

DataFrame containing the stream data.

Type:

pandas.DataFrame

sampling_freq_nominal#

Nominal sampling frequency of the stream as specified by Pupil Labs (https://pupil-labs.com/products/neon/specs).

Type:

int or None

property timestamps: ndarray#

Timestamps of the stream in nanoseconds.

property ts: ndarray#

Alias for timestamps.

property first_ts: int#

First timestamp of the stream.

property last_ts: int#

Last timestamp of the stream.

property ts_diff: ndarray#

Difference between consecutive timestamps.

property times: ndarray#

Timestamps converted to seconds relative to stream start.

property duration: float#

Duration of the stream in seconds.

property sampling_freq_effective: float#

Effective sampling frequency of the stream.

property is_uniformly_sampled: bool#

Whether the stream is uniformly sampled.

time_to_ts(time: Number | ndarray) → ndarray#

Convert relative time(s) in seconds to closest timestamp(s) in nanoseconds.

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

Crop data to a specific time range based on timestamps, relative times since start, or row numbers.

Parameters:

  • tmin (numbers.Number, optional) – Start timestamp/time/row to crop the data to. If None, the minimum timestamp/time/row in the data is used. Defaults to None.

  • tmax (numbers.Number, optional) – End timestamp/time/row to crop the data to. If None, the maximum timestamp/time/row in the data is used. Defaults to None.

  • by ("timestamp" or "time" or "row", optional) – Whether tmin and tmax are UTC timestamps in nanoseconds OR relative times in seconds OR row numbers of the stream data. Defaults to “timestamp”.

  • inplace (bool, optional) – Whether to replace the data in the object with the cropped data. Defaults to False.

Returns:

Cropped stream if inplace=False, otherwise None.

Return type:

Stream or None

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

Temporally restrict the stream to the timestamps of another stream. Equivalent to crop(other.first_ts, other.last_ts).

Parameters:

  • other (Stream) – The other stream whose timestamps are used to restrict the data.

  • inplace (bool, optional) – Whether to replace the data in the object with the restricted data.

Returns:

Restricted stream if inplace=False, otherwise None.

Return type:

Stream or None

interpolate(new_ts: ndarray | None = None, float_kind: str = 'linear', other_kind: str = 'nearest', inplace: bool = False) → Stream | None#

Interpolate the stream to a new set of timestamps.

Parameters:

  • new_ts (numpy.ndarray, optional) – An array of new timestamps (in nanoseconds) at which to evaluate the interpolant. If None (default), new timestamps are generated according to the nominal sampling frequency of the stream as specified by Pupil Labs: https://pupil-labs.com/products/neon/specs.

  • float_kind (str, optional) – Kind of interpolation applied on columns of float type, For details see scipy.interpolate.interp1d. Defaults to "linear".

  • other_kind (str, optional) – Kind of interpolation applied on columns of other types, For details see scipy.interpolate.interp1d. Defaults to "nearest".

  • inplace (bool, optional) – Whether to replace the data in the object with the interpolated data. Defaults to False.

Returns:

Interpolated stream if inplace=False, otherwise None.

Return type:

Stream or None

interpolate_events(events: Events, buffer: Number | tuple[Number, Number] = 0.05, float_kind: str = 'linear', other_kind: str = 'nearest', inplace: bool = False) → Stream | None#

Interpolate data in the duration of events in the stream data. Similar to mne.preprocessing.eyetracking.interpolate_blinks().

Parameters:

  • events (Events) – Events object containing the events to interpolate. The events must have start timestamp [ns] and end timestamp [ns] columns.

  • buffer (numbers.Number or , optional) – The time before and after an event (in seconds) to consider invalid. If a single number is provided, the same buffer is applied to both before and after the event. Defaults to 0.05.

  • float_kind (str, optional) – Kind of interpolation applied on columns of float type, For details see scipy.interpolate.interp1d. Defaults to "linear".

  • other_kind (str, optional) – Kind of interpolation applied on columns of other types, For details see scipy.interpolate.interp1d. Defaults to "nearest".

  • inplace (bool, optional) – Whether to replace the data in the object with the interpolated data. Defaults to False.

Returns:

Interpolated stream if inplace=False, otherwise None.

Return type:

Stream or None

window_average(new_ts: ndarray, window_size: int | None = None, inplace: bool = False) → Stream | None#

Take the average over a time window to obtain smoothed data at new timestamps.

Parameters:

  • new_ts (numpy.ndarray) –

    An array of new timestamps (in nanoseconds) at which to evaluate the averaged signal. Must be coarser than the source sampling, i.e.:

    >>> np.median(np.diff(new_ts)) > np.median(np.diff(data.index))

  • window_size (int, optional) – The size of the time window (in nanoseconds) over which to compute the average around each new timestamp. If None (default), the window size is set to the median interval between the new timestamps, i.e., np.median(np.diff(new_ts)). The window size must be larger than the median interval between the original data timestamps, i.e., window_size > np.median(np.diff(data.index)).

  • inplace (bool, optional) – Whether to replace the data in the object with the window averaged data. Defaults to False.

Returns:

Stream with window average applied on data if inplace=False, otherwise None.

Return type:

Stream or None