PLSC#

class mne_plsc.PLSC(template, model, grouping)#

Bases: object

Container for PLSC models returned by fit_beh() and within-participants PLSC models returned by fit_within_beh().

Parameters:

  • template (Template) – A template object used for clustering and plotting.

  • model (pyplsc.PLSC) – A model that has been fit to some data.

  • grouping (str) –

    Specifies how data are stratified. Must be one of:

    • 'between'

    • 'within'

    • 'both'

    • 'neither'

add_adjacency(all_space_adjacent='auto', montage_name=None, spatial_adjacency=None)#

Add adjacency matrix for clustering.

Parameters:

  • all_space_adjacent (bool, optional) – Specifies whether all spatial locations (e.g. channels, vertices) should be treated as adjacent to each other for the purposes of clustering. This is useful when doing ERP analyses, where strong loadings at non-adjacent channels would be considered part of the same component. It can also be used to examine distributed patterns of (de)synchronization for frequency-domain analyses. The default is 'auto', which is True for ERP analysis (inferred based on template.datatype) and False for all other analyses.

  • montage_name (str, optional) – Name of montage passed to mne.channels.read_ch_adjacency. The default is None, which uses mne.channels.find_ch_adjacency to get channel adjacency.

Returns:

None. Adds an adjacency attribute to template which indicates which channels, times, and frequencies (as applicable) are adjacent for clustering.

Return type:

None.

add_source_info(src=None, mri=None, subjects_dir=None, freqs=None)#

Add information about source space for clustering and plotting.

Parameters:

  • src (mne.SourceSpaces, optional) – Source spaces corresponding to the source time courses. The default is None.

  • mri (Niimg-like object, optional) – Structural data, e.g., path to T1 scan file. The default is None.

  • subjects_dir (path-like, optional) – Freesurfer subjects directory. The default is None.

Return type:

None

bootstrap(n_boot=5000, confint_level=0.95, alignment_method='rotate-design-sals', return_boot_stat_dist=False, n_jobs=1, print_prog=True)#

Perform (stratified) bootstrap resampling to assess the reliability of the data saliences.

Parameters:

  • n_boot (int, optional) – Number of bootstrap resamples to compute. The default is 5000.

  • confint_level (float, optional) – The confidence level of the quantile-based confidence intervals to compute. The default is 0.95.

  • alignment_method (string, optional) –

    Method to be used for aligning recomputed data saliences with original data saliences. Must be one of:

    • 'rotate-design-sals' (default): Find the rotation that solves the orthogonal procrustes problem to align the recomputed and original design saliences, then apply this to the recomputed data saliences. This is the what is computed in the original Matlab version of PLS.

    • 'rotate-data-sals': Find the rotation that solves the orthogonal procrustes problem to align the recomputed and original data saliences, then apply this to the recomputed data saliences.

    • 'flip-design-sals': Find the set of sign flips that ensures the inner product of the recomputed and original design saliences are positive, then apply these sign flips to the recomputed data saliences.

    • 'flip-data-sals': Find the set of sign flips that ensures the inner product of the recomputed and original data saliences are positive, then apply these sign flips to the recomputed data saliences.

    • 'none': Perform no alignment.

  • return_boot_stat_dist (bool, optional) – If True, distribution of boot_stat from resampling is returned. This is the distribution used to compute quantile-based confidence intervals. Default is True.

  • n_jobs (int, optional) – Number of parallel jobs to deploy to compute permutations. -1 automatically deploys the maximum number of jobs. The default is 1.

  • print_prog (bool, optional) – Specifies whether to display a progress bar. Default is True.

Returns:

If return_boot_dist is true, returns the bootstrap distribution of the statistic named by model.boot_stat

Return type:

numpy.ndarray

Examples

>>> res.bootstrap(1000, n_jobs=-1)
>>> print(res.model.boot_stat_ci[..., 0]) # Print CI of boot_stat for first LV
brain_sals_to_mne(lv_idx, which='saliences')#
cluster(which='auto', threshold=None, signed='auto')#

Identify clusters of adjacent saliences above some threshold.

Parameters:

  • which (str, optional) – Specifies whether raw saliences ('saliences') or z scores ('z-scores') should be used for clustering. The default is 'auto', which uses z-scores if they are available and otherwise falls back to raw saliences.

  • threshold (float | callable, optional) – Saliences must be above this threshold to be part of a cluster. The default is None, which uses the mean salience if which='saliences' and a value of 2 if which='z-scores'.

  • signed (bool, optional) – If True, each cluster will contain only positive or only negative saliences. If False, clusters can contain both positive and negative saliences. In ERP analysis, both positive and negative saliences could be considered part of the same component. The default is 'auto', which is False for ERP analysis and True for other analyses.

