mne_lsl.player.PlayerLSL🔗

class mne_lsl.player.PlayerLSL(fname, chunk_size=10, n_repeat=inf, *, name=None, source_id='MNE-LSL', annotations=None)[source]🔗

Class for creating a mock LSL stream.

Parameters:

fnamepath-like | Raw: Path to the file to re-play as a mock real-time stream. MNE-Python must be able to load the file with mne.io.read_raw(). An Raw object can be provided directly.
chunk_sizeint ≥ 1: Number of samples pushed at once on the StreamOutlet.
n_repeatint | np.inf: Number of times to repeat the file. If np.inf, the file is re-played indefinitely.
namestr | None: Name of the mock LSL stream. If None, the name MNE-LSL-Player is used.
source_idstr: A unique identifier of the device or source of the data. This information improves the system robustness since it allows recipients to recover from failure by finding a stream with the same source_id on the network. By default, the source_id is set to "MNE-LSL".
annotationsbool | None: If True, an StreamOutlet is created for the Annotations of the Raw object. If False, Annotations are ignored and the StreamOutlet is not created. If None (default), the StreamOutlet is created only if the Raw object has Annotations to push. See notes for additional information on the Annotations timestamps.

Attributes

`annotations`	Annotations attached to the raw object, if streamed.
`ch_names`	Name of the channels.
`chunk_size`	Number of samples in a chunk.
`compensation_grade`	The current gradient compensation grade.
`fname`	Path to file played.
`info`	Info of the real-time stream.
`n_repeat`	Number of times the file is repeated.
`name`	Name of the LSL stream.
`running`	Status of the player, True if it is running and pushing data.
`source_id`	Source ID of the LSL stream.

Methods

`anonymize`([daysback, keep_his, verbose])	Anonymize the measurement information in-place.
`get_channel_types`([picks, unique, only_data_chs])	Get a list of channel type for each channel.
`get_channel_units`([picks, only_data_chs])	Get a list of channel unit for each channel.
`get_montage`()	Get a DigMontage from instance.
`plot_sensors`([kind, ch_type, title, ...])	Plot sensor positions.
`rename_channels`(mapping[, allow_duplicates, ...])	Rename channels.
`set_channel_types`(mapping, *[, ...])	Define the sensor type of channels.
`set_channel_units`(mapping)	Define the channel unit multiplication factor.
`set_meas_date`(meas_date)	Set the measurement start date.
`set_montage`(montage[, match_case, ...])	Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points.
`start`()	Start streaming data on the LSL `StreamOutlet`.
`stop`()	Stop streaming data on the LSL `StreamOutlet`.

Notes

The file re-played is loaded in memory. Thus, large files are not recommended. Once the end-of-file is reached, the player loops back to the beginning which can lead to a small discontinuity in the data stream.

Each time a chunk (defined by chunk_size) is pushed on the StreamOutlet, the last sample of the chunk is attributed the current time (as returned by the function local_clock()). Thus, the sample chunk[0, :] occurred in the past and the sample chunk[-1, :] occurred “now”. If Annotations are streamed, the annotations within the chunk are pushed on the annotation StreamOutlet. The Annotations are pushed with a timestamp corrected for the annotation onset in regards to the chunk beginning. However, Annotations push is not delayed until the the annotation timestamp or until the end of the chunk. Thus, an Annotations can arrived at the client StreamInlet “ahead” of time, i.e. earlier than the current time (as returned by the function local_clock()). Thus, it is recommended to connect to an annotation stream with the StreamInlet or StreamLSL with the clocksync processing flag and to always inspect the timestamps returned for every samples.

from mne_lsl.lsl import local_clock
from mne_lsl.player import PlayerLSL as Player
from mne_lsl.stream import StreamLSL as Stream

player = Player(..., annotations=True)  # file with annotations
player.start()
stream = Stream(bufsize=100, stype="annotations")
stream.connect(processing_flags=["clocksync"])
data, ts = stream.get_data()
print(ts - local_clock())  # positive values are annotations in the "future"

If Annotations are streamed, the StreamOutlet name is {name}-annotations where name is the name of the PlayerLSL. The dtype is set to np.float64 and each unique Annotations description is encoded as a channel. The value streamed on a channel correspond to the duration of the Annotations. Thus, a sample on this StreamOutlet is a one-hot encoded vector of the Annotations description/duration.

anonymize(daysback=None, keep_his=False, *, verbose=None)[source]🔗

Anonymize the measurement information in-place.

Parameters:

daysbackint | None: Number of days to subtract from all dates. If None (default), the acquisition date, info['meas_date'], will be set to January 1ˢᵗ, 2000. This parameter is ignored if info['meas_date'] is None (i.e., no acquisition date has been set).
keep_hisbool: If True, his_id of subject_info will not be overwritten. Defaults to False.

