borsar.cluster.Clusters¶

class borsar.cluster.Clusters(clusters, pvals, stat, dimnames=None, dimcoords=None, info=None, src=None, subject=None, subjects_dir=None, description=None, sort_pvals=True, safety_checks=True)[source]¶

Container for results of cluster-based tests.

Parameters:

Parameters:	clusters : list of boolean ndarrays \| boolean ndarray List of boolean masks - one per cluster. The masks should match the dimensions of the stat ndarray. Each mask descirbes which elements are members of given cluster. Alternatively - one boolean array where first dimension corresponds to consevutive clusters. When no clusters were found this can be an empty numpy array, an empty list or None. pvals : list or array of float List/array of p values corresponding to consecutive clusters in clusters. If no clusters were found this can be an empty numpy array, an empty list or None. stat : ndarray Statistical map of the analysis. Usual dimensions are: space, space x time, space x frequencies, space x frequencies x time where space corresponds to channels or vertices (in the source space). dimnames : list of str, optional List of dimension names. For example [‘chan’, ‘freq’] or [‘vert’, ‘time’]. The length of dimnames has to mach stat.ndim. If ‘chan’ dimname is given, you also need to provide mne.Info corresponding to the channels via info keyword argument. If ‘vert’ dimname is given, you also need to provide forward, subject and subjects_dir via respective keyword arguments. dimcoords : list of arrays, optional List of arrays, where each array contains coordinates (labels) for consecutive elements in corresponding dimension. For example if your stat represents channels by frequencies then a) dimcoords[0] should have length of stat.shape[0] and its consecutive elements should represent channel names while b) dimcoords[1] should have length of stat.shape[1] and its consecutive elements should represent centers of frequency bins (in Hz). info : mne.Info, optional When using channel space (‘chan’ is one of the dimnames) you need to provide information about channel position in mne.Info file (for example epochs.info). src : mne.SourceSpaces, optional When using source space (‘vert’ is one of the dimnames) you need to pass mne.SourceSpaces subject : str, optional When using source space (‘vert’ is one of the dimnames) you need to pass a subject name (name of the freesurfer directory with file for given subject). subjects_dir : str, optional When using source space (‘vert’ is one of the dimnames) you need to pass a Freesurfer subjects directory (path to the folder contraining subjects as subfolders). description : str \| dict, optional Optional description of the Clusters - for example analysis parameters and some other additional details. sort_pvals : bool Whether to sort clusters by their p-value (ascending). Default: True.

clusters : list of boolean ndarrays | boolean ndarray: List of boolean masks - one per cluster. The masks should match the dimensions of the stat ndarray. Each mask descirbes which elements are members of given cluster. Alternatively - one boolean array where first dimension corresponds to consevutive clusters. When no clusters were found this can be an empty numpy array, an empty list or None.
pvals : list or array of float: List/array of p values corresponding to consecutive clusters in clusters. If no clusters were found this can be an empty numpy array, an empty list or None.
stat : ndarray: Statistical map of the analysis. Usual dimensions are: space, space x time, space x frequencies, space x frequencies x time where space corresponds to channels or vertices (in the source space).
dimnames : list of str, optional: List of dimension names. For example [‘chan’, ‘freq’] or [‘vert’, ‘time’]. The length of dimnames has to mach stat.ndim. If ‘chan’ dimname is given, you also need to provide mne.Info corresponding to the channels via info keyword argument. If ‘vert’ dimname is given, you also need to provide forward, subject and subjects_dir via respective keyword arguments.
dimcoords : list of arrays, optional: List of arrays, where each array contains coordinates (labels) for consecutive elements in corresponding dimension. For example if your stat represents channels by frequencies then a) dimcoords[0] should have length of stat.shape[0] and its consecutive elements should represent channel names while b) dimcoords[1] should have length of stat.shape[1] and its consecutive elements should represent centers of frequency bins (in Hz).
info : mne.Info, optional: When using channel space (‘chan’ is one of the dimnames) you need to provide information about channel position in mne.Info file (for example epochs.info).
src : mne.SourceSpaces, optional: When using source space (‘vert’ is one of the dimnames) you need to pass mne.SourceSpaces
subject : str, optional: When using source space (‘vert’ is one of the dimnames) you need to pass a subject name (name of the freesurfer directory with file for given subject).
subjects_dir : str, optional: When using source space (‘vert’ is one of the dimnames) you need to pass a Freesurfer subjects directory (path to the folder contraining subjects as subfolders).
description : str | dict, optional: Optional description of the Clusters - for example analysis parameters and some other additional details.
sort_pvals : bool: Whether to sort clusters by their p-value (ascending). Default: True.

Methods

`copy`()	Copy the Clusters object.
`get_cluster_limits`(cluster_idx[, …])	Find cluster limits based on percentage of cluster mass contribution to given dimensions.
`get_contribution`([cluster_idx, along, norm])	Get mass percentage contribution to given clusters along specified dimension.
`get_index`([cluster_idx, retain_mass, …])	Get indices (tuple of slices) selecting a specified range of data.
`plot`([cluster_idx, aggregate, set_light, …])	Plot cluster.
`plot_contribution`(dimname[, axis])	Plot contribution of clusters along specified dimension.
`save`(fname[, description])	Save Clusters to hdf5 file.
`select`([p_threshold, percentage_in, …])	Select clusters by p value threshold or its location in the data space.

__init__(clusters, pvals, stat, dimnames=None, dimcoords=None, info=None, src=None, subject=None, subjects_dir=None, description=None, sort_pvals=True, safety_checks=True)[source]¶: Initialize self. See help(type(self)) for accurate signature.

Methods

`__init__`(clusters, pvals, stat[, dimnames, …])	Initialize self.
`copy`()	Copy the Clusters object.
`get_cluster_limits`(cluster_idx[, …])	Find cluster limits based on percentage of cluster mass contribution to given dimensions.
`get_contribution`([cluster_idx, along, norm])	Get mass percentage contribution to given clusters along specified dimension.
`get_index`([cluster_idx, retain_mass, …])	Get indices (tuple of slices) selecting a specified range of data.
`plot`([cluster_idx, aggregate, set_light, …])	Plot cluster.
`plot_contribution`(dimname[, axis])	Plot contribution of clusters along specified dimension.
`save`(fname[, description])	Save Clusters to hdf5 file.
`select`([p_threshold, percentage_in, …])	Select clusters by p value threshold or its location in the data space.