osl_ephys.glm

Submodules

• osl_ephys.glm.glm_base
• osl_ephys.glm.glm_epochs
• osl_ephys.glm.glm_spectrum

Attributes

__doc__

Classes

GLMBaseResult	A class for GLM-Epochs fitted to MNE-Python Raw objects.
GroupGLMBaseResult	A class for group level GLM-Epochs fitted across mmultiple first-level
SensorClusterPerm	A class holding the result for sensor x frequency or sensor x time cluster stats computed
SensorMaxStatPerm	A class holding the result for sensor x frequency or sensor x time max-stat permutation test computed
SensorGLMSpectrum	A class for GLM-Spectra fitted from MNE-Python Raw objects.
GroupSensorGLMSpectrum	A class for group level GLM-Spectra fitted across mmultiple first-level
MaxStatPermuteGLMSpectrum	A class holding the result for sensor x frequency cluster stats computed
ClusterPermuteGLMSpectrum	A class holding the result for sensor x frequency cluster stats computed
GLMBaseResult	A class for GLM-Epochs fitted to MNE-Python Raw objects.
GroupGLMBaseResult	A class for group level GLM-Epochs fitted across mmultiple first-level
SensorClusterPerm	A class holding the result for sensor x frequency or sensor x time cluster stats computed
GLMEpochsResult	A class for first-level GLM-Spectra fitted to MNE-Python Epochs objects
GroupGLMEpochs	A class for group level GLM-Spectra fitted across mmultiple first-level

Functions

group_glm_spectrum_from_array(fl_data[, ...])	Compute a group GLM-Spectrum from an array of first-level spectra
group_glm_spectrum(inspectra[, design_config, ...])	Compute a group GLM-Spectrum from a set of first-level GLM-Spectra.
glm_spectrum(XX[, reg_categorical, reg_ztrans, ...])	Compute a GLM-Spectrum from a MNE-Python Raw data object.
glm_irasa(XX[, method, resample_factors, ...])	Compute a GLM-IRASA from a MNE-Python Raw data object.
read_glm_spectrum(infile)	Read in a GLMSpectrum object that has been saved as as a pickle.
plot_joint_spectrum_clusters(xvect, psd, clusters, info)	Plot a GLM-Spectrum contrast from cluster objects, with spatial line colouring and topograpies.
plot_joint_spectrum(xvect, psd, info[, ax, freqs, ...])	Plot a GLM-Spectrum contrast with spatial line colouring and topograpies.
plot_sensor_spectrum(xvect, psd, info[, ax, ...])	Plot a GLM-Spectrum contrast with spatial line colouring.
plot_sensor_proj(info[, ax, cmap])
plot_sensor_data(xvect, data, info[, ax, lw, xticks, ...])	Plot sensor data with spatial line colouring.
prep_scaled_freq(base, freq_vect)	Prepare frequency vector for plotting with a given scaling.
get_source_colors(parcellation_file[, cmap])
get_mne_sensor_cols(info)	Get sensor colours from MNE info object.
plot_channel_layout(ax, info[, size, marker])	Plot sensor layout.
plot_with_cols(ax, data, xvect[, cols, lw])	Plot data with spatial line colouring.
decorate_spectrum(ax[, ylabel])	Decorate a spectrum plot.
glm_epochs(config, epochs)	Compute a GLM-Epochs from an MNE-Python Epochs object.
group_glm_epochs(inspectra[, design_config, datainfo, ...])	Compute a group GLM-Epochs from a set of first-level GLM-Epochs.
read_mne_epochs(X[, picks])	Read in an MNE-Python Epochs object and convert it to a GLM data object.
read_glm_epochs(infile)	Read in a GLMEpochs object that has been saved as as a pickle.

Package Contents

class osl_ephys.glm.GLMBaseResult(model, design, info, data=None)

A class for GLM-Epochs fitted to MNE-Python Raw objects.

model

design

data = None

info

compute_cohens_f2(reg_ind)

Compute a Cohens F-squared effect size associated with a specific regressor.

Parameters:

reg_ind (int) – regressor of interest

Returns:

Cohen’s F-squared values

Return type:

array

save_pkl(outname, overwrite=True, save_data=False)

Save GLM-Epochs result to a pickle file.

Parameters:

• outname (str) – Filename or full file path to write pickle to

• overwrite (bool) – Overwrite previous file if one exists? (Default value = True)

• save_data (bool) – Save epoch data in pickle? This is omitted by default to save disk space (Default value = False)

class osl_ephys.glm.GroupGLMBaseResult(model, design, info, config, fl_contrast_names=None, data=None)

A class for group level GLM-Epochs fitted across mmultiple first-level GLM-Epochs computed from MNE-Python Raw objects

model

design

data = None

config

info

contrast_names

get_channel_adjacency(dist=40)

Return adjacency matrix of channels.

Parameters:

dist (float) – Distance in mm between parcel centroids to consider neighbours. Only used if data is parcellated.

Returns:

• adjacency (scipy.sparse.csr_matrix) – The adjacency matrix.

• ch_names (list of str) – The channel names.

class osl_ephys.glm.SensorClusterPerm(glmsp, gl_con, fl_con=0, nperms=1000, cluster_forming_threshold=3, tstat_args=None, metric='tstats', tmin=None, tmax=None, fmin=None, fmax=None, picks=None, nprocesses=1)

Bases: BaseSensorPerm

A class holding the result for sensor x frequency or sensor x time cluster stats computed from a group level GLM-Spectrum or GLM-Epochs

perm_data

gl_contrast_name

fl_contrast_name

info

perms

get_sig_clusters(thresh)

Return the significant clusters at a given threshold.

Parameters:

thresh (float) – The threshold to consider a cluster significant eg 95 or 99

Returns:

• clusters – A list containing the significant clusters. Each list item contains a tuple of three items - the cluster statistic, the cluster percentile relative to the null and the spatial/spectral indices of the cluster.

• obs_stat – The observed statistic.

plot_sig_clusters(thresh, ax=None, min_extent=1)

Plot the significant clusters at a given threshold.

Parameters:

• thresh (float) – The threshold to consider a cluster significant eg 95 or 99

• ax (matplotlib.axes) – Matplotlib axes to plot on. (Default value = None)

class osl_ephys.glm.SensorMaxStatPerm(glmsp, gl_con, fl_con=0, nperms=1000, tstat_args=None, metric='tstats', nprocesses=1, pooled_dims=(1, 2), tmin=None, tmax=None, fmin=None, fmax=None, picks=None)

Bases: BaseSensorPerm

A class holding the result for sensor x frequency or sensor x time max-stat permutation test computed from a group level GLM-Spectrum or GLM-Epochs

adjacency

perm_data

gl_con

fl_con = 0

gl_contrast_name

fl_contrast_name

info

perms

get_sig_clusters(thresh)

Return the significant clusters at a given threshold.

Parameters:

thresh (float) – The threshold to consider a cluster significant eg 95 or 99

Returns:

• clusters – A list containing the significant clusters. Each list item contains a tuple of three items - the cluster statistic, the cluster percentile relative to the null and the spatial/spectral indices of the cluster.

• obs_stat – The observed statistic.

plot_sig_clusters(thresh, ax=None, min_extent=1)

Plot the significant clusters at a given threshold.

Parameters:

• thresh (float) – The threshold to consider a cluster significant eg 95 or 99

• ax (matplotlib.axes) – Matplotlib axes to plot on. (Default value = None)

class osl_ephys.glm.SensorGLMSpectrum(glmsp, info)

Bases: osl_ephys.glm.glm_base.GLMBaseResult

A class for GLM-Spectra fitted from MNE-Python Raw objects.

f

config

plot_joint_spectrum(contrast=0, metric='copes', **kwargs)

Plot a GLM-Spectrum contrast with spatial line colouring and topograpies.

Parameters:

• contrast (int) – Contrast to plot (Default value = 0)

• freqs ({list, tuple or 'auto'}) – Which frequencies to plot topos for (Default value = ‘auto’)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• topo_scale ({'joint' or None}) – Whether to fix topomap colour scales across all topos (‘joint’) or leave them individual (Default value = ‘joint’)

• lw (flot) – Line width(Default value = 0.5)

• ylabel (str) – Y-axis label(Default value = ‘Power’)

• title (str) – Plot title(Default value = None)

