API documentation¶

A complete catalogue of all package functions can be found on this page.

EEG Objects Module¶

Module for creating custom epoch objects

class simpl_eeg.eeg_objects.EEG_File(folder_path, file_name='auto', events_file='auto', montage='auto')¶

A class to import and store relevant eeg files

Attributes:

folder_path: str: path to experiment folder.
experiment: str: the name of the folder containing experiment files.
mat: list of ints: a list of integers representing impact times.
raw: mne.io.eeglab.eeglab.RawEEGLAB: raw experiment data in FIF format.

class simpl_eeg.eeg_objects.Epochs(folder_path, tmin=- 0.3, tmax=0.7, start_second=None, file_name='auto', events_file='auto', montage='auto', **kwargs)¶

A class to represent epochs and underlying data

Attributes:

eeg_file: EEG_File: eeg file data
all_epochs: mne.Epochs: the generated epoch data
epoch: mne.Epochs: the selected epoch of interest

Methods:

generate_epochs(duration, start_second):: Calculates epochs based on a duration and start second.
get_epoch(epoch_num):: Set and return the epoch of interest.
skip_n_steps(num_steps):: Returns a subset of the epoch by skipping records in increments of num_steps.

average_n_steps(num_steps)¶

Return new epoch containing every nth frame for the selected epoch Averages steps bewteen frames

Parameters:

num_steps: int: The number of time steps to average

Returns:

mne.Evoked:: The reduced size epoch in evoked format

generate_epochs(tmin, tmax, start_second, **kwargs)¶

Generates an epoch object based on the given input

Parameters:

tmin: float

Number of seconds before the event time to include in epoch

tmax: float

Number of seconds after the event time to include in epoch

start_second: int

Second of the event time, or None if autodetected event time should be used

**kwargs: dict (optional)

Additional parameters to pass to the mne.Epochs() constructor

Full list of options available at https://mne.tools/stable/generated/mne.Epochs.html

Returns:

mne.Epochs:: The generated epoch(s)

get_epoch(epoch_num)¶

Get the nth epoch from the genertated epochs

Parameters:

epoch_num: int: The epoch to select

Returns:

mne.Epoch:: The epoch of interest

skip_n_steps(num_steps, use_single=True)¶

Return new epoch containing every nth frame Skips steps between frames

Parameters:

num_steps: int: The number of time steps to skip
use_single: bool (optional): Whether to apply the skipping to all epochs or the current selected epoch only

Returns:

mne.Epochs:: The reduced size epoch

simpl_eeg.eeg_objects.load_events(file_type, raw=None, events_file='auto', folder_path=None)¶: Helper function for __init__ in EEG_File class that loads events information. Returns events list as first argument and source of events file as the second. If the primary data file does not contain events information (.set, .gdf) then it loads events for external events file (.mat). If no events_file name is provided the alphabetically first .mat file in the folder_path directory which is flagged for having less than 5,000 events will be loaded. If events exists within the primary data file (.vhdr, .bdf, .edf, .cnt) then the will be loaded from it and events_file will be ignored. Returns None if no events can be loaded.

simpl_eeg.eeg_objects.load_file_EEG(data_path, folder_path, events_file, montage)¶: Helper function for __init__ in EEG_File class used to load Nihon Kohden data file (.EEG) files.

simpl_eeg.eeg_objects.load_file_bdf(data_path, montage)¶: Helper function for __init__ in EEG_File class used to load .bdf files.

simpl_eeg.eeg_objects.load_file_cnt(data_path, montage)¶: Helper function for __init__ in EEG_File class used to load .cnt files. .cnt files are assumed to contain events

simpl_eeg.eeg_objects.load_file_edf(data_path, montage)¶: Helper function for __init__ in EEG_File class used to load .edf files.

simpl_eeg.eeg_objects.load_file_gdf(data_path, folder_path, events_file, montage)¶: Helper function for __init__ in EEG_File class used to load .gdf files.

simpl_eeg.eeg_objects.load_file_lay(data_path, folder_path, events_file, montage)¶: Helper function for __init__ in EEG_File class used to load eximia (.lay) files.

simpl_eeg.eeg_objects.load_file_nxe(data_path, folder_path, events_file, montage)¶: Helper function for __init__ in EEG_File class used to load eximia (.nxe) files.

simpl_eeg.eeg_objects.load_file_set(data_path, folder_path, events_file, montage)¶: Helper function for __init__ in EEG_File class used to load .set files. If some data is stored in a .fdt file in the same directory then it will be loaded automatically.

simpl_eeg.eeg_objects.load_file_vhdr(data_path, montage)¶: Helper function for __init__ in EEG_File class used to load .vhdr files.

simpl_eeg.eeg_objects.load_montage(raw, montage='auto')¶

Helper function for __init__ in EEG_File class that loads a montage if one is not set. If no montage is specified will try to load an “easycap-M1” montage. Returns None if no montage can be loaded.

Attributes:

raw: mne.io.eeglab.eeglab.RawEEGLAB: raw experiment data in FIF format

Raw Voltage Module¶

simpl_eeg.raw_voltage.plot_voltage(epoch, remove_xlabel=False, show_times=True, height=None, width=None, **kwargs)¶

Generate raw voltage plot

Parameters:

epoch: mne.epochs.Epochs

Epoch(s) to display

remove_xlabel: bool (optional)

Whether to remove the x-axis label. Defaults to False.

show_times: bool (optional)

Whether to show seconds on the x-axis. Defaults to True.

height: float | None (optional)

Height of the plot in inches. Defaults to None for automatic.

width: float | None (optional)

Width of the plot in inches. Defaults to None for automatic.

**kwargs: dict (optional)

Optional arguments to pass to mne.Epochs.plot()

Full list of options available at https://mne.tools/stable/generated/mne.Epochs.html#mne.Epochs.plot

Returns:

matplotlib.figure.Figure:: The raw voltage plot figure

Topomap 2D Module¶

simpl_eeg.topomap_2d.add_timestamp(epoch, x_pos, y_pos, frame_number)¶

Adds a timestamp to a matplotlib.image.AxesImage object.

Parameters:

epoch: mne.epochs.Epochs: MNE epochs object containing the timestamps.
ax_lims: tuple: A tuple of the ax_lims.
frame_number: int: The timestamp to plot.

simpl_eeg.topomap_2d.animate_topomap_2d(epoch, plotting_data=None, colormap='RdBu_r', mark='dot', vmin=- 30, vmax=30, sphere='auto', colorbar=True, timestamp=True, frame_rate=12, **kwargs)¶

Plots a still image mne.epochs.Epochs EEG data as a 2D topomap using the mne.viz.plot_topomap function.

Parameters:

epoch: mne.epochs.Epochs or mne.evoked.EvokedArray: MNE epochs object (or evoked array object) containing portions of raw EEG data built around specified timestamp(s).
plotting_data: numpy.ndarray or None: Array of the EEG data from a measurement (not a time interval) to be plotted should be in the format (num_channels, num_frames) i.e. multiple rows of values for the timestamps you plan to plot. If plotting_data is provided the heatmap in the figure will be built from it in conjunction with the ‘info’ from the provided epoch (containing information like node names and locations). If no plotting_data is provided the heatmap will be built from the EEG data in the epoch instead.
colormap: matplotlib colormap or None: Specifies the ‘colormap’ parameter to be used in the mne.viz.plot_topomap() and in colorbar generation. Defaults to ‘RdBu_r’.
mark: str: Specifies what kind of marker should be shown for each node on the topomap. Can be one of ‘dot’, ‘r+’ (for red +’s), ‘channel_name’, or ‘none’. Defaults to ‘dot’.
vmin: float: Specifies the ‘vmin’ parameter in the mne.viz.plot_topomap() function. Sets the limits for the colors which will be used on the topomap. Value is in μV. Defaults to -30.
vmax: float: Specifies the ‘vmax’ parameter in the mne.viz.plot_topomap() function. Sets the limits for the colors which will be used on the topomap. Value is in μV. Defaults to +30.
colorbar: bool: Specifies whether or not to include a colorbar in the animation. Removing will lead to a marginal decrease in rendering times. Defaults to True.
timestamp: bool: Specifies whether or not to show the timestamp on the plot relative to the time in the epoch that is being shown. Defaults to True.
frame_rate: int or float: The frame rate to genearte the final animation with. Defaults to 12.
**kwargs: various: Additional arguments from the ‘mne.viz.plot_topomap’ function (https://mne.tools/stable/generated/mne.viz.plot_topomap.html) may also be passed. Since this function is used under-the-hood most of these arguments should work exactly as they do in their original function. The exact list of avalible arguments and their defaults includes: [contours: 0, sphere: 100, res: 64, extrapolate: ‘head’, outlines: ‘head, mask: None, mask_params: None, image_interp: ‘blinear’, show: False, onselect: None, border: ‘mean’, ch_type: ‘eeg’]. The ‘axes’ argument is not avalible since it does not work with animations. Some arguments may break this function. The arguments that are tested and known to work include [res, sphere, extrapolate, outlines, contours, outlines, and border].

Returns:

ani: matplotlib.animation.FuncAnimation: matplotlib funcanimation of a 2d topographic map based on the input epoch data.

simpl_eeg.topomap_2d.get_axis_lims(epoch)¶

Generates an invisible mne.viz.plot_topomap plot and gets the ylim from its matplotlib.axes._subplots.AxesSubplot.

Parameters:

epoch: mne.epochs.Epochs: MNE epochs object containing the timestamps.

Returns:

ax_lims: tuple: A tuple of the ax_lims.

simpl_eeg.topomap_2d.plot_topomap_2d(epoch, plotting_data=None, recording_number=0, colormap='RdBu_r', colorbar=True, vmin=- 30, vmax=30, mark='dot', sphere='auto', timestamp=True, **kwargs)¶

Plots a still image mne.epochs.Epochs EEG data as a 2D topomap using the mne.viz.plot_topomap function.

Parameters:

epoch: mne.epochs.Epochs or mne.evoked.EvokedArray: MNE epochs object (or evoked array object) containing portions of raw EEG data built around specified timestamp(s).
plotting_data: numpy.ndarray or None: Array of the EEG data from a measurement (not a time interval) to be plotted should be in the format (num_channels, ) i.e. a single row of values for the only timestamp you plan to plot. If plotting_data is provided the heatmap in the figure will be built from it in conjunction with the ‘info’ from the provided epoch (containing information like node names and locations). If no plotting_data is provided the heatmap will be built from the EEG data in the epoch instead. Defaults to None.
recording_number: int: The index of the data recording in the epoch to show in the plot. Defaults to 0.
colormap: matplotlib colormap or None: Specifies the ‘colormap’ parameter to be used in the mne.viz.plot_topomap() and in colorbar generation. Defaults to ‘RdBu_r’.
colorbar: bool: Specifies whether to include a colorbar or not. Removing it will marginally improve performance. Defaults to True.
vmin: float: Specifies the ‘vmin’ parameter in the mne.viz.plot_topomap() function. Sets the limits for the colors which will be used on the topomap. Value is in μV. Defaults to -30.
vmax: float: Specifies the ‘vmax’ parameter in the mne.viz.plot_topomap() function. Sets the limits for the colors which will be used on the topomap. Value is in μV. Defaults to +30.
mark: str: Specifies what kind of marker should be shown for each node on the topomap. Can be one of ‘dot’, ‘r+’ (for red +’s), ‘channel_name’, or ‘none’. Deaults to ‘dot’.
timestamp: bool: Specifies whether or not to show the timestamp on the plot relative to the time in the epoch that is being shown. Defaults to True.
**kwargs: various: Additional arguments from the ‘mne.viz.plot_topomap’ function (https://mne.tools/stable/generated/mne.viz.plot_topomap.html) may also be passed. Since this function is used under-the-hood most of these arguments should work exactly as they do in their original function. The exact list of avalible arguments and their defaults includes: [contours: 0, sphere: 100, res: 64, extrapolate: ‘head’, outlines: ‘head, mask: None, mask_params: None, image_interp: ‘blinear’, show: False, onselect: None, border: ‘mean’, ch_type: ‘eeg’, axes: None]. Some arguments may break this function. The arguments that are tested and known to work include [res, sphere, extrapolate, outlines, contours, outlines, border].

Returns:

topo_2d_fig: matplotlib.image.AxesImage: matplotlib image plot of a 2d topographic map based on the input epoch data.

Topomap 3D Head Module¶

Module for generating and animating the topographic map in a 3D head shape

simpl_eeg.topomap_3d_head.frame_args(duration)¶

Return the frame arguments of the animated plot

Parameters:

duration: int: The number of seconds per frame for the animated plot

Returns:

dict:: A dictionary of frame arguments

simpl_eeg.topomap_3d_head.get_eeg_node(raw, standard_montage_list)¶

Get the electrode location from the raw data

Parameters:

raw: mne.epochs.Epochs: The raw epoch data
standard_montage_list: numpy.ndarray: The numpy array which contains the cartesian coordinate of standard node location

Returns:

numpy.ndarray:: The electrode location from the raw data

simpl_eeg.topomap_3d_head.get_node_dataframe(raw, montage)¶

Get the electrode name and electrode location from the raw data and save it in a dataframe

Parameters:

raw: mne.epochs.Epochs: The raw epoch data
montage: numpy.ndarray: The numpy array which contains the cartesian coordinate of standard node location

Returns:

pandas.core.frame.DataFrame:: A dataframe which contains the electrode name and electrode location from the raw data

simpl_eeg.topomap_3d_head.get_standard_coord()¶

Generate an array of cartesian coordinates of the standard node locations (“standard_1005”)

Returns:

mne.channels.montage:: The standard montage from the mne library
array:: A numpy array of cartesian coordinates of the standard node locations (“standard_1005”)

simpl_eeg.topomap_3d_head.interpolated_time(df, channel_names, node_coord, x, y, z, t)¶

To interpolate EEG signals to locations points that don’t have data

Parameters:

df: dataframe: A dataframe that contains the EEG signal of each channels for each time stamps
channel_names: list: A list of channel names in the raw data
node_coord: array: A numpy array of (x, y, z) coordinates of all channels in the raw data
x: array: A numpy array of X coordinates of all channels for interpolation
y: array: A numpy array of Y coordinates of all channels for interpolation
z: array: A numpy array of Z coordinates of all channels for interpolation
t: int: The time stamp we want to interpolate EEG voltages for

Returns:

numpy.ndarray:: A numpy array of interpolated EEG voltages

simpl_eeg.topomap_3d_head.save_gif(epoch, gifname, duration, data_df=None)¶

Save the animated plot as gif file

Parameters:

epoch: mne.epochs.Epochs: The epoch file for creating gif.
gifname: str: The file name.
duration: int: The duration (milliseconds) between each frame.
data_df: pd.core.frame.DataFrame: A data frame of EEG data if epoched data is not of interest

simpl_eeg.topomap_3d_head.topo3dhead_plot(epoch, i, data_df=None)¶

To generate a static image for each gif frame

Parameters:

epoch: mne.epochs.Epochs: An epoched file for the EEGLab data
data_df: pd.core.frame.DataFrame: A data frame of EEG data if epoched data is not of interest
i: int: The time stamp that is of interest

Returns:

plotly.graph_objs._figure.Figure:: The 3D topograpic map on 3D shape

simpl_eeg.topomap_3d_head.topo_3d_map(epoch, time_stamp, data_df=None, color_title='EEG MicroVolt', vmin=- 50, vmax=50, colormap='Bluered')¶

Plot a topographic map in a 3D head shape for a single time stamp

Parameters:

epoch: mne.epochs.Epochs: An epoched file for the EEGLab data
time_stamp: int: The time stamp that is of interest if using epoched data, the row number that is of interest if using data frame
data_df: pd.core.frame.DataFrame: A data frame of EEG data if epoched data is not of interest
color_title: str (optional): The title of the color bar. Defaults to “EEG MicroVolt”.
vmin: int (optional): The minimum EEG voltage value to be shown on the color bar. Defaults to -50.
vmax: int (optional): The maximum EEG voltage value to be shown on the color bar. Defaults to 50.
colormap: str (optional): The colour scheme to use. Defaults to Bluered.

Returns:

plotly.graph_objs._figure.Figure: A topographic map in a 3D head shape

Topomap 3D Brain Module¶

simpl_eeg.topomap_3d_brain.add_timestamp_brain(stc, figure, frame_number, xpos, ypos, fontsize)¶

Adds a timestamp to a matplotlib.image.AxesImage object

Parameters:

stc: mne.source_estimate.SourceEstimate: The stc to get proper timestamps from.
figure: matplotlib.figure.Figure: The time to plot as a timestamp.
frame_number: int: The frame_number of the stc to plot as a timestamp.
xpos: float: The matplotlib x coordinate to place the timestamp.
ypos: float: The matplotlib y coordinate to place the timestamp.
fontsize:: The size to generate the font.

simpl_eeg.topomap_3d_brain.animate_matplot_brain(epoch=None, fwd='auto', stc='auto', views=['lat', 'dor', 'fro'], size=200, hemi='both', colormap='mne', colorbar=True, colormap_limit_type='lims', vmin=None, vmid=None, vmax=None, spacing='oct5', smoothing_steps=3, timestamp=True, frame_rate=12, **kwargs)¶

Creates an animated view of all timestamp observations an mne.epochs.Epochs data using a matplotlib backend. If multiple views are used then speed becomes significantly slower. Colorbar placement may be inconsistent.

Parameters:

epoch: mne.epochs.Epoch or None: MNE epochs object containing portions of raw EEG data built around specified timestamp(s). If no fwd and stc are provided a fwd will be generated from the epoch using create_fsaverage_forward(). The epoch and fwd (either provided or generated) will then be used in create_inverse_solution() to generate an stc that the brain figure will be generated from.
fwd: mne.forward.forward.Forward or ‘auto’: MNE forward object. If provided alongside an epoch they will both be used in create_fsaverage_forward() to create an stc which the brain figure will then be generated from. Defaults to ‘auto’.
stc: mne.source_estimate.SourceEstimate or ‘auto’: ‘inverse_solution’ to generate the plot from. If set to “auto” then an stc will be automatically generated from either an epoch or an epoch and a fwd, however, this will significantly slow down rendering time. Defaults to ‘auto’.
views: str or list: Specifies the ‘view’ parameter in the mne.SourceEstimate.plot() function. For any backend can be any combination of ‘lat’ (lateral), ‘med’ (medial), ‘ros’ (rostral), ‘cau’ (caudal), ‘dor’ (dorsal), ‘ven’(ventral), ‘fro’(frontal), ‘par’ (parietal). The following arguments are also accepted but are NOT compatible with the matplotlib backend ‘axi’ (axial), ‘sag’ (sagittal), and ‘cor’(coronal). Defaults to [‘lat’, ‘fro’, ‘dor’].
size: int: Size will be divided by 100 and rounded the closest inch which will then be used as the height per view. For example, entering 100 will result in 1 inch per view. If plotting multiple views overall size of the multiplot is automatically calculated to fit all views. Defaults to 200.
hemi: ‘lh’ or ‘rh’ or ‘both’ or ‘split’: Specifies the ‘initial_time’ parameter in the mne.SourceEstimate.plot() function. Can be one of ‘lh’, ‘rh’, ‘both’, or ‘split’. Defaults to ‘both’. Note that ‘split’ and ‘both’ will return a ‘split’ view since both is not avalible with a matplotlib backend. Defaults to ‘both’.
colormap: str or np.ndarray of float, shape(n_colors, 3 | 4): Specifies the ‘colormap’ parameter in the mne.SourceEstimate.plot() function. Can use a matplotlib colormap by name or take a custom look up table as input. Defaults to “mne”.
colorbar: bool: Determines whether to include a colorbar on the plot not. Defaults to True.
colormap_limit_type: str: Can be either “lims” or “pos_lims”. “lims” means that your vmin, vmid, and vmax values will specify the “Lower, middle, and upper bounds for colormap”. Using “pos_lims” will lead to vmin, vmid, and vmax representing the “Lower, middle, and upper bound for colormap. Positive values will be mirrored directly across zero during colormap construction to obtain negative control points.” Defaults to “lims”.
vmin: float: Specifies the lower value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the negative value of vmax if only that is provided.
vmid: float: Specifies the middle value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the value between vmin and vmax if one/both of them is provided.
vmax: float: Specifies the middle value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the negative value of vmin if only that is provided.
spacing: str: Specifies the ‘spacing’ parameter in the mne.SourceEstimate.plot() function. “The spacing to use for the source space. Can be ‘ico#’ for a recursively subdivided icosahedron, ‘oct#’ for a recursively subdivided octahedron. In general, you can speed up the plotting by selecting a sparser source space. Has no effect with mayavi backend. Defaults to ‘oct6’”.
smoothing_steps: int: Specifies the ‘smoothing_steps’ parameter in the mne.SourceEstimate.plot() function. “The amount of smoothing”. Defaults to 3.
timestamp: bool: Specifies whether or not to show the timestamp on the plot relative to the time in the epoch that is being shown. Defaults to True.
frame_rate: int or float: The frame rate to render the animation at. Defautls to 12.

Returns:

matplotlib.animation.FuncAnimation:: Animation containing frames from all of the avalible times in the passed in epoch.

simpl_eeg.topomap_3d_brain.calculate_cbar_dims(img_width, img_figsize, img_height)¶

Helper for plot_topomap_3d_brain when plotting multiple views and using the matplotlib backend. Calculates the colorbar width and height to be placed correctly.

Parameters:

img_width: matplotlib.figure.Figure: Number of brain images to include horizontally.
img_figsize: int: Total height/width of the image in inches (square image).
img_height: int: Number of brain images to include vertically.

Returns:

cbar_width: float: Width of colorbar in matplotlib units.
cbar_height: float: Height of colorbar in matplotlib units.

simpl_eeg.topomap_3d_brain.calculate_clim_values(vmin, vmid, vmax, colormap_limit_type)¶

Creates clim_values to be used in colorbar/figure generation

Parameters:

ax: matplotlib.axes._subplots.AxesSubplot: Matplotlib axis that will be moved to a new figure.
fig: matplotlib.figure.Figure: Matplotlib figure the axis will be moved to.

Returns:

simpl_eeg.topomap_3d_brain.convert_figure_to_image(fig, img_height, img_width)¶

Helper for animate_matplot_brain. Converts figure to image when plotting multiple views and then cuts out the empty space. This must be done when animating to preserve the figure dimensions as they otherwise get cut-off.

Parameters:

fig: matplotlib.figure.Figure: Matplotlib figure to convert to image.
img_height: int: Number of brain images to include vertically.
img_width: matplotlib.figure.Figure: Number of brain images to include horizontally.

Returns:

plot_image: numpy.ndarray: Image built from figure that will be animated.

simpl_eeg.topomap_3d_brain.create_fsaverage_forward(epoch, **kwargs)¶

A forward model is an estimation of the potential or field distribution for a known source and for a known model of the head. Returns EEG forward operator with a downloaded template MRI (fsaverage).

Parameters:

epoch: mne.epochs.Epochs: MNE epoch object containing portions of raw EEG data built around specified timestamp(s).
kwargs: arguments: Specify any of the following arguments for the mne.make_forward_solution() function. These include midist=5.0, n_jobs=1.

Returns:

mne.forward.forward.Forward:: Forward operator built from the user_input epoch and the fsaverage brain.

simpl_eeg.topomap_3d_brain.create_inverse_solution(epoch, fwd, covariance_method=['empirical', 'shrunk'], apply_inverse_method='dSPM', loose=0.2, depth=0.8, snr=3.0, pick_ori='normal')¶

Calculates the inverse solution, which is an Estimation of the unknown sources corresponding to the measured EEG or MEG.

Parameters:

epoch: mne.epochs.Epochs or mne.evoked.EvokedArray: MNE epochs or evoked object containing portions of raw EEG data built around specified timestamp(s). The inverse solution will be built based on the data in the specified epoch.
fwd: mne.forward.forward.Forward: Specifies the ‘forward’ parameter in the mne.minimum_norm.make_inverse_operator() function.
covariance_method: list: Specifies the ‘method’ parameter in the mne.compute_covariance() function.
loose: float: Specifies the ‘loose’ parameter in the mne.minimum_norm.make_inverse_operator() function.
depth: float: Specifies the ‘depth’ parameter in the mne.minimum_norm.make_inverse_operator() function.
snr: float: Used to calculate ‘lambda2’ in the equation ‘lambda2 = 1.0 / snr ** 2’.
inverse_epochs_method: str: Specifies the ‘method’ parameter in mne.minimum_norm.apply_inverse_epochs() (if using epochs) or mne.minimum_norm.apply_inverse() (if using evoked data).
pick_ori: str: Specifies the ‘pick_ori’ parameter in mne.minimum_norm.apply_inverse_epochs() (if using epochs) or mne.minimum_norm.apply_inverse() (if using evoked data).

Returns:

mne.source_estimate.SourceEstimate:: Forward operator built from the user_input epochs and the fsaverage brain.

simpl_eeg.topomap_3d_brain.create_inverse_solution_auto(stc='auto', fwd='auto', epoch=None)¶

Helper function for plot_topomap_3d_brain(). Generates an inverse solution (stc) or passes an already existing one through based on its parameters.

Parameters:

stc: mne.source_estimate.SourceEstimate or ‘auto’: ‘inverse_solution’ to generate the plot from. If set to “auto” then an stc will be automatically generated from either an epoch or an epoch and a fwd, however, this will significantly slow down rendering time. Defaults to ‘auto’.
fwd: mne.forward.forward.Forward or ‘auto’: MNE forward object. If provided alongside an epoch they will both be used in create_fsaverage_forward() to create an stc which the brain figure will then be generated from. Defaults to ‘auto’.
epoch: mne.epochs.Epoch or None: MNE epochs object containing portions of raw EEG data built around specified timestamp(s). If no fwd and stc are provided a fwd will be generated from the epoch using create_fsaverage_forward(). The epoch and fwd (either provided or generated) will then be used in create_inverse_solution() to generate an stc that the brain figure will be generated from.

Returns:

mne.source_estimate.SourceEstimate:: inverse_solution ready to be used in plot function

simpl_eeg.topomap_3d_brain.move_axes(ax, fig, copy=False)¶

Helper function for plot_topomap_3d_brain and animate_matplot_brain. Moves or copies axes from one matplotlib.figure.Figure to another.

Parameters:

ax: matplotlib.axes._subplots.AxesSubplot: Matplotlib axis that will be moved to a new figure.
fig: matplotlib.figure.Figure: Matplotlib figure the axis will be moved to.

Returns:

simpl_eeg.topomap_3d_brain.plot_topomap_3d_brain(epoch=None, fwd='auto', stc='auto', recording_number=0, backend='matplotlib', views=['lat', 'dor', 'fro'], view_layout='horizontal', size=300, hemi='both', colormap='mne', colormap_limit_type='lims', vmin=None, vmid=None, vmax=None, colorbar=True, time_viewer='auto', background='black', foreground='white', spacing='oct6', smoothing_steps=3, timestamp=True, figure=None, **kwargs)¶

Creates a still image figure of the epochs or stc data mapped to the brain using the mne.SourceEstimate.plot function. Generates when provided with 1. an stc (see create_inverse_solution) (FASTEST) 2. an epoch and acommpanying fwd (see create_fsaverage_forward) (reccomended) 3. an epoch on its own (SLOWEST). This function is written to work with either a ‘pyvista’ or ‘matplotlib’ backend. Note pyvista and mayavi backend dependencies must be installed independently of the simpl_eeg package (see topo_3d_brain in instructions for details) if you wish to use their backends.

Parameters:

epoch: mne.epochs.Epoch or None: MNE epochs object containing portions of raw EEG data built around specified timestamp(s). If no fwd and stc are provided a fwd will be generated from the epoch using create_fsaverage_forward(). The epoch and fwd (either provided or generated) will then be used in create_inverse_solution() to generate an stc that the brain figure will be generated from.
fwd: mne.forward.forward.Forward or ‘auto’: MNE forward object. If provided alongside an epoch they will both be used in create_fsaverage_forward() to create an stc which the brain figure will then be generated from. Defaults to ‘auto’.
stc: mne.source_estimate.SourceEstimate or ‘auto’: ‘inverse_solution’ to generate the plot from. If set to “auto” then an stc will be automatically generated from either an epoch or an epoch and a fwd, however, this will significantly slow down rendering time. Defaults to ‘auto’.
recording_number: int or None: Specifies the recording number in the epoch/stc to render. Defaults to 0 (the first frame).
backend: str (‘auto’ or ‘mayavi’ or ‘pyvista’ or ‘matplotlib’): Specifies the ‘initial_time’ parameter in the mne.SourceEstimate.plot() function. “If ‘auto’, tries to plot with pyvista, but resorts to matplotlib if no 3d backend is available.” Note that ‘mayavi’ has not been tested for this function. Using matplotlib as a backend will lead to some functionality breaking (look at the documentation on a function-by-function basis to know which to avoide). Note pyvista and mayavi backend dependencies must be installed independently of the simpl_eeg package (see topo_3d_brain in instructions for details) if you wish to use those backends. Defaults to ‘matplotlib’.
views: str or list: Specifies the ‘view’ parameter in the mne.SourceEstimate.plot() function. For any backend can be any combination of ‘lat’ (lateral), ‘med’ (medial), ‘ros’ (rostral), ‘cau’ (caudal), ‘dor’ (dorsal), ‘ven’(ventral), ‘fro’(frontal), ‘par’ (parietal). The following arguments are also accepted but are NOT compatible with the matplotlib backend ‘axi’ (axial), ‘sag’ (sagittal), and ‘cor’(coronal). Defaults to [‘lat’, ‘fro’, ‘dor’].
view_layout: str: Specifies the ‘view_layout’ parameter in the mne.SourceEstimate.plot() function. Should be ‘vertical’ or ‘horizontal’. Using ‘horizontal’ with hemi set to ‘split’ might cause issues. NOTE that this argument has no effect when using the ‘matplotlib’ backend. Defaults to ‘horizontal’.
size: int: If using a non-matplotlib backend then specifies how many pixels tall EACH “view” of the brian will be. If using matplotlib as a backend then the height will be divided by 100 and rounded the closest inch. For example, entering 100 will result in 1 inch per view. If plotting multiple views overall size of the multiplot is automatically calculated to fit all views. Defaults to 300.
hemi: str (‘lh’ or ‘rh’ or ‘both’ or ‘split’): Specifies the ‘initial_time’ parameter in the mne.SourceEstimate.plot() function. Can be one of ‘lh’, ‘rh’, ‘both’, or ‘split’. Defaults to ‘both’. Note that when using the matplotlib backend that ‘split’ and ‘both’ will return a ‘split’ view since both is not avalible. Defaults to ‘both’.
colormap: str or np.ndarray of float, shape(n_colors, 3 | 4): Specifies the ‘colormap’ parameter in the mne.SourceEstimate.plot() function. Can use a matplotlib colormap by name or take a custom look up table as input. Defaults to “mne” since this colormap provides a grey texture for the brain.
colormap_limit_type: str: Can be either “lims” or “pos_lims”. “lims” means that your vmin, vmid, and vmax values will specify the “Lower, middle, and upper bounds for colormap”. Using “pos_lims” will lead to vmin, vmid, and vmax representing the “Lower, middle, and upper bound for colormap. Positive values will be mirrored directly across zero during colormap construction to obtain negative control points.” Defaults to “lims”.
vmin: float: Specifies the lower value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the negative value of vmax if only that is provided.
vmid: float: Specifies the middle value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the value between vmin and vmax if one/both of them is provided.
vmax: float: Specifies the middle value of the colormap limit. If no value is specified then limits will be automatically calculated based on the mne.SourceEstimate.plot() function defaults OR will be the negative value of vmin if only that is provided.
colorbar: bool: Determines whether to include a colorbar on the plot not. Defaults to True.
time_viewer: bool or str: Specifies the ‘time_viewer’ parameter in the mne.SourceEstimate.plot() function. ‘auto’ by default. With a PyVista backend this will allow for the user to interact with the generated plot. Has no effect on figures generated with the matplotlib backend.
background: matplotlib color: Specifies the ‘background’ parameter in the mne.SourceEstimate.plot() function. Does not work with plots made with the matplotlib backend. ‘black’ by default.
foreground: matplotlib color: Specifies the ‘foreground’ parameter in the mne.SourceEstimate.plot() function. Does not work with plots made with the matplotlib backend. ‘white’ by default.
spacing: str: Specifies the ‘spacing’ parameter in the mne.SourceEstimate.plot() function. “The spacing to use for the source space. Can be ‘ico#’ for a recursively subdivided icosahedron, ‘oct#’ for a recursively subdivided octahedron. In general, you can speed up the plotting by selecting a sparser source space. Has no effect with mayavi backend. Defaults to ‘oct6’”.
smoothing_steps: int: Specifies the ‘smoothing_steps’ parameter in the mne.SourceEstimate.plot() function. “The amount of smoothing”. 3 by default.
timestamp: bool: Specifies whether or not to show the timestamp on the plot relative to the time in the epoch that is being shown. Defaults to True.
figure: instance of mayavi.core.api.Scene or instance of matplotlib.figure.Figure or list or int or None: Specifies the ‘figure’ parameter in the mne.SourceEstimate.plot() function. “If None, a new figure will be created. If multiple views or a split view is requested, this must be a list of the appropriate length. If int is provided it will be used to identify the Mayavi figure by it’s id or create a new figure with the given id. If an instance of matplotlib figure, mpl backend is used for plotting.” NOTE that if plotting multiple views OR a split/both hemi with the matplotlib backend then this argument will not work. None by default.

Returns:

matplotlib.figure.Figure or mne.viz.figure: If using ‘matplotlib’ backend (default) then returns a matplotlib.figure.Figure. If using ‘pyvista’ then returns a mne.viz.figure of brain with input epoch or stc data mapped to it.

simpl_eeg.topomap_3d_brain.save_animated_topomap_3d_brain(brain, filename, time_dilation=20, interpolation='linear', framerate=12, time_viewer=True)¶

Saves an animated mne.viz._brain._brain.Brain object as a gif using the mne.viz.Brain.save_movie() function. Saves animation of the entire figure.

Parameters:

brain: mne.viz._brain._brain.Brain: mne.viz figure of brain which will be saved as a gif.
filename: str: ‘filename’ parameter in mne.viz.Brain.save_movie() function. “Path at which to save the movie. The extension determines the format (e.g., ‘.mov’, ‘.gif’, …; see the imageio documentation for available formats)”.
time_dilation: float: ‘time_dilation’ parameter in mne.viz.Brain.save_movie() function. “Factor by which to stretch time (default 4). For example, an epoch from -100 to 600 ms lasts 700 ms. With time_dilation=4 this would result in a 2.8 s long movie”..
interpolation: str or None: ‘interpolation’ parameter in mne.viz.Brain.save_movie() function. “Interpolation method (scipy.interpolate.interp1d parameter). Must be one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, or ‘cubic’”.
time_viewer: bool: ‘time_dilation’ parameter in mne.viz.Brain.save_movie() function. “If True, include time viewer traces”.

Returns:

Connectivity Module¶

Module for reading and generating custom epochs

simpl_eeg.connectivity.animate_connectivity(epoch, calc_type='correlation', steps=20, pair_list=[], threshold=0, show_sphere=True, colormap='RdBu_r', vmin=None, vmax=None, line_width=None, title=None, colorbar=True, timestamp=True, frame_rate=12.0, **kwargs)¶

Animate 2d EEG nodes on scalp with lines representing connectivity

Args:

epochs: mne.epochs.Epochs

Epoch to visualize

calc_type: str (optional)

Connectivity calculation type. Defaults to “correlation”.

steps: int (optional)

Number of frames to use in correlation caluclation. Defaults to 20.

pair_list: [str] (optional)

List of node pairs. Defaults to [], which indicates all pairs.

threshold: int (optional)

Unsigned connectivity threshold to display connection. Defaults to 0.

show_sphere: bool (optional)

Whether to show the cartoon head or not. Defaults to True.

colormap: str (optional)

Colour scheme to use. Defaults to “RdBu_r”

vmin: int (optional)

The minimum for the scale. Defaults to None.

vmin: int (optional)

The maximum for the scale. Defaults to None.

line_width: int (optional)

The line width for the connections. Defaults to None for non-static width.

title: str (optional)

The title to display on the plot. Defaults to None for no title.

colorbar: bool (optional)

Whether to show the colorbar. Defaults to True.

timestamp: bool (optional)

Whether to show the timestamp caption. Defaults to True.

frame_rate: int or float (optional)

The frame rate to genearte the final animation with. Defaults to 12.0.

**kwargs: dict (optional)

Optional arguments to pass to mne.viz.plot_sensors()

Full list of options available at https://mne.tools/stable/generated/mne.viz.plot_sensors.html

Returns:

matplotlib.animation.Animation:: Animation of connectivity plot

simpl_eeg.connectivity.animate_connectivity_circle(epoch, calc_type='correlation', max_connections=50, steps=20, colormap='RdBu_r', vmin=None, vmax=None, line_width=1.5, title=None, colorbar=True, timestamp=True, frame_rate=12.0, **kwargs)¶

Animate connectivity circle

Args:

epoch: mne.epochs.Epochs

Epoch to visualize

calc_type: str (optional)

Connectivity calculation type. Defaults to “correlation”.

max_connections: int (optional)

Number of connections to display. Defaults to 50.

steps: int (optional)

Number of frames to use in correlation caluclation. Defaults to 20.

colormap: str (optional)

Colour scheme to use. Defaults to “RdBu_r”.

vmin: int (optional)

The minimum for the scale. Defaults to None.

vmin: int (optional)

The maximum for the scale. Defaults to None.

line_width: int (optional)

The line width for the connections. Defaults to 1.5.

title: str (optional)

The title to display on the plot. Defaults to None for no title.

colorbar: bool (optional)

Whether to display the colorbar or not. Defaults to True.

timestamp: bool (optional)

Whether to display the timestamp caption. Defaults to True.

frame_rate: int or float (optional)

The frame rate to genearte the final animation with. Defaults to 12.0.

**kwargs: dict (optional)

Optional arguments to pass to mne.viz.plot_connectivity_circle()

Full list of options available at https://mne.tools/stable/generated/mne.viz.plot_connectivity_circle.html

Returns:

matplotlib.animation.Animation:: Animation of connectivity plot

simpl_eeg.connectivity.calculate_connectivity(epoch, calc_type='correlation')¶

Calculate connectivity between nodes

Args:

epoch: mne.epochs.Epochs: Epoch to calculate connectivity for
calc_type: str (optional): Calculation type, one of spectral_connectivity, envelope_correlation, covariance, correlation. Defaults to “correlation”.

Returns:

pandas.core.frame.DataFrame:: Data frame containing connectivity values

simpl_eeg.connectivity.convert_pairs(string_pairs)¶

Convert pair names to usable format

Args:

string_pairs: str: Comma seperated node pairs in format “node1-node2”

Returns:

[tuple]:: List of tuples with node pair names

simpl_eeg.connectivity.get_axis_lims_con(epoch)¶

Generates an invisible mne.viz.plot_topomap plot and gets the ylim from its matplotlib.axes._subplots.AxesSubplot. Helper function for plot_connectivity.

Parameters:

epoch: mne.epochs.Epochs: MNE epochs object containing the timestamps.

Returns:

ax_lims: tuple: A tuple of the ax_lims.

simpl_eeg.connectivity.get_frame(epoch, step_size, frame_number)¶

Crop an epoch based on a frame number

Args:

epoch: mne.epochs.Epochs: Epoch to crop
steps_size: int: Number of time frames per step
frame_number: int: Current frame number

Returns:

mne.epochs.Epochs:: Cropped epochs for the given frame

simpl_eeg.connectivity.plot_conn_circle(epoch, fig=None, calc_type='correlation', max_connections=50, ch_names=[], colormap='RdBu_r', vmin=None, vmax=None, line_width=1.5, title=None, colorbar=True, caption=None, **kwargs)¶

Plot connectivity circle

Args:

epoch: mne.epochs.Epochs

Epoch to visualize

fig: matplotlib.pyplot.figure (optional)

Figure to plot on. Defaults to None.

calc_type: str (optional)

Connectivity calculation type. Defaults to “correlation”

max_connections: int (optional)

Maximum connections to plot. Defaults to 50.

ch_names: [str] (optional)

List of channel names to display. Defaults to [], which indicates all channels.

vmin: int (optional)

The minimum for the scale. Defaults to None.

vmin: int (optional)

The maximum for the scale. Defaults to None.

colormap: str (optional)

Colour scheme to use. Defaults to “RdBu_r”.

colormap: bool (optional)

Whether to plot the colorbar. Defaults to True.

line_width: int (optional)

The line width for the connections. Defaults to 1.5.

title: str (optional)

The title to display on the plot. Defaults to None for no title.

colorbar: bool (optional)

Whether to display the colorbar or not. Defaults to True.

caption: str (optional)

The caption to display at the bottom of the plot. Defaults to None.

**kwargs: dict (optional)

Optional arguments to pass to mne.viz.plot_connectivity_circle()

Full list of options available at https://mne.tools/stable/generated/mne.viz.plot_connectivity_circle.html

Returns:

matplotlib.pyplot.figure:: Connectivity circle figure

simpl_eeg.connectivity.plot_connectivity(epoch, fig=None, locations=None, calc_type='correlation', pair_list=[], threshold=0, show_sphere=True, readjust_sphere='auto', colormap='RdBu_r', vmin=None, vmax=None, line_width=None, title=None, colorbar=True, caption=None, **kwargs)¶

Plot 2d EEG nodes on scalp with lines representing connectivity

Args:

epoch: mne.epochs.Epochs

Epoch to visualize

fig: matplotlib.pyplot.figure (optional)

Figure to plot on. Defaults to None.

locations: [matplotlib.text.Text] (optional)

List of node locations. Defaults to None.

calc_type: str

Connectivity calculation type

pair_list: [str] (optional)

List of node pairs. Defaults to [], which indicates all pairs.

threshold: int (optional)

Unsigned connectivity threshold to display connection. Defaults to 0.

show_sphere: bool (optional)

Whether to show the cartoon head or not. Defaults to True.

readjust_sphere: bool or “auto” (optional)

Tries to re-align cartoon head but may overcorrect. Defaults to “auto”.

colormap: str (optional)

Colour scheme to use. Defaults to “RdBlu_r”.

vmin: int (optional)

The minimum for the scale. Defaults to None.

vmin: int (optional)

The maximum for the scale. Defaults to None.

line_width: int (optional)

The line width for the connections. Defaults to None for non-static width.

title: str (optional)

The title to display on the plot. Defaults to None for no title.

colorbar: bool (optional)

Whether to display the colorbar. Defaults to True.

caption: str (optional)

The caption to display at the bottom of the plot. Defaults to None.

**kwargs: dict (optional)

Optional arguments to pass to mne.viz.plot_sensors()

Full list of options available at https://mne.tools/stable/generated/mne.viz.plot_sensors.html

Returns:

matplotlib.pyplot.figure:: The generated connectivity figure

SimPL_EEG Package

API documentation¶

EEG Objects Module¶

Raw Voltage Module¶

Topomap 2D Module¶

Topomap 3D Head Module¶

Topomap 3D Brain Module¶

Connectivity Module¶