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)[source]π
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:
- stream
Stream
Stream object to connect to, from which the epochs are extracted. The stream must be regularly sampled.
- bufsize
int
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
andtmax
.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_id
int
|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
. If adict
is provided, it should map event names to event IDs. For exampledict(auditory=1, visual=2)
. If the event source is an irregularly sampled stream, the numerical values within the channels are ignored and this argument is ignored in which case it should be set toNone
.- event_channels
str
|list
ofstr
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_stream
Stream
|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 separateevent_stream
. See notes for details.- tmin, tmax
float
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
and0.5
, respectively.- baseline
None
|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 betweena
andb
(in seconds), including the endpoints. Ifa
isNone
, the beginning of the data is used; and ifb
isNone
, 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 timepointst
such thata <= t <= b
.Correction is applied to each epoch and channel individually in the following way:
Calculate the mean signal of the baseline period.
Subtract this mean from the entire epoch.
- picks
str
| 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.- reject
dict
|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
andreject_tmax
parameters.If
reject
isNone
(default), no rejection is performed.- flat
dict
|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
andreject_tmax
parameters.- reject_tmin, reject_tmax
float
|None
Start and end of the time window used to reject epochs based on peak-to-peak (PTP) amplitudes as specified via
reject
andflat
. The defaultNone
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
andflat
.- detrend
int
|str
|None
The type of detrending to use. Can be
'constant'
or0
for constant (DC) detrend,'linear'
or1
for linear detrend, orNone
for no detrending. Note that detrending is performed before baseline correction.
- stream
Attributes
Connection status of the
EpochsStream
.Events of the epoched LSL stream.
Info of the epoched LSL stream.
Number of new epochs available in the buffer.
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.
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
andevent_id
must work together to select which events should be considered.if
event_stream
isNone
, the events are extracted from channels within the connectedstream
. Thisstream
is necessarily regularly sampled, thus the event channels must correspond to MNE'stim'
channels, i.e. channels on whichmne.find_events()
can be applied.if
event_stream
is provided and is regularly sampled, the events are extracted from channels in theevent_stream
. The event channels must correspond to MNE'stim'
channels, i.e. channels on whichmne.find_events()
can be applied.if
event_stream
is provided and is irregularly sampled, the events are extracted from channels in theevent_stream
. 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. Thus, the argumentevent_id
is ignored. This last case can be useful when working with aPlayer
replaying annotations from a file as one-hot encoded events.
Event streams irregularly sampled and a
str
datatype are not yet supported.Note
In the 2 last cases where
event_stream
is provided, all'stim'
channels in the connectedstream
are ignored.Read about the processing applied to the underlying buffer.
- acquire()[source]π
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 from0
. In this case, the acquisition is done automatically in a background thread.
- connect(acquisition_delay=0.001)[source]π
Start acquisition of epochs from the connected Stream.
- Parameters:
- acquisition_delay
float
|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.
- acquisition_delay
- Returns:
- epochs_streaminstance of
EpochsStream
The
EpochsStream
instance modified in-place.
- epochs_streaminstance of
- disconnect()[source]π
Stop acquisition of epochs from the connected Stream.
- Returns:
- epochsinstance of
EpochsStream
The epochs instance modified in-place.
- epochsinstance of
- get_data(n_epochs=None, picks=None, exclude='bads')[source]π
Retrieve the latest epochs from the buffer.
- Parameters:
- n_epochs
int
|None
Number of epochs to retrieve from the buffer. If None, all epochs are returned.
- picks
str
| 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 ininfo['bads']
will be included if their names or indices are explicitly provided.- exclude
str
|list
ofstr
|tuple
ofstr
Set of channels to exclude, only used when picking based on types (e.g.,
exclude="bads"
whenpicks="meg"
) or when picking is set toNone
.
- n_epochs
- Returns:
- data
array
of shape (n_epochs, n_channels, n_samples) Data in the buffer.
- data
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 argumentpicks
.
- property connectedπ
Connection status of the
EpochsStream
.- Type:
- 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 aEpochsStream
object.- Type:
- 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:
- property timesπ
The time of each sample in the epochs.
- Type:
Examples using mne_lsl.stream.EpochsStream
π
Epoching a Stream in real-time