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().

n_clusters: int, list[int], or None

An integer or list of integers representing the number of clusters used for k-means.

cluster_selection_method: str or None:

Method used to identify the optimal number of clusters.

n_cores: int or None

Number of cores specified used for multiprocessing with Joblib.

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

Run IDs specified in the analysis.

standardize: bool or None

Whether region-of-interests (ROIs)/columns were standardized during analysis.

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

Group-specific feature means if standardization was applied.

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

Group-specific feature standard deviations if standardization was applied.

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

Group-specific concatenated timeseries data.

{"GroupName": np.array(shape=[(participants x TRs), ROIs])}
kmeans: dict[str, sklearn.cluster.KMeans] or None

Group-specific k-means models.

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

Cluster centroids for each group and CAP.

{"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.

{"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.

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

Total variance explained by each group’s model.

{"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.

neurocaps.typing.ParcelApproach

Type definition representing the structure of the Schaefer, AAL, and Custom parcellation approaches.

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