Returns:

None. Adds the attribute clusters.

Return type:

None

cluster_report()#
cluster_to_stc(lv_idx, cluster_idx, which='auto', mask_val=0)#

Export cluster to source time course object.

Parameters:

  • lv_idx (int) – Latent variable index.

  • cluster_idx (int) – Cluster index.

  • which (str, optional) –

    Specifies the data to be extracted in a cluster. Must be one of:

    • 'auto': (default) z-scores if bootstrapping has been done, otherwise saliences

    • 'saliences'

    • 'z-scores'

    • 'data': data, averaged over all observations

  • mask_val (scalar, optional) – Value that should be used to mask data not in the cluster (e.g., numpy.nan). The default is 0.

Returns:

Source estimate containing data from cluster.

Return type:

mne.SourceEstimate | mne.VolSourceEstimate

get_boot_stat_frame(lv_idx=None)#

Get the statistic estimated during bootstrap resampling as a dataframe, including upper and lower confidence limits if bootstrap resampling has been done.

Parameters:

lv_idx (indexer, optional) – Index/indices of latent variable pair(s) the dataframe should cover. The default is None, which yields a dataframe covering all latent variables.

Returns:

Data frame containing statistic estimated during bootstrap resampling.

Return type:

pandas.DataFrame

get_cluster_data(lv_idx=None, cluster_idx=None)#

Extract the data for each observation in a given cluster or set of clusters as a dataframe. Note that this extracts the actual brain data rather than the brain saliences.

Parameters:

  • lv_idx (indexer, optional) – Index of the latent variable(s) for which to extract data. The default is None.

  • cluster_idx (TYPE, optional) – DESCRIPTION. The default is None.

Returns:

A data frame containing .

Return type:

pd.DataFrame

get_cluster_sizes(lv_idx, size_measure='pct-strong')#

Get sizes of clusters.

Parameters:

  • lv_idx (int) – Index of latent variable pair for which the plot should be generated.

  • size_measure (str, optional) –

    Specifies how cluster size should be measured. Must be one of:

    • 'pct-strong' (default): cluster sizes are as a percentage of the strong saliences (strong meaning above the threshold used in cluster())

    • 'pct-total': cluster sizes are as a percentage of the total number of saliences per singular vector.

    • 'absolute': cluster sizes are in absolute number of saliences.

Returns:

The sizes of each cluster, sorted from largest to smallest.

Return type:

np.ndarray

permute(n_perm=5000, store_null_dist=True, n_jobs=1, print_prog=True)#

Perform permutation testing to assess the significance of the latent variables. p values become available after running this method through the model.pvals_ attribute.

Parameters:

  • n_perm (int, optional) – Number of permutations t operform. The default is 5000.

  • store_null_dist (bool, optional) – If True, permutation samples will be saved and used for, e.g., scree plots. Default is True.

  • n_jobs (int, optional) – Number of parallel jobs to deploy to compute permutations. -1 automatically deploys the maximum number of jobs. The default is 1.

  • print_prog (bool, optional) – Specifies whether to display a progress bar. Default is True.

Return type:

None

Notes

p values are available through the model.pvals_ attribute and can also be accessed using summary().

Examples

>>> res.permute(n_perm=1000, n_jobs=-1) # Use max parallel jobs
>>> res.summary()
>>> print(res.model.pvals_)
plot_boot_stat(lv_idx, with_ci=True, ax=None)#

Visualize model.boot_stat with a barplot.

Parameters:

  • lv_idx (int) – Index of latent variable pair for which the plot should be generated.

  • with_ci (bool, optional) – Specifies whether to show confidence interval error bars, if bootstrapping has been done. Ignored if bootstrapping has not been done. Default is True.

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Returns:

Figure and axes containing plot.

Return type:

f, ax

plot_brain_sals(lv_idx, which='saliences', ax=None)#

Plot of brain saliences.

Parameters:

  • lv_idx (int) – Index of latent variable pair for which the plot should be generated.

  • which (str, optional) – Specifies whether raw saliences ('saliences') or z scores ('z-scores') should be plotted. The default is ‘saliences’.

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Returns:

Figure and axes containing plot.

Return type:

f, ax

plot_cluster(lv_idx, cluster_idx, size_measure='pct-strong', highlight='peak', plot_type='auto')#

Visualize both the spatial and non-spatial dimensions of a cluster of strong loadings.

