Epochs class#

This page documents the pyneon.Epochs class, which segments pyneon.Stream or pyneon.Events data into epochs based on specified criteria. It also documents the helper functions pyneon.events_to_epochs_info() and pyneon.construct_epochs_info() for creating the epochs information DataFrame.

class pyneon.Epochs(source: Stream | Events, epochs_info: DataFrame)#

Class to create and analyze epochs in the data streams.

Parameters:

sourceStream or Events

Data to create epochs from. Can be either a Stream or a Events instance.

epochs_infopandas.DataFrame, shape (n_epochs, 4)

DataFrame containing epoch information with the following columns (times are UNIX timestamps in nanoseconds):

Column	Description
t_ref	Reference time of the epoch.
t_before	Time before the reference time to start the epoch.
t_after	Time after the reference time to end the epoch.
description	Description or label associated with the epoch.

Must not have empty values.

See events_to_epochs_info() or construct_epochs_info() for helper functions to create this DataFrame.

Attributes:

epochs_infopandas.DataFrame, shape (n_epochs, 4)

DataFrame containing epoch information with the following columns (times are UNIX timestamps in nanoseconds):

Column	Description
t_ref	Reference time of the epoch.
t_before	Time before the reference time to start the epoch.
t_after	Time after the reference time to end the epoch.
description	Description or label associated with the epoch.

Column	Description
t_start	Start time of the epoch (`t_ref - t_before`).
t_end	End time of the epoch (`t_ref + t_after`).

sourceStream or Events

The source data used to create epochs.

Methods

`annotate_source`()	Create index-wise annotations of epoch indices for the source data.
`apply_baseline`([baseline, method, ...])	Apply baseline correction to epochs.
`plot`([column_name, cmap_name, ax, show])	Plot data from a specified column from epochs on a matplotlib axis.
`to_numpy`([column_names, sampling_rate, ...])	Converts epochs into a 3D arrays with dimensions (n_epochs, n_channels, n_times).

Notes

An epoch spans the temporal range of t_ref - t_before to t_ref + t_after as shown below:

                t_ref[0]                            t_ref[1]
    <--t_before[0]--|--t_after[0]-->      <-t_before[1]-|-t_after[1]->
├--------------------------------------------------------------------------------┤

property epochs_dict: dict[int, Stream | Events | None]#

Dictionary of epochs indexed by epoch index. Each epoch contains data cropped from the source between t_start and t_end. If no data is found for an epoch, its value is None.

Returns:

dict of int to Stream or Events or None: Dictionary mapping epoch indices to their corresponding data.

property empty_epochs: list[int]#

Indices of epochs that contain no data.

Returns:

list of int: List of epoch indices for which no data was found.

annotate_source() → DataFrame#

Create index-wise annotations of epoch indices for the source data.

Returns:

pandas.DataFrame: DataFrame with index matching the source data indices and a column “epoch_indices” containing lists of epoch indices that include each data point.

property t_ref: ndarray#

Reference time for each epoch in Unix nanoseconds.

Returns:

numpy.ndarray: Array of reference timestamps in nanoseconds.

property t_before: ndarray#

Time before the reference time for each epoch in nanoseconds.

Returns:

numpy.ndarray: Array of time durations before reference in nanoseconds.

property t_after: ndarray#

Time after the reference time for each epoch in nanoseconds.

Returns:

numpy.ndarray: Array of time durations after reference in nanoseconds.

property description: ndarray#

Description or label for each epoch.

Returns:

numpy.ndarray: Array of description strings.

property dtypes: Series#: Data types of the epoched data.

property is_equal_length: bool#

Whether all epochs have the same length.

Returns:

bool: True if all epochs have identical t_before and t_after durations.

property has_overlap: bool#

Whether any adjacent epochs overlap in time.

Returns:

bool: True if any adjacent epochs have overlapping time intervals.

plot(column_name: str | None = None, cmap_name: str = 'cool', ax: Axes | None = None, show: bool = True) → tuple[Figure, Axes]#