Warning

This could mean that info is not fully anonymized. Use with caution.
verboseint | str | bool | None: Sets the verbosity level. The verbosity increases gradually between "CRITICAL", "ERROR", "WARNING", "INFO" and "DEBUG". If None is provided, the verbosity is set to the currently set logger’s level. If a bool is provided, the verbosity is set to "WARNING" for False and to "INFO" for True.

Returns:

playerinstance of Player: The player instance modified in-place.

Notes

Removes potentially identifying information if it exists in info. Specifically for each of the following we use:

meas_date, file_id, meas_id
A default value, or as specified by daysback.
subject_info
Default values, except for ‘birthday’ which is adjusted to maintain the subject age.
experimenter, proj_name, description
Default strings.
utc_offset
None.
proj_id
Zeros.
proc_history
Dates use the meas_date logic, and experimenter a default string.
helium_info, device_info
Dates use the meas_date logic, meta info uses defaults.

If info['meas_date'] is None, it will remain None during processing the above fields.

Operates in place.

get_channel_types(picks=None, unique=False, only_data_chs=False)[source]🔗

Get a list of channel type for each channel.

Parameters:

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.
uniquebool: Whether to return only unique channel types. Default is False.
only_data_chsbool: Whether to ignore non-data channels. Default is False.

Returns:

channel_typeslist: The channel types.

get_channel_units(picks=None, only_data_chs=False)[source]🔗

Get a list of channel unit for each channel.

Parameters:

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.
only_data_chsbool: Whether to ignore non-data channels. Default is False.

Returns:

channel_unitslist of tuple of shape (2,): A list of 2-element tuples. The first element contains the unit FIFF code and its associated name, e.g. 107 (FIFF_UNIT_V) for Volts. The second element contains the unit multiplication factor, e.g. -6 (FIFF_UNITM_MU) for micro (corresponds to 1e-6).

get_montage()[source]🔗

Get a DigMontage from instance.

Returns:

montageNone | str | DigMontage: A montage containing channel positions. If a string or DigMontage is specified, the existing channel information will be updated with the channel positions from the montage. Valid strings are the names of the built-in montages that ship with MNE-Python; you can list those via mne.channels.get_builtin_montages(). If None (default), the channel positions will be removed from the Info.

plot_sensors(kind='topomap', ch_type=None, title=None, show_names=False, ch_groups=None, to_sphere=True, axes=None, block=False, show=True, sphere=None, *, verbose=None)🔗

Plot sensor positions.

Parameters:

kindstr: Whether to plot the sensors as 3d, topomap or as an interactive sensor selection dialog. Available options ‘topomap’, ‘3d’, ‘select’. If ‘select’, a set of channels can be selected interactively by using lasso selector or clicking while holding control key. The selected channels are returned along with the figure instance. Defaults to ‘topomap’.
ch_typeNone | str: The channel type to plot. Available options 'mag', 'grad', 'eeg', 'seeg', 'dbs', 'ecog', 'all'. If 'all', all the available mag, grad, eeg, seeg, dbs, and ecog channels are plotted. If None (default), then channels are chosen in the order given above.
titlestr | None: Title for the figure. If None (default), equals to 'Sensor positions (%s)' % ch_type.
show_namesbool | array of str: Whether to display all channel names. If an array, only the channel names in the array are shown. Defaults to False.
ch_groups‘position’ | array of shape (n_ch_groups, n_picks) | None: Channel groups for coloring the sensors. If None (default), default coloring scheme is used. If ‘position’, the sensors are divided into 8 regions. See order kwarg of mne.viz.plot_raw(). If array, the channels are divided by picks given in the array.

Added in version 0.13.0.
to_spherebool: Whether to project the 3d locations to a sphere. When False, the sensor array appears similar as to looking downwards straight above the subject’s head. Has no effect when kind=’3d’. Defaults to True.

Added in version 0.14.0.
axesinstance of Axes | instance of Axes3D | None: Axes to draw the sensors to. If kind='3d', axes must be an instance of Axes3D. If None (default), a new axes will be created.

Added in version 0.13.0.
blockbool: Whether to halt program execution until the figure is closed. Defaults to False.

Added in version 0.13.0.
showbool: Show figure if True. Defaults to True.
spherefloat | array_like | instance of ConductorModel | None | ‘auto’ | ‘eeglab’: The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

Added in version 0.20.

Changed in version 1.1: Added 'eeglab' option.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

figinstance of Figure: Figure containing the sensor topography.
selectionlist: A list of selected channels. Only returned if kind=='select'.