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

class pyneon.stream.NeonStream(file: Path)#

Bases: NeonTabular

Base for Neon continuous data (gaze, eye states, IMU). It’s indexed by timestamp [ns].

Parameters:: file (pathlib.Path) – Path to the CSV file containing the stream data.

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) → NeonStream | None#

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

Parameters:

tmin (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 (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:

NeonStream or None

restrict(other: NeonStream, inplace: bool = False)#

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

Parameters:

other (NeonStream) – 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:

NeonStream or None

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

Interpolate the stream to a new set of timestamps.

Parameters:

new_ts (np.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, by default "linear". For details see scipy.interpolate.interp1d.
other_kind (str, optional) – Kind of interpolation applied on columns of other types, by default "nearest". For details see scipy.interpolate.interp1d.
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:

NeonStream or None

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

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

Parameters:

new_ts (np.ndarray) – An array of new timestamps (in nanoseconds) at which to compute the windowed averages. The median interval between these new timestamps must be larger than the median interval between the original data timestamps, i.e., np.median(np.diff(new_ts)) > np.median(np.diff(data.index)). In other words, only downsampling is supported.
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: