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.

Important

Parcellation maps are expected to be in a standard MNI space. This is due to the CAP.caps2surf assuming that the parcellation map is in MNI standard space when transforming data between volumetric and surface spaces.

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 serialized file (i.e. pickle, joblib, json). For detailed documentation on the expected structure, see the type definitions for ParcelConfig and ParcelApproach in the “See Also” section.

Important

The default “regions” names for “AAL” was changed in versions >=0.31.0, which will group nodes differently.
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 unless self.clear_groups() is used.

Properties#

parcel_approachParcelApproach

Parcellation information with “maps” (path to parcellation file), “nodes” (labels), and “regions” (anatomical regions or networks). This property is also settable (accepts a dictionary or pickle file). Returns a deep copy.

groupsdict[str, list[str]] or None:

Mapping of groups names to lists of subject IDs. Returns a deep copy.

subject_tabledict[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(). Returns a deep copy.

n_clustersint, 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_methodstr or None:

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

n_coresint or None

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

runsint, list[int | str], or None

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

standardizebool or None

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

meansdict[str, np.array] or None

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

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

stdevdict[str, np.array] or None

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

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

Note

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

concatenated_timeseriesdict[str, np.array] or None

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

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

kmeansdict[str, sklearn.cluster.KMeans] or None

Group-specific k-means models. Defined after running self.get_caps(). Returns a deep copy.

{"GroupName": sklearn.cluster.KMeans}

capsdict[str, dict[str, np.array]] or None

Cluster centroids for each group and CAP. Defined after running self.get_caps(). Returns a deep copy.

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

cluster_scoresdict[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_clustersdict[str, int] or None

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

{"GroupName": int}

variance_explaineddict[str, float] or None

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

{"GroupName": float}

region_meansdict[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]), ...)}}

outer_productsdict[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]), ...}}

cosine_similaritydict[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]),
        }
    }
}

Note

“High Amplitude” indicate alignment to activations (> 0) in a CAP and “Low Amplitude” indicate alignment to the deactivations (< 0) in a CAP.

See also

neurocaps.typing.ParcelConfig: Type definition representing the configuration options and structure for the Schaefer and AAL parcellations. (See ParcelConfig Documentation)
neurocaps.typing.ParcelApproach: Type definition representing the structure of the Schaefer, AAL, and Custom parcellation approaches. (See 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`	Calculate Participant-wise CAP Metrics.
`caps2corr`	Generate a 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.
`clear_groups`	Clears the `groups` property.
`get_caps`	Perform K-Means Clustering to Identify CAPs.
`return_cap_labels`	Return CAP Labels for Each Subject.