mne_lsl.stream.EpochsStream

class mne_lsl.stream.EpochsStream(stream, bufsize, event_id, event_channels, event_stream=None, tmin=-0.2, tmax=0.5, baseline=(None, 0), picks=None, reject=None, flat=None, reject_tmin=None, reject_tmax=None, detrend=None)

Stream object representing a single real-time stream of epochs.

Note that a stream of epochs is necessarily connected to a regularly sampled stream of continuous data, from which epochs are extracted depending on an internal event channel or to an external event stream.

Parameters:

streamStream

Stream object to connect to, from which the epochs are extracted. The stream must be regularly sampled.

bufsizeint

Number of epochs to keep in the buffer. The buffer size is defined by this number of epochs and by the duration of individual epochs, defined by the argument tmin and tmax.

Note

For a new epoch to be added to the buffer, the epoch must be fully acquired, i.e. the last sample of the epoch must be received. Thus, an epoch is acquired at least tmax seconds after the event onset.

event_idint | dict | None

The ID of the events to consider from the event source. The event source can be a channel from the connected Stream or a separate event stream. In both case the event should be defined either as int or dict. If a dict is provided, it should map event names to event IDs. For example dict(auditory=1, visual=2).

event_channelsstr | list of str

Channel(s) to monitor for incoming events. The event channel(s) must be part of the connected Stream or of the event_stream if provided. See notes for details.

event_streamStream | None

Source from which events should be retrieved. If provided, event channels in the connected stream are ignored in favor of the event channels in this separate event_stream. See notes for details.

Note

If a separate event stream is provided, time synchronization between the connected stream and the event stream is very important. For StreamLSL objects, provide processing_flags='all' as argument during connection with connect().

tmin, tmaxfloat

Start and end time of the epochs in seconds, relative to the time-locked event. The closest or matching samples corresponding to the start and end time are included. Defaults to -0.2 and 0.5, respectively.

baselineNone | tuple of length 2

The time interval to consider as “baseline” when applying baseline correction. If None, do not apply baseline correction. If a tuple (a, b), the interval is between a and b (in seconds), including the endpoints. If a is None, the beginning of the data is used; and if b is None, it is set to the end of the data. If (None, None), the entire time interval is used.

Note

The baseline (a, b) includes both endpoints, i.e. all timepoints t such that a <= t <= b.

Correction is applied to each epoch and channel individually in the following way:

1. Calculate the mean signal of the baseline period.

2. Subtract this mean from the entire epoch.

picksstr | array_like | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all channels.

rejectdict | None

Reject epochs based on maximum peak-to-peak signal amplitude (PTP), i.e. the absolute difference between the lowest and the highest signal value. In each individual epoch, the PTP is calculated for every channel. If the PTP of any one channel exceeds the rejection threshold, the respective epoch will be dropped.

The dictionary keys correspond to the different channel types; valid keys can be any channel type present in the object.

Example:

reject = dict(grad=4000e-13,  # unit: T / m (gradiometers)
              mag=4e-12,      # unit: T (magnetometers)
              eeg=40e-6,      # unit: V (EEG channels)
              eog=250e-6      # unit: V (EOG channels)
              )

Note

Since rejection is based on a signal difference calculated for each channel separately, applying baseline correction does not affect the rejection procedure, as the difference will be preserved.

Note

To constrain the time period used for estimation of signal quality, pass the reject_tmin and reject_tmax parameters.

If reject is None (default), no rejection is performed.

flatdict | None

Reject epochs based on minimum peak-to-peak signal amplitude (PTP). Valid keys can be any channel type present in the object. The values are floats that set the minimum acceptable PTP. If the PTP is smaller than this threshold, the epoch will be dropped. If None then no rejection is performed based on flatness of the signal.

Note

To constrain the time period used for estimation of signal quality, pass the reject_tmin and reject_tmax parameters.

reject_tmin, reject_tmaxfloat | None

Start and end of the time window used to reject epochs based on peak-to-peak (PTP) amplitudes as specified via reject and flat. The default None corresponds to the first and last time points of the epochs, respectively.

Note

This parameter controls the time period used in conjunction with both, reject and flat.

detrendint | str | None

The type of detrending to use. Can be 'constant' or 0 for constant (DC) detrend, 'linear' or 1 for linear detrend, or None for no detrending. Note that detrending is performed before baseline correction.

Attributes

