Epochs class#

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

Class to create and manage epochs in the data streams.

Parameters:

source (Stream or Events) – Data to create epochs from.
times_df (pandas.DataFrame, shape (n_epochs, 4), optional) –
DataFrame containing epoch information with the following columns:

t_ref: Reference time of the epoch, in nanoseconds.

t_before: Time before the reference time to start the epoch, in nanoseconds.

t_after: Time after the reference time to end the epoch, in nanoseconds.

description: Description or label associated with the epoch.

Must not have empty values.

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]->
├--------------------------------------------------------------------------------┤

epochs#

DataFrame containing epoch information with the following columns:

t_ref (int64): Reference time of the epoch, in nanoseconds.

t_before (int64): Time before the reference time to start the epoch, in nanoseconds.

t_after (int64): Time after the reference time to end the epoch, in nanoseconds.

description (str): Description or label associated with the epoch.

data (object): DataFrame containing the data for each epoch.

Type:: pandas.DataFrame

data#

Annotated data with epoch information. In addition to the original data columns, the following columns are added:

epoch index (Int32): ID of the epoch the data belongs to.

epoch time (Int64): Time relative to the epoch reference time, in nanoseconds.

epoch description (str): Description or label associated with the epoch.

If epochs overlap, data annotations are always overwritten by the latest epoch.

Type:: pandas.DataFrame

property t_ref: ndarray#: The reference time for each epoch in UTC nanoseconds.

property t_before: ndarray#: The time before the reference time for each epoch in nanoseconds.

property t_after: ndarray#: The time after the reference time for each epoch in nanoseconds.

property description: ndarray#: The description or label for each epoch.

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

property is_equal_length: bool#: Whether all epochs have the same length.

property has_overlap: bool#: Whether any adjacent epochs overlap.

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_name (str) – Name of the column to plot for pyneon.Epochs constructed from a pyneon.Stream. If pyneon.Epochs was constructed from a pyneon.Events, this parameter is ignored. Defaults to None.
cmap_name (str) – Colormap to use for different epochs. Defaults to ‘cool’.
ax (matplotlib.axes.Axes or None) – Axis to plot the data on. If None, a new figure is created. Defaults to None.
show (bool) – Show the figure if True. Defaults to True.

Returns:

fig (matplotlib.figure.Figure) – Figure object containing the plot.
ax (matplotlib.axes.Axes) – Axis object containing the plot.

to_numpy(column_names: str | list[str] = 'all') → tuple[ndarray, dict]#

Converts epochs into a 3D array with dimensions (n_epochs, n_channels, n_times). Acts similarly as mne.Epochs.get_data(). Requires the epoch to be created from a uniformly-sampled pyneon.Stream.

Parameters:

column_names (str or list of str, optional) – Column names to include in the NumPy array. If ‘all’, all columns are included. Only columns that can be converted to int or float can be included. Default is ‘all’.

Returns:

numpy_epochs (numpy.ndarray) – NumPy array of shape (n_epochs, n_channels, n_times).
info (dict) –

A dictionary containing:

"column_ids": List of provided column names.

"t_rel": The common time grid, in nanoseconds.

"nan_flag": Boolean indicating whether NaN values were found in the data.

Notes

The time grid (t_rel) is in nanoseconds.
If NaN values are present after interpolation, they are noted in nan_flag.

baseline_correction(baseline: tuple[Number | None, Number | None] = (None, 0), method: str = 'mean', inplace: bool = True) → DataFrame#

Perform baseline correction on epochs.

Parameters:

baseline ((t_min, t_max), iterable of float | None) – Start and end of the baseline window in seconds, relative to the event trigger (t_ref = 0). None means “from the first / up to the last sample”. Default: (None, 0.0) -> the pre-trigger part of each epoch.
method ("mean" or "linear", optional) –
- "mean" - Subtract the scalar mean of the baseline window.
- "linear" - Fit a first-order (\(y = at + b\)) model within the baseline window and remove the fitted trend from the entire epoch (a very small, fast version of MNE’s regression detrending).
Defaults to “mean”.
inplace (bool) – If True, overwrite epochs data. Otherwise return a new, corrected pandas.DataFrame and leave the object unchanged. Defaults to True.

Returns:

The baseline-corrected data (same shape & dtypes as original data).

Return type:

pandas.DataFrame

pyneon.events_to_times_df(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 times_df DataFrame suitable for creating epochs from event data. For “simple” events (blinks, fixations, saccades), all events are used. For more complex events (e.g., from “events.csv”, or concatenated events), the user can specify which events to include by a name column.

Parameters:

events (Events) – Events instance containing the event times.
t_before (numbers.Number) – Time before the event start time to start the epoch. Units specified by t_unit.
t_after (numbers.Number) – Time after the event start time to end the epoch. Units specified by t_unit.
t_unit (str, optional) – Unit of time for t_before and t_after. Can be "s", "ms", "us", or "ns". Default is "s".
event_name (str or list of str, optional) – Only used if events includes more than one event type. If "all", all events are used. Otherwise, the name column is used to filter events whose names are in the list. Default to "all".

Returns:

DataFrame with columns: t_ref, t_before, t_after, description (all in ns).

Return type:

pandas.DataFrame

pyneon.construct_times_df(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#

Handles the construction of the times_df 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 UTC timestamps in nanoseconds.

Parameters:

t_ref (numpy.ndarray, optional) – Array of reference times for the epochs. Units specified by t_ref_unit.
t_before (numpy.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_after (numpy.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.
description (numpy.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_unit (str, optional) – Unit of time for t_ref. Can be "s", "ms", "us", or "ns". Default is "ns".
t_other_unit (str, optional) – Unit of time for t_before and t_after. Can be "s", "ms", "us", or "ns". Default is "s".
global_t_ref (int, 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 pyneon.Stream.first_ts).

Returns:

DataFrame with columns: t_ref, t_before, t_after, description (all in ns).

Return type:

pandas.DataFrame

Epochs class#

This Page