CAP#

class neurocaps.analysis.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. If None, on the first call of self.get_caps(), “All Subjects” will be set as the default group name and be populated with the subject IDs in subject_timeseries. Groups remain fixed for the entire instance of the class.

Properties#

parcel_approach: ParcelApproach

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

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. Derived from self.groups each time self.get_caps() is ran. While this property can be modified using its setter, any changes will be overwritten based on self.groups on the subsequent call to 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])}}

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

`__str__`	Print Current Object State.
`calculate_metrics`	Compute Participant-wise CAP Metrics.
`caps2corr`	Generate Pearson Correlation Matrix for CAPs.
`caps2niftis`	Convert CAPs to NifTI Statistical Maps.
`caps2plot`	Generate Heatmaps and Outer Product Plots for CAPs.
`caps2radar`	Generate Radar Plots for CAPs using Cosine Similarity.
`caps2surf`	Project CAPs onto Surface Plots.
`get_caps`	Perform K-Means Clustering to Identify CAPs.