connected	Connection status of the EpochsStream.
events	Events of the epoched LSL stream.
info	Info of the epoched LSL stream.
n_new_epochs	Number of new epochs available in the buffer.
times	The time of each sample in the epochs.

Methods

acquire()	Pull new epochs in the buffer.
connect([acquisition_delay])	Start acquisition of epochs from the connected Stream.
disconnect()	Stop acquisition of epochs from the connected Stream.
get_data([n_epochs, picks, exclude])	Retrieve the latest epochs from the buffer.

Notes

Since events can be provided from multiple source, the arguments event_channels, event_source and event_id must work together to select which events should be considered.

• if event_stream is None, the events are extracted from channels within the connected stream. This stream is necessarily regularly sampled, thus the event channels must correspond to MNE 'stim' channels, i.e. channels on which mne.find_events() can be applied.

• if event_stream is provided and is regularly sampled, the events are extracted from channels in the event_stream. The event channels must correspond to MNE 'stim' channels, i.e. channels on which mne.find_events() can be applied.

• if event_stream is provided and is irregularly sampled, the events are extracted from channels in the event_stream.

  • If event_id is None, the numerical value within the channels are ignored and the appearance of a new value in the stream is considered as a new event named after the channel name. This case can be useful when working with a Player replaying annotations from a file as one-hot encoded events.

  • If event_id is provided, the events are selected based on the selected channels in event_channels and the provided event_id.

    Note

    In this case, the EpochsStream expects a numerical event on only one channel at a time. In other words, the sample pushed to the event stream should have only one non-zero value at a time. If this is not the case, only the maximum sample value is considered as the event code.

Event streams irregularly sampled and using a str datatype are not supported.

Note

In the last cases where event_stream is provided, all 'stim' channels in the connected stream are ignored.

Read about the processing applied to the underlying buffer.

acquire()

Pull new epochs in the buffer.

This method is used to manually acquire new epochs in the buffer. If used, it is up to the user to call this method at the desired frequency, else it might miss some of the events and associated epochs.

Notes

This method is not needed if the mne_lsl.stream.EpochsStream was connected with an acquisition delay different from 0. In this case, the acquisition is done automatically in a background thread.

connect(acquisition_delay=0.001)

Start acquisition of epochs from the connected Stream.

Parameters:

acquisition_delayfloat | None

Delay in seconds between 2 updates at which the event stream is queried for new events, and thus at which the epochs are updated. If None, the automatic acquisition in a background thread is disabled and the user must manually call the acquisition method :meth:~`mne_lsl.stream.EpochsStream.acquire` to pull new samples.

Note

For a new epoch to be added to the buffer, the epoch must be fully acquired, i.e. the last sample of the epoch must be received. Thus, an epoch is acquired tmax seconds after the event onset.

Returns:

epochs_streaminstance of EpochsStream

The EpochsStream instance modified in-place.

disconnect()

Stop acquisition of epochs from the connected Stream.

Returns:

epochsinstance of EpochsStream

The epochs instance modified in-place.

get_data(n_epochs=None, picks=None, exclude='bads')

Retrieve the latest epochs from the buffer.

Parameters:

n_epochsint | None

Number of epochs to retrieve from the buffer. If None, all epochs are returned.

picksstr | array_like | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

excludestr | list of str | tuple of str

Set of channels to exclude, only used when picking based on types (e.g., exclude="bads" when picks="meg") or when picking is set to None.

Returns:

dataarray of shape (n_epochs, n_channels, n_samples)

Data in the buffer.

Notes

The number of newly available epochs stored in the property n_new_epochs is reset at every function call, even if all channels were not selected with the argument picks.

property connected

Connection status of the EpochsStream.

Type:

bool

property events

Events of the epoched LSL stream.

Contrary to the events stored in mne.Epochs.events, only the integer code of the event is stored in a EpochsStream object.

Type:

numpy.ndarray

property info

Info of the epoched LSL stream.

Type:

Info

property n_new_epochs

Number of new epochs available in the buffer.

The number of new epochs is reset at every Stream.get_data call.

Type:

int

property times

The time of each sample in the epochs.

Type:

numpy.ndarray

Examples using mne_lsl.stream.EpochsStream

Real-time evoked responses

Real-time evoked responses

Decoding real-time data

Decoding real-time data

Epoching a Stream in real-time

Epoching a Stream in real-time