neurocaps.analysis.CAP#

class CAP(parcel_approach=None, groups=None)[source]#

Co-Activation Patterns (CAPs) Class.

Performs k-means clustering for CAP identification, computes temporal dynamics metrics, and provides visualization tools for analyzing brain activation patterns.

Parameters:

  • parcel_approach (ParcelConfig, ParcelApproach, or str, default=None) – Specifies the parcellation approach to use. Options are “Schaefer”, “AAL”, or “Custom”. Can be initialized with parameters, as a nested dictionary, or loaded from a pickle file. For detailed documentation on the expected structure, see the type definitions for ParcelConfig and ParcelApproach in the “See Also” section.

  • groups (dict[str, list[str]] or None, default=None) – Optional mapping of group names to lists of subject IDs for group-specific analyses.

Properties#

parcel_approach: ParcelApproach

Parcellation information with “maps” (path to parcellation file), “nodes” (labels), and “regions” (anatomical regions or networks).

groups: dict[str, list[str]] or None:

Mapping of groups names to lists of subject IDs.

subject_table: dict[str, str] or None

Lookup table mapping subject IDs to their groups. Defined after running self.get_caps(). Defined after running self.get_caps().

n_clusters: int, list[int], or None

An integer or list of integers representing the number of clusters used for k-means. Defined after running self.get_caps().

cluster_selection_method: str or None:

Method used to identify the optimal number of clusters. Defined after running self.get_caps().

n_cores: int or None

Number of cores specified used for multiprocessing with Joblib. Defined after running self.get_caps().

runs: int, list[int | str], or None

Run IDs specified in the analysis. Defined after running self.get_caps().

standardize: bool or None

Whether region-of-interests (ROIs)/columns were standardized during analysis. Defined after running self.get_caps().

means: dict[str, np.array] or None

Group-specific feature means if standardization was applied. Defined after running self.get_caps().

{"GroupName": np.array(shape=[1, ROIs])}
stdev: dict[str, np.array] or None

Group-specific feature standard deviations if standardization was applied. Defined after running self.get_caps().

{"GroupName": np.array(shape=[1, ROIs])}

Note

Standard deviations below np.finfo(std.dtype).eps are replaced with 1 for numerical stability.

concatenated_timeseries: dict[str, np.array] or None

Group-specific concatenated timeseries data. Can be deleted using del self.concatenated_timeseries. Defined after running self.get_caps().

{"GroupName": np.array(shape=[(participants x TRs), ROIs])}

Note

For versions >= 0.25.0, subject IDs are sorted lexicographically prior to concatenation and the order is determined by self.groups.

kmeans: dict[str, sklearn.cluster.KMeans] or None

Group-specific k-means models. Defined after running self.get_caps().

{"GroupName": sklearn.cluster.KMeans}
caps: dict[str, dict[str, np.array]] or None

Cluster centroids for each group and CAP. Defined after running self.get_caps().

{"GroupName": {"CAP-1": np.array(shape=[1, ROIs]), "CAP-2": np.array(shape=[1, ROIs])}}
cluster_scores: dict[str, str | dict[str, float]] or None

Scores for different cluster sizes by group. Defined after running self.get_caps().

{"Cluster_Selection_Method": str, "Scores": {"GroupName": {2: float, 3: float}}}
optimal_n_clusters: dict[str, int] or None

Optimal number of clusters by group if cluster selection was used. Defined after running self.get_caps().

{"GroupName": int}
variance_explained: dict[str, float] or None

Total variance explained by each group’s model. Defined after running self.get_caps().

{"GroupName": float}
region_means: dict[str, dict[str, list[str] | np.array]] or None

Region-averaged values used for visualization. Defined after running self.caps2plot().

{"GroupName": {"Regions": [...], "CAP-1": np.array(shape=[1, Regions]), "CAP-2": np.array(shape=[1, Regions])}}

Changed in version 0.23.4: Replaces region_caps and adds the “Regions” key for each group. For backwards compatibility, region_caps, which doesn’t include the “Regions” key is still available.

outer_products: dict[str, dict[str, np.array]] or None

Outer product matrices for visualization. Defined after running self.caps2plot().

{"GroupName": {"CAP-1": np.array(shape=[ROIs, ROIs]), "CAP-2": np.array(shape=[ROIs, ROIs])}}
cosine_similarity: dict[str, dict[str, list[str] | np.array]] or None

Cosine similarities between CAPs and the regions specified in parcel_approach. Defined after running self.caps2radar().

{"GroupName": {"Regions": [...], "CAP-1": {"High Amplitude": np.array(shape=[1, Regions]), "Low Amplitude": np.array(shape=[1, Regions])}}

See also

neurocaps.typing.ParcelConfig

Type definition representing the configuration options and structure for the Schaefer and AAL parcellations. Refer to ParcelConfig documentation.

neurocaps.typing.ParcelApproach

Type definition representing the structure of the Schaefer, AAL, and Custom parcellation approaches. Refer to ParcelApproach documentation.

Important

Data/Property Persistence: Each time certain functions are called, properties related to that function are automatically initialized/overwritten to create a clean state for the subsequent analysis. For instance, when self.get_caps() is ran, then properties such as self.caps, self.kmeans, self.concatenated_timeseries, self.stdev, etc are automatically re-initialized to store the new results. The same occurs for self.cosine_similarity, when self.caps2radar() is ran and for other properties and their associated functions.

Note

Default Group Name: The default group name is “All Subjects” when no groups are specified.

Custom Parcellations: Refer to the NeuroCAPs’ Parcellation Documentation for detailed explanations and example structures for Custom parcellations.

Methods

calculate_metrics(subject_timeseries[, tr, ...])

Compute Participant-wise CAP Metrics.

caps2corr([output_dir, suffix_title, ...])

Generate Pearson Correlation Matrix for CAPs.

caps2niftis(output_dir[, suffix_filename, ...])

Convert CAPs to NifTI Statistical Maps.

caps2plot([output_dir, suffix_title, ...])

Generate Heatmaps and Outer Product Plots for CAPs.

caps2radar([output_dir, suffix_title, ...])

Generate Radar Plots for CAPs using Cosine Similarity.

caps2surf([output_dir, suffix_title, ...])

Project CAPs onto Surface Plots.

get_caps(subject_timeseries[, runs, ...])

Perform K-Means Clustering to Identify CAPs.
On this page