Plot data from a specified column from epochs on a matplotlib axis.

Parameters:

column_namestr: Name of the column to plot for Epochs constructed from a Stream. If Epochs was constructed from a Events, this parameter is ignored. Defaults to None.
cmap_namestr: Colormap to use for different epochs. Defaults to ‘cool’.
axmatplotlib.axes.Axes or None: Axis to plot on. If None, a new figure is created. Defaults to None.
showbool: Show the figure if True. Defaults to True.

Returns:

figmatplotlib.figure.Figure: Figure instance containing the plot.
axmatplotlib.axes.Axes: Axis instance containing the plot.

to_numpy(column_names: str | list[str] = 'all', sampling_rate: Number | None = None, float_kind: str | int = 'linear', other_kind: str | int = 'nearest') → tuple[ndarray, dict]#

Converts epochs into a 3D arrays with dimensions (n_epochs, n_channels, n_times). Acts similarly as mne.Epochs.get_data().

Requires the epoch to be created from a Stream.

Parameters:

column_namesstr or list of str, optional: Column names to include in the NumPy array. If “all”, all columns are included. Only numerical columns can be included. Default to “all”.
sampling_ratenumbers.Number, optional: Desired sampling rate in Hz for the output NumPy array. If None, the nominal sampling rate of the source Stream is used. Defaults to None.
float_kindstr or int, optional: Kind of interpolation applied to columns of float type. See scipy.interpolate.interp1d for details. Defaults to “linear”.
other_kindstr or int, optional: Kind of interpolation applied to columns of other types. See scipy.interpolate.interp1d for details. Only “nearest”, “nearest-up”, “previous”, and “next” are recommended. Defaults to “nearest”.

Returns:

numpy.ndarray

NumPy array of shape (n_epochs, n_channels, n_times).

infodict

A dictionary containing:

epoch_times	The common time grid, in nanoseconds.
column_names	List of provided column names.
nan_flag	Boolean indicating whether NaN values were found in the data.

apply_baseline(baseline: tuple[Number | None, Number | None] = (None, 0), method: Literal['mean', 'regression'] = 'mean', exclude_cols: list[str] = [], inplace: bool = True) → dict | None#

Apply baseline correction to epochs. Only applied to columns of float type.

The baseline data is extracted and used to compute the correction. When method="mean", the mean of the baseline window is subtracted from the entire epoch. When method="regression", a linear trend is fitted to the baseline window and subtracted.

For columns containing circular data (e.g., “yaw [deg]”), the correction is applied on unwrapped data (rad) and the result is wrapped back to degrees after correction.

Parameters:

baselinetuple[Number or None, Number or None], optional: Time window (relative to reference) for baseline computation in seconds. Defaults to (None, 0), which uses all data before the reference time.
method{“mean”, “regression”}, optional: Baseline correction method. Defaults to “mean”.
exclude_colslist of str, optional: Columns to exclude from baseline correction. Defaults to [].
inplacebool, optional: If True, replace epochs_dict. Otherwise returns a new instance of dict. Defaults to True.

Returns:

dict or None: A new dict with modified epoch data if inplace=False, otherwise None. See epochs_dict for details.

pyneon.events_to_epochs_info(events: Events, t_before: Number, t_after: Number, t_unit: Literal['s', 'ms', 'us', 'ns'] = 's', event_name: str | list[str] = 'all') → DataFrame#

Construct a epochs_info DataFrame suitable for creating epochs around event onsets.

For simple event classes (“blinks”, “fixations”, “saccades”), all events in the input are used automatically. For more complex or combined event collections (e.g., loaded from events.csv), you can either include all events (event_name=”all”) or filter by specific names using event_name.

Parameters:

eventsEvents: Events instance containing the event times.
t_beforenumbers.Number: Time before each event start to begin the epoch. Interpreted according to t_unit.
t_afternumbers.Number: Time after each event start to end the epoch. Interpreted according to t_unit.
t_unitstr, optional: Unit of time for t_before and t_after. Can be “s”, “ms”, “us”, or “ns”. Defaults to “s”.
event_namestr or list of str, optional: Only used if events.type is not one of “blinks”, “fixations”, or “saccades”. Otherwise, events.data must have a name column indicating event labels. If “all”, all events from events.data are included, and their name values become the epoch descriptions. If a string or list is provided, only matching events are included. Defaults to “all”.

Returns:

epochs_infopandas.DataFrame, shape (n_epochs, 4)

DataFrame containing epoch information with the following columns (times are UNIX timestamps in nanoseconds):

Column	Description
t_ref	Reference time of the epoch.
t_before	Time before the reference time to start the epoch.
t_after	Time after the reference time to end the epoch.
description	Description or label associated with the epoch.

Examples

Create epochs_info from blink events:

>>> epochs_info = events_to_epochs_info(blinks, t_before=1, t_after=1)
>>> print(epochs_info.head())
                 t_ref    t_before     t_after description
0  1766068460987724691  1000000000  1000000000       blink
1  1766068462919464691  1000000000  1000000000       blink
2  1766068463785334691  1000000000  1000000000       blink
3  1766068464836328691  1000000000  1000000000       blink
4  1766068465932322691  1000000000  1000000000       blink

Create epochs_info from “flash onset” events:

>>> epochs_info = events_to_epochs_info(
    events, t_before=0.5, t_after=3, event_name="flash onset")
>>> print(epochs_info.head())
                 t_ref   t_before     t_after  description
0  1766068461745390000  500000000  3000000000  flash onset
1  1766068465647497000  500000000  3000000000  flash onset
2  1766068469642822000  500000000  3000000000  flash onset
3  1766068473635128000  500000000  3000000000  flash onset
4  1766068477629326000  500000000  3000000000  flash onset

pyneon.construct_epochs_info(t_ref: ndarray, t_before: ndarray | Number, t_after: ndarray | Number, description: ndarray | str, t_ref_unit: Literal['s', 'ms', 'us', 'ns'] = 'ns', t_other_unit: Literal['s', 'ms', 'us', 'ns'] = 's', global_t_ref: int = 0) → DataFrame#

Construct the epochs_info DataFrame for creating epochs. It populates single values for t_before, t_after, and description to match the length of t_ref and converts all times to Unix timestamps in nanoseconds.

Parameters:

t_refnumpy.ndarray, optional: Array of reference times for the epochs. Units specified by t_ref_unit.
t_beforenumpy.ndarray or Number, optional: Time before the reference time to start the epoch. Could be an array of equal length as t_ref or a single number (to be repeated for all epochs). Units specified by t_other_unit.
t_afternumpy.ndarray or Number, optional: Time after the reference time to end the epoch. Could be an array of equal length as t_ref or a single number (to be repeated for all epochs). Units specified by t_other_unit.
descriptionnumpy.ndarray or str, optional: Description or label associated with the epochs. Could be an array of equal length as t_ref or a single string (to be repeated for all epochs).
t_ref_unitstr, optional: Unit of time for t_ref. Can be “s”, “ms”, “us”, or “ns”. Default is “ns”.
t_other_unitstr, optional: Unit of time for t_before and t_after. Can be “s”, “ms”, “us”, or “ns”. Default is “s”.
global_t_refint, optional: Global reference time (in nanoseconds) to be added to t_ref. Unit is nanosecond. Defaults to 0. This is useful when the reference times are relative to a global start time (for instance Stream.first_ts).

Returns:

epochs_infopandas.DataFrame, shape (n_epochs, 4)

DataFrame containing epoch information with the following columns (times are UNIX timestamps in nanoseconds):

Column	Description
t_ref	Reference time of the epoch.
t_before	Time before the reference time to start the epoch.
t_after	Time after the reference time to end the epoch.
description	Description or label associated with the epoch.

Epochs class#

This Page