Parameters:

  • lv_idx (int) – Index of latent variable pair of the cluster to be plotted.

  • cluster_idx (int) – Index of cluster to display.

  • size_measure (str, optional) – Specifies the size measure to use when comparing cluster sizes to min_size. See get_cluster_sizes(). The default is 'pct-strong'. Ignored if cluster_idx is specified.

  • highlight (str, optional) –

    Specifies how to represent the cluster spatially. Must be one of:

    • 'peak' (default): Plots the spatial data at the peak across the non-spatial dimensions.

    • 'extent': Plots the spatial data averaged over the cluster extent over the non-spatial dimensions.

  • plot_type (str, optional) –

    Specifies how to plot the non-spatial data. Must be one of:

    • 'auto' (default): Makes a sensible choice given the datatype provided.

    • 'butterfly': Creates a butterfly plot (coloured line plot per channel)

    • ``’’

Return type:

None

plot_cluster_nonspatial(lv_idx, cluster_idx, highlight='none', plot_type='auto', ax=None)#

SUMMARY.

Parameters:

  • lv_idx (TYPE) – DESCRIPTION.

  • cluster_idx (TYPE) – DESCRIPTION.

  • annotate (str) – What to annotate.

  • plot_type (TYPE, optional) – DESCRIPTION. The default is ‘auto’.

  • ax (TYPE, optional) – DESCRIPTION. The default is None.

Return type:

None

plot_cluster_sizes(lv_idx, size_measure='pct-strong', n_clust=None, ax=None)#

Create a plot of cluster sizes from largest to smallest.

Parameters:

  • lv_idx (int) – Index of latent variable pair for which cluster sizes should be plotted.

  • size_measure (str, optional) – Specifies how cluster size should be measured. See get_cluster_sizes(). The default is ‘pct-strong’.

  • n_clust (int, optional) – Number of clusters, starting from largest, to plot. Default is None, which displays all clusters.

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Returns:

Figure and axes containing plot.

Return type:

f, ax

plot_cluster_spatial(lv_idx, cluster_idx, highlight='peak', ax=None)#

Plot cluster across spatial dimension of data (sensors or sources).

Parameters:

  • lv_idx (int) – Index of latent variable pair.

  • cluster_idx (int) – Index of cluster.

  • highlight (str, optional) – See highlight arg to plot_clusters()

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Returns:

DESCRIPTION.

Return type:

TYPE

plot_lv(lv_idx, which='saliences', with_ci=True)#

Create a two-panel summary plot of a latent variable pair. The left panel displays the value of boot_stat while the right panel displays the brain saliences.

Parameters:

  • lv_idx (indexer) – Index of latent variable pair(s) for which the plot should be generated.

  • which (str, optional) – Specifies whether raw saliences ('saliences') or z scores ('z-scores') should be plotted in the right panel. The default is ‘saliences’.

  • with_ci (bool, optional) – Controls confidence interval plotting. See plot_boot_stat().

Returns:

Figure and axes containing plots.

Return type:

f, ax

plot_scores(lv_idx, ax=None)#

Create a scatterplot of data scores against design scores.

Parameters:

  • lv_idx (int) – Index of latent variable pair for which the plot should be generated.

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Returns:

Figure and axes containing plot.

Return type:

f, ax

plot_scree(which='pct-variance', null_percentile=95, ax=None)#

Generate a scree plot of singular values, possibly along with their null distributions.

Parameters:

  • which (str, optional) – Specifies whether the raw singular values ('singular-vals') or percent variance explained ('pct-variance') should be plotted. The default is 'pct-variance'.

  • null_dist (numpy.ndarray, optional) – Null distribution of singular values to display, as returned by model.permute(). The default is None, which plots no null distribution.

  • null_percentile (float, optional) – If provided, the null distribution of each singular value is displayed as a vertical line from the minimum to a percentile specified by this argument. The default is 95.

  • ax (instance of Matplotlib Axes, optional) – Axes to plot to. The default is None, which generates a new figure.

Notes

If which is 'pct-variance', the singular values in the null distribution are squared and divided by the sum of the squared observed singular values.

Returns:

Figure and axes containing plot.

Return type:

f, ax

save(path)#

Save a model to .xz using the LZMA algorithm. This is a thin wrapper around python’s lzma library.

Parameters:

path (str) – Path to model. If no extension is included, .xz will be added.

Return type:

None

summary()#

Summarize the model, including p values per latent variable pair if permutation has been done. See permute().

Returns:

Data frame with one row per latent variable pair.

Return type:

pandas.DataFrame

Examples

>>> res.summary()
clusters#

A list of clusters per latent variable pair.

Type:

list

grouping#

Used to specify whether data are specified by within-participants condition, between-participants condition, both, or neither.

Type:

str

model#

A PLSC model.

Type:

pyplsc.PLSC

null_dist#

Array contain null distribution of singular values. Set by permute().

Type:

numpy.ndarray

template#

A template containing storing channel positions etc. for plotting.

Type:

Template