• ylim ({tuple or list}) – min and max values for y-axis (Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

• topo_prop (float) – Proportion of plot dedicted to topomaps(Default value = 1/3)

• metric ({'copes' or 'tstats}) – Which metric to plot? (Default value = ‘copes’)

plot_sensor_spectrum(contrast=0, metric='copes', **kwargs)

Plot a GLM-Spectrum contrast with spatial line colouring.

Parameters:

• contrast (int) – Contrast to plot

• sensor_proj (bool) – Whether to plot an inset topo showing spatial colours (Default value = False)

• xticks (array_like of float) – xtick positions (Default value = None)

• xticklabels (array_like of str) – labels for xticks (Default value = None)

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• lw (flot) – Line width(Default value = 0.5)

• ylabel (str) – Y-axis label(Default value = ‘Power’)

• title (str) – Plot title(Default value = None)

• ylim ({tuple or list}) – min and max values for y-axis (Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

• topo_prop (float) – Proportion of plot dedicted to topomaps(Default value = 1/3)

• metric ({'copes' or 'tstats}) – Which metric to plot(Default value = ‘copes’)

class osl_ephys.glm.GroupSensorGLMSpectrum(model, design, config, info, fl_contrast_names=None, data=None)

Bases: osl_ephys.glm.glm_base.GroupGLMBaseResult

A class for group level GLM-Spectra fitted across mmultiple first-level GLM-Spectra computed from MNE-Python Raw objects

f

__str__()

save_pkl(outname, overwrite=True, save_data=False)

Save GLM-Spectrum result to a pickle file.

Parameters:

• outname (str) – Filename or full file path to write pickle to

• overwrite (bool) – Overwrite previous file if one exists? (Default value = True)

• save_data (bool) – Save STFT data in pickle? This is omitted by default to save disk space (Default value = False)

plot_joint_spectrum(gcontrast=0, fcontrast=0, metric='copes', **kwargs)

Plot a GLM-Spectrum contrast with spatial line colouring and topograpies.

Parameters:

• gcontrast (int) – Group level contrast to plot (Default value = 0)

• fcontrast (int) – First level contrast to plot (Default value = 0)

• freqs ({list, tuple or 'auto'}) – Which frequencies to plot topos for (Default value = ‘auto’)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• topo_scale ({'joint' or None}) – Whether to fix topomap colour scales across all topos (‘joint’) or leave them individual (Default value = ‘joint’)

• lw (flot) – Line width(Default value = 0.5)

• ylabel (str) – Y-axis label(Default value = ‘Power’)

• title (str) – Plot title(Default value = None)

• ylim ({tuple or list}) – min and max values for y-axis (Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

• topo_prop (float) – Proportion of plot dedicted to topomaps(Default value = 1/3)

• metric ({'copes' or 'tstats}) – Which metric to plot(Default value = ‘copes’)

get_fl_contrast(fl_con)

Get the data from a single first level contrast.

Parameters:

fl_con (int) – First level contrast data index to return

Returns:

ret_con – GroupSensorGLMSpectrum instance containing a single first level contrast.

Return type:

GroupSensorGLMSpectrum

class osl_ephys.glm.MaxStatPermuteGLMSpectrum(glmsp, gl_con, fl_con=0, nperms=1000, tstat_args=None, metric='tstats', nprocesses=1, pooled_dims=(1, 2), tmin=None, tmax=None, fmin=None, fmax=None, picks=None)

Bases: osl_ephys.glm.glm_base.SensorMaxStatPerm

A class holding the result for sensor x frequency cluster stats computed from a group level GLM-Spectrum

plot_sig_clusters(thresh, ax=None, base=1, min_extent=1)

Plot the significant clusters at a given threshold.

Parameters:

• thresh (float) – The threshold to consider a cluster significant eg 95 or 99

• ax (matplotlib.axes) – Matplotlib axes to plot on. (Default value = None)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

class osl_ephys.glm.ClusterPermuteGLMSpectrum(glmsp, gl_con, fl_con=0, nperms=1000, cluster_forming_threshold=3, tstat_args=None, metric='tstats', tmin=None, tmax=None, fmin=None, fmax=None, picks=None, nprocesses=1)

Bases: osl_ephys.glm.glm_base.SensorClusterPerm

A class holding the result for sensor x frequency cluster stats computed from a group level GLM-Spectrum

plot_sig_clusters(thresh, ax=None, base=1, min_extent=1)

Plot the significant clusters at a given threshold.

Parameters:

• thresh (float) – The threshold to consider a cluster significant eg 95 or 99

• ax (matplotlib.axes) – Matplotlib axes to plot on. (Default value = None)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1). (Default value = 1)

osl_ephys.glm.group_glm_spectrum_from_array(fl_data, design_config=None, datainfo=None, spectrum_config=None, info=None, fl_contrast_names=None)

Compute a group GLM-Spectrum from an array of first-level spectra

Parameters:

• fl_data (array_like) – An array containing first level power spectra with the first two dimensions being number of participants and then any first-level contrasts.

• design_config (glmtools.design.DesignConfig) – The design specification for the group level model (Default value = None)

• datainfo (dict) – Dictionary of data values to use as covariates. The length of each covariate must match the number of input GLM-Spectra (Default value = None)

• spectrum_config (sails.stft.GLMPeriodogramConfig) – Configuration of spectrum estimate

• info (mne.io.meas_info.Info) – Specification of electrophysiology data

Returns:

Group GLM results

Return type:

GroupSensorGLMSpectrum

osl_ephys.glm.group_glm_spectrum(inspectra, design_config=None, datainfo=None, metric='copes')

Compute a group GLM-Spectrum from a set of first-level GLM-Spectra.

Parameters:

• inspectra (list, tuple) – A list containing either the filepaths of a set of saved GLM-Spectra objects, or the GLM-Spectra objects themselves.

• design_config (glmtools.design.DesignConfig) – The design specification for the group level model (Default value = None)

• datainfo (dict) – Dictionary of data values to use as covariates. The length of each covariate must match the number of input GLM-Spectra (Default value = None)

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

Returns:

GroupSensorGLMSpectrum instance containing the group level GLM-Spectrum.

Return type:

GroupSensorGLMSpectrum

References

[1]

Quinn, A. J., Atkinson, L., Gohil, C., Kohl, O., Pitt, J., Zich, C., Nobre, A. C., & Woolrich, M. W. (2022). The GLM-Spectrum: A multilevel framework for spectrum analysis with covariate and confound modelling. Cold Spring Harbor Laboratory. https://doi.org/10.1101/2022.11.14.516449

osl_ephys.glm.glm_spectrum(XX, reg_categorical=None, reg_ztrans=None, reg_unitmax=None, contrasts=None, fit_intercept=True, standardise_data=False, window_type='hann', nperseg=None, noverlap=None, nfft=None, detrend='constant', return_onesided=True, scaling='density', mode='psd', fmin=None, fmax=None, axis=-1, fs=1, verbose='WARNING')

Compute a GLM-Spectrum from a MNE-Python Raw data object.

Parameters:

• XX ({MNE Raw object, or data array}) – Data to compute GLM-Spectrum from

• standardise_data (bool) – Flag indicating whether to z-transform input data (Default value = False)

• reg_categorical (dict or None) – Dictionary of covariate time series to be added as binary regessors. (Default value = None)

• reg_ztrans (dict or None) – Dictionary of covariate time series to be added as z-standardised regessors. (Default value = None)

• reg_unitmax (dict or None) – Dictionary of confound time series to be added as positive-valued unitmax regessors. (Default value = None)

• contrasts (dict or None) – Dictionary of contrasts to be computed in the model. (Default value = None, will add a simple contrast for each regressor)

• fit_intercept (bool) – Specifies whether a constant valued ‘intercept’ regressor is included in the model. (Default value = True)’

• nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.

• noverlap (int) – Number of samples that successive sliding windows should overlap.

• window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.

• detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’

• nfft (int) – Length of the FFT to use (Default value = 256)

• axis (int) – Axis of input array along which the computation is performed. (Default value = -1)

• return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.

• mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)

• scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’

• fs (float) – Sampling rate of the data

• fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)

• fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’

• verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

SensorGLMSpectrum instance containing the fitted GLM-Spectrum.

Return type:

SensorGLMSpectrum

References

[1]

Quinn, A. J., Atkinson, L., Gohil, C., Kohl, O., Pitt, J., Zich, C., Nobre, A. C., & Woolrich, M. W. (2022). The GLM-Spectrum: A multilevel framework for spectrum analysis with covariate and confound modelling. Cold Spring Harbor Laboratory. https://doi.org/10.1101/2022.11.14.516449

osl_ephys.glm.glm_irasa(XX, method='modified', resample_factors=None, aperiodic_average='median', reg_categorical=None, reg_ztrans=None, reg_unitmax=None, contrasts=None, fit_intercept=True, standardise_data=False, window_type='hann', nperseg=None, noverlap=None, nfft=None, detrend='constant', return_onesided=True, scaling='density', mode='psd', fmin=None, fmax=None, axis=-1, fs=1, verbose='WARNING')

Compute a GLM-IRASA from a MNE-Python Raw data object.

Parameters:

• XX ({MNE Raw object, or data array}) – Data to compute GLM-Spectrum from

• standardise_data (bool) – Flag indicating whether to z-transform input data (Default value = False)

• reg_categorical (dict or None) – Dictionary of covariate time series to be added as binary regessors. (Default value = None)

• reg_ztrans (dict or None) – Dictionary of covariate time series to be added as z-standardised regessors. (Default value = None)

• reg_unitmax (dict or None) – Dictionary of confound time series to be added as positive-valued unitmax regessors. (Default value = None)

• contrasts (dict or None) – Dictionary of contrasts to be computed in the model. (Default value = None, will add a simple contrast for each regressor)

• fit_intercept (bool) – Specifies whether a constant valued ‘intercept’ regressor is included in the model. (Default value = True)’

• method ({'original', 'modified'}) – whether to compute the original implementation of IRASA or the modified update (default is ‘modified’)

• resample_factors ({None, array_like}) – array of resampling factors to average across or None, in which a set of factors are automatically computed (default is None).

• aperiodic_average ({'mean', 'median', 'median_bias', 'min'}) – method for averaging across irregularly resampled spectra to estimate the aperiodic component (default is ‘median’).’

• nperseg (int) – Length of each segment. Defaults to None, but if window is str or tuple, is set to 256, and if window is array_like, is set to the length of the window.

• noverlap (int) – Number of samples that successive sliding windows should overlap.

• window_type (str or tuple or array_like, optional) – Desired window to use. If window is a string or tuple, it is passed to scipy.signal.windows.get_window to generate the window values, which are DFT-even by default. See scipy.signal.windows for a list of windows and required parameters. If window is array_like it will be used directly as the window and its length must be nperseg. Defaults to a Hann window.

• detrend (str or function or False, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to the detrend function. If it is a function, it takes a segment and returns a detrended segment. If detrend is False, no detrending is done. Defaults to ‘constant’.’

• nfft (int) – Length of the FFT to use (Default value = 256)

• axis (int) – Axis of input array along which the computation is performed. (Default value = -1)

• return_onesided (bool, optional) – If True, return a one-sided spectrum for real data. If False return a two-sided spectrum. Defaults to True, but for complex data, a two-sided spectrum is always returned.

• mode ({'psd', 'magnitude', 'angle', 'phase', 'complex'}) – Which type of spectrum to return (Default value = ‘psd’)

• scaling ({ 'density', 'spectrum' }) – Selects between computing the power spectral density (‘density’) where Pxx has units of V**2/Hz and computing the power spectrum (‘spectrum’) where Pxx has units of V**2, if x is measured in V and fs is measured in Hz. Defaults to ‘density’

• fs (float) – Sampling rate of the data

• fmin ({float, None}) – Smallest frequency in desired range (left hand boundary)

• fmax ({float, None}) – Largest frequency in desired range (right hand boundary)’

• verbose ({None, 'DEBUG', 'INFO', 'WARNING', 'CRITICAL'}) – String indicating the level of detail to be printed to the screen during computation.’

Returns:

SensorGLMSpectrum instance containing the fitted GLM-Spectrum.

Return type:

SensorGLMSpectrum

References

[1]

Quinn, A. J., Atkinson, L., Gohil, C., Kohl, O., Pitt, J., Zich, C., Nobre, A. C., & Woolrich, M. W. (2022). The GLM-Spectrum: A multilevel framework for spectrum analysis with covariate and confound modelling. Cold Spring Harbor Laboratory. https://doi.org/10.1101/2022.11.14.516449

osl_ephys.glm.read_glm_spectrum(infile)

Read in a GLMSpectrum object that has been saved as as a pickle.

Parameters:

infile (str) – Filepath of saved object

Returns:

glmsp – SensorGLMSpectrum instance containing the fitted GLM-Spectrum.

Return type:

SensorGLMSpectrum

osl_ephys.glm.plot_joint_spectrum_clusters(xvect, psd, clusters, info, ax=None, freqs='auto', base=1, topo_scale='joint', lw=0.5, ylabel='Power', title='', ylim=None, xtick_skip=1, topo_prop=1 / 5, topo_cmap=None, topomap_args=None)

Plot a GLM-Spectrum contrast from cluster objects, with spatial line colouring and topograpies.

Parameters:

• xvect (array_like) – Frequency vector

• psd (array_like) – Spectrum values

• clusters (list) – List of cluster objects

• info (dict) – MNE-Python info object

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• freqs ({list, tuple or 'auto'}) – Which frequencies to plot topos for (Default value = ‘auto’)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• topo_scale ({'joint' or None}) – Whether to fix topomap colour scales across all topos (‘joint’) or leave them individual (Default value = ‘joint’)

• lw (float) – Line width(Default value = 0.5)

• ylabel (str) – Y-axis label(Default value = ‘Power’)

• title (str) – Plot title(Default value = None)

• ylim ({tuple or list}) – min and max values for y-axis (Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

• topo_prop (float) – Proportion of plot dedicted to topomaps(Default value = 1/3)

• topo_cmap ({None or matplotlib colormap}) – Colormap to use for plotting (Default is ‘RdBu_r’ if pooled topo data range is positive and negative, otherwise ‘Reds’ or ‘Blues’ depending on sign of pooled data range)

osl_ephys.glm.plot_joint_spectrum(xvect, psd, info, ax=None, freqs='auto', base=1, topo_scale='joint', lw=0.5, ylabel='Power', title='', ylim=None, xtick_skip=1, topo_prop=1 / 5, topo_cmap=None, topomap_args=None)

Plot a GLM-Spectrum contrast with spatial line colouring and topograpies.

Parameters:

• xvect (array_like) – Vector of frequency values for x-axis

• psd (array_like) – Array of spectrum values to plot

• info (mne.Info) – MNE-Python info object

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• freqs ({list, tuple or 'auto'}) – Which frequencies to plot topos for (Default value = ‘auto’)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• topo_scale ({'joint' or None}) – Whether to fix topomap colour scales across all topos (‘joint’) or leave them individual (Default value = ‘joint’)

• lw (flot) – Line width(Default value = 0.5)

• ylabel (str) – Y-axis label(Default value = ‘Power’)

• title (str) – Plot title(Default value = None)

• ylim ({tuple or list}) – min and max values for y-axis (Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

• topo_prop (float) – Proportion of plot dedicted to topomaps(Default value = 1/3)

• topo_cmap ({None or matplotlib colormap}) – Colormap to use for plotting (Default value is ‘RdBu_r’ if pooled topo data range is positive and negative, otherwise ‘Reds’ or ‘Blues’ depending on sign of pooled data range)

osl_ephys.glm.plot_sensor_spectrum(xvect, psd, info, ax=None, sensor_proj=False, xticks=None, xticklabels=None, lw=0.5, title=None, sensor_cols=True, base=1, ylabel=None, xtick_skip=1)

Plot a GLM-Spectrum contrast with spatial line colouring.

Parameters:

• xvect (array_like) – Vector of frequency values for x-axis

• psd (array_like) – Array of spectrum values to plot

• info (MNE Raw info) – Sensor info for spatial map

• ax ({None or axis handle}) – Axis to plot into (Default value = None)

• sensor_proj (bool) – Whether to plot a topomap inset (Default value = False)

• xticks (array_like) – xtick positions (Default value = None)

• xticklabels (array_like of str) – xtick labels (Default value = None)

• lw (flot) – Line width(Default value = 0.5)

• title (str) – Plot title(Default value = None)

• sensor_cols (bool) – Whether to colour lines by sensor (Default value = True)

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• ylabel (str) – Y-axis label(Default value = None)

• xtick_skip (int) – Number of xaxis ticks to skip, useful for tight plots (Default value = 1)

osl_ephys.glm.plot_sensor_proj(info, ax=None, cmap=None)

osl_ephys.glm.plot_sensor_data(xvect, data, info, ax=None, lw=0.5, xticks=None, xticklabels=None, sensor_cols=True, base=1, xtick_skip=1)

Plot sensor data with spatial line colouring.

osl_ephys.glm.prep_scaled_freq(base, freq_vect)

Prepare frequency vector for plotting with a given scaling.

Parameters:

• base (float) – The x-axis scaling, set to 0.5 for sqrt freq axis (Default value = 1)

• freq_vect (array_like) – Vector of frequency values for x-axis

Returns:

• fx (array_like) – Scaled frequency vector

• ftick (array_like) – Normal frequency ticks

• ftickscaled (array_like) – Scaled frequency ticks

Notes

Assuming ephy freq ranges for now - around 1-40Hz

osl_ephys.glm.get_source_colors(parcellation_file, cmap='viridis')

osl_ephys.glm.get_mne_sensor_cols(info)

Get sensor colours from MNE info object.

Parameters:

info (mne.Info) – MNE-Python info object

Returns:

• colors (array_like) – Array of RGB values for each sensor

• pos (array_like) – Sensor positions

• outlines (array_like) – Sensor outlines

osl_ephys.glm.plot_channel_layout(ax, info, size=30, marker='o')

Plot sensor layout.

Parameters:

• ax (matplotlib.axes) – Axis to plot into

• info (mne.Info) – MNE-Python info object

• size (int) – Size of sensor § (Default value = 30)

• marker (str) – Marker type (Default value = ‘o’)

osl_ephys.glm.plot_with_cols(ax, data, xvect, cols=None, lw=0.5)

Plot data with spatial line colouring.

Parameters:

• ax (matplotlib.axes) – Axis to plot into

• data (array_like) – Data to plot

• xvect (array_like) – Vector of frequency values for x-axis

• cols (array_like) – Array of RGB values for each sensor (Default value = None)

• lw (flot) – Line width(Default value = 0.5)

osl_ephys.glm.decorate_spectrum(ax, ylabel='Power')

Decorate a spectrum plot.

Parameters:

• ax (matplotlib.axes) – Axis to plot into

• ylabel (str) – Y-axis label(Default value = ‘Power’)

class osl_ephys.glm.GLMBaseResult(model, design, info, data=None)

A class for GLM-Epochs fitted to MNE-Python Raw objects.

model

design

data = None

info

compute_cohens_f2(reg_ind)

Compute a Cohens F-squared effect size associated with a specific regressor.

Parameters:

reg_ind (int) – regressor of interest

Returns:

Cohen’s F-squared values

Return type:

array

save_pkl(outname, overwrite=True, save_data=False)

Save GLM-Epochs result to a pickle file.

Parameters:

• outname (str) – Filename or full file path to write pickle to

• overwrite (bool) – Overwrite previous file if one exists? (Default value = True)

• save_data (bool) – Save epoch data in pickle? This is omitted by default to save disk space (Default value = False)

class osl_ephys.glm.GroupGLMBaseResult(model, design, info, config, fl_contrast_names=None, data=None)

A class for group level GLM-Epochs fitted across mmultiple first-level GLM-Epochs computed from MNE-Python Raw objects

model

design

data = None

config

info

contrast_names

get_channel_adjacency(dist=40)

Return adjacency matrix of channels.

Parameters:

dist (float) – Distance in mm between parcel centroids to consider neighbours. Only used if data is parcellated.

Returns:

• adjacency (scipy.sparse.csr_matrix) – The adjacency matrix.

• ch_names (list of str) – The channel names.

class osl_ephys.glm.SensorClusterPerm(glmsp, gl_con, fl_con=0, nperms=1000, cluster_forming_threshold=3, tstat_args=None, metric='tstats', tmin=None, tmax=None, fmin=None, fmax=None, picks=None, nprocesses=1)

Bases: BaseSensorPerm

A class holding the result for sensor x frequency or sensor x time cluster stats computed from a group level GLM-Spectrum or GLM-Epochs

perm_data

gl_contrast_name

fl_contrast_name

info

perms

get_sig_clusters(thresh)

Return the significant clusters at a given threshold.

Parameters:

thresh (float) – The threshold to consider a cluster significant eg 95 or 99

Returns:

• clusters – A list containing the significant clusters. Each list item contains a tuple of three items - the cluster statistic, the cluster percentile relative to the null and the spatial/spectral indices of the cluster.

• obs_stat – The observed statistic.

plot_sig_clusters(thresh, ax=None, min_extent=1)

Plot the significant clusters at a given threshold.

Parameters:

• thresh (float) – The threshold to consider a cluster significant eg 95 or 99

• ax (matplotlib.axes) – Matplotlib axes to plot on. (Default value = None)

class osl_ephys.glm.GLMEpochsResult(model, design, info, tmin=0, data=None, times=None)

Bases: osl_ephys.glm.glm_base.GLMBaseResult

A class for first-level GLM-Spectra fitted to MNE-Python Epochs objects

tmin = 0

times = None

save_pkl(outname, overwrite=True, save_data=False)

Save GLM-Epochs result to a pickle file.

Parameters:

• outname (str) – Filename or full file path to write pickle to

• overwrite (bool) – Overwrite previous file if one exists? (Default value = True)

• save_data (bool) – Save epochs data in pickle? This is omitted by default to save disk space (Default value = False)

get_evoked_contrast(contrast=0, metric='copes')

Get the evoked response for a given contrast.

Parameters:

• contrast (int) – Contrast index to return

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

Returns:

The evoked response for the contrast.

Return type:

mne.Evoked

plot_joint_contrast(contrast=0, metric='copes', title=None)

Plot the evoked response for a given contrast.

Parameters:

• contrast (int) – Contrast index to return

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

• title (str) – Title for the plot

class osl_ephys.glm.GroupGLMEpochs(model, design, info, config, fl_contrast_names=None, data=None, tmin=0, times=None)

Bases: osl_ephys.glm.glm_base.GroupGLMBaseResult

A class for group level GLM-Spectra fitted across mmultiple first-level GLM-Spectra computed from MNE-Python Raw objects

tmin = 0

times = None

get_evoked_contrast(gcontrast=0, fcontrast=0, metric='copes')

Get the evoked response for a given contrast.

Parameters:

• contrast (int) – Contrast index to return

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

Returns:

The evoked response for the contrast.

Return type:

mne.Evoked

plot_joint_contrast(gcontrast=0, fcontrast=0, metric='copes', title=None, joint_args=None)

Plot the evoked response for a given contrast.

Parameters:

• contrast (int) – Contrast index to return

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

• title (str) – Title for the plot

get_fl_contrast(fl_con)

Get the data from a single first level contrast.

Parameters:

fl_con (int) – First level contrast data index to return

Return type:

GLMEpochsResult instance containing a single first level contrast.

save_pkl(outname, overwrite=True, save_data=False)

Save GLM-Epochs result to a pickle file.

Parameters:

• outname (str) – Filename or full file path to write pickle to

• overwrite (bool) – Overwrite previous file if one exists? (Default value = True)

• save_data (bool) – Save epochs data in pickle? This is omitted by default to save disk space (Default value = False)

osl_ephys.glm.glm_epochs(config, epochs)

Compute a GLM-Epochs from an MNE-Python Epochs object.

Parameters:

• config (glmtools.design.DesignConfig) – The design specification for the model

• epochs (str, mne.Epochs) – The epochs object to use for the model

Return type:

GLMEpochsResult

osl_ephys.glm.group_glm_epochs(inspectra, design_config=None, datainfo=None, metric='copes', baseline=None)

Compute a group GLM-Epochs from a set of first-level GLM-Epochs.

Parameters:

• inspectra (list, tuple) – A list containing either the filepaths of a set of saved GLM-Epochs objects, or the GLM-Epochs objects themselves.

• design_config (glmtools.design.DesignConfig) – The design specification for the group level model (Default value = None)

• datainfo (dict) – Dictionary of data values to use as covariates. The length of each covariate must match the number of input GLM-Epochs (Default value = None)

• metric ({'copes', or 'tsats'}) – Which metric to plot (Default value = ‘copes’)

Return type:

GroupGLMEpochs

osl_ephys.glm.read_mne_epochs(X, picks=None)

Read in an MNE-Python Epochs object and convert it to a GLM data object.

Parameters:

• X (str, mne.Epochs) – The epochs object to use for the model

• picks (list) – List of channels to use for the model (Default value = None)

Returns:

The data object used to fit the model.

Return type:

glmtools.data.TrialGLMData

osl_ephys.glm.read_glm_epochs(infile)

Read in a GLMEpochs object that has been saved as as a pickle.

Parameters:

infile (str) – Filepath of saved object

Return type:

GLMEpochsResult

osl_ephys.glm.__doc__