CAP.caps2radar#

CAP.caps2radar(use_scatterpolar=False, output_dir=None, plot_output_format='png', suffix_filename=None, suffix_title=None, show_figs=True, **kwargs)[source]#

Generate Radar Plots for CAPs using Cosine Similarity.

Calculates the cosine similarity between the “High Amplitude” (positive/above the mean) and “Low Amplitude” (negative/below the mean) activations of the CAP and each a-priori region or network in the parcellation defined by parcel_approach (e.g. DMN, Vis, etc). One radar plot is generated per CAP and separate images are generated for each group.

Important

  • This function assumes the mean for each ROI is 0 due to standardization.

  • The absolute values of the negative activations are computed for visualization purposes.

Parameters:

  • use_scatterpolar (bool, default=False) – Uses plotly.graph_objects.Scatterpolar instead of plotly.express.line_polar.

  • output_dir (str or None, default=None) – Directory to save plots as png or html images. The directory will be created if it does not exist. If None, plots will not be saved.

  • plot_output_format (str, default=”png”) –

    The format to save plots in when output_dir is specified. Options are “png”, “html”, or “json” (which can be further modified).

    Changed in version 0.33.0: Replaces as_html and as_json and accepts a string value.

  • suffix_filename (str or None, default=None) – Appended to the filename of each saved plot if output_dir is provided.

  • suffix_title (str or None, default=None) – Appended to the title of each plot.

  • show_figs (bool, default=True) – Display figures. If the current Python session is non-interactive, then plotly.offline is used to generate an html file named “temp-plot.html”, which opens each plot in the default browser.

  • **kwargs – Additional keyword arguments for customizing plots. See neurocaps.utils.PlotDefaults.caps2radar() for all available options and their default values (See PlotDefaults Documentation for caps2radar)

Returns:

self

Note

Interpretation: Each radar plot provides a high-level representation of CAP by computing and visualizing how closely each CAP’s positive (“High Amplitude”) and negative (“Low Amplitude”) patterns aligns large-scale, canonical networks or regions.

For each radar plot, two traces are shown:

  • “High Amplitude”: Spatial alignment with the positively activating nodes in a CAP. Traces indicate a given region is active during that CAP.

  • “Low Amplitude”: Spatial alignment with deactivating nodes in a CAP. Traces indicate that a given region is suppressed during that CAP.

This provides a quantitative method to label CAPs based on the dominant active and suppressed networks or regions. For instance, if the dorsal attention network (DAN) has the highest (largest trace) “High Amplitude” cosine similarity value and the ventral attention network (VAN) has a highest “Low Amplitude” cosine similarity value, then that CAP can be described as (DAN +/VAN -). Or if the highest “High Amplitude” cosine similarity value is assoiciated with the default mode network (DMN), while the highest “Low Amplitude” cosine similarity values are associates with the DAN and the frontoparietal network (FPN), then the CAP can represent a classic task-negative pattern. Note, the “High Amplitude” and “Low Amplitude” values of each region can also be subtracted using the infomation in the self.cosine_similarity property to determine the most predominantly active and suppressed networks in order to characterize CAPs.

Important

In the self.cosine_similarity, the absolute values for “Low Amplitude”, which are the negative cosine similarity values, denoting alignment to the deactivations (< 0) of a CAP are provided.

Methodology: The process involves the following steps for computing the “High Amplitude” and “Low Amplitude” values for each CAP and network/region combination

  1. Extract Cluster Centroids:

    • Each CAP is represented by a cluster centroid, which is a 1 x ROI

    (Region of Interest) vector.

  2. Generate Binary Vectors:

    • For each network/region create a binary vector (1 x ROI) where “1” indicates that

    the ROI is part of the specific region and “0” otherwise. - In this example, the binary vector acts as a 1-D mask to isolate ROIs in the Visual Network by setting the corresponding indices to “1”.

    import numpy as np

# Define nodes with their corresponding label IDs
nodes = ["LH_Vis1", "LH_Vis2", "LH_SomSot1", "LH_SomSot2",
            "RH_Vis1", "RH_Vis2", "RH_SomSot1", "RH_SomSot2"]

# Binary mask for the Visual Network (Vis)
binary_vector = np.array([1, 1, 0, 0, 1, 1, 0, 0])

  3. Isolate Positive and Negative Activations in CAP Centroid:

    • Positive activations are defined as the values in the CAP centroid that are greater

    than zero. These values represent the “High Amplitude” activations for that CAP. - Negative activations are defined as the values in the CAP centroid that are less than zero. These values represent the “Low Amplitude” activations for that CAP.

    # Example cluster centroid for CAP 1
cap_1_cluster_centroid = np.array([-0.3, 1.5, 2.0, -0.2, 0.7, 1.3, -0.5, 0.4])

# Assign values less than 0 as 0 to isolate the high amplitude activations
high_amp = np.where(cap_1_cluster_centroid > 0, cap_1_cluster_centroid, 0)

# Assign values greater than 0 as 0 to isolate the low amplitude activations
# Also invert the sign to restrict similarity to [0, 1]
low_amp = np.where(cap_1_cluster_centroid < 0, -cap_1_cluster_centroid, 0)

  4. Calculate Cosine Similarity:

    • Normalize the dot product by the product of the Euclidean norms of the cluster

    centroid and the binary vector to obtain the cosine similarity:

    # Compute dot product between the binary vector each activation vector
high_dot = np.dot(high_amp, binary_vector)
low_dot = np.dot(low_amp, binary_vector)

# Compute the norms
high_norm = np.linalg.norm(high_amp)
low_norm = np.linalg.norm(low_amp)
bin_norm = np.linalg.norm(binary_vector)

# Calculate cosine similarity; Produces the alignment of the region/network
# with the active and suppressed patterns of the CAP
high_cos = high_dot / (high_norm * bin_norm)
low_cos = low_dot / (low_norm * bin_norm)

  5. Generate Radar Plots of Each CAPs:

    • Each radar plot visualizes the cosine similarity for both “High Amplitude”

    (positive) and “Low Amplitude” (negative) activations of the CAP.

Handling Division by Zero: NumPy automatically handles division by zero errors. This may occur if the network or the “High Amplitude” or “Low Amplitude” vectors are all zeroes. In such cases, NumPy assigns NaN to the cosine similarity for the affected network(s), indicating that the similarity is undefined.

Parcellation Approach: If using “Custom” for parcel_approach the “regions” subkey is required.

Saving Plots and Chrome Installation: Kaleido >= 1.0.0 no longer installs Chrome automatically. Saving plots as PNG requires Chrome. If Chrome is not installed, either install it or run pip install kaleido && kaleido_get_chrome, or use plot_output_format="html" as an alternative.

Tick Values: if the tickvals or range subkeys in this code are not specified in the radialaxis kwarg, then four values are shown - 0.25*(max value), 0.50*(max value), 0.75*(max value), and the max value. These values are also rounded to the second decimal place.

References

Zhang, R., Yan, W., Manza, P., Shokri-Kojori, E., Demiral, S. B., Schwandt, M., Vines, L., Sotelo, D., Tomasi, D., Giddens, N. T., Wang, G., Diazgranados, N., Momenan, R., & Volkow, N. D. (2023). Disrupted brain state dynamics in opioid and alcohol use disorder: attenuation by nicotine use. Neuropsychopharmacology, 49(5), 876–884. https://doi.org/10.1038/s41386-023-01750-w

Ingwersen, T., Mayer, C., Petersen, M., Frey, B. M., Fiehler, J., Hanning, U., Kühn, S., Gallinat, J., Twerenbold, R., Gerloff, C., Cheng, B., Thomalla, G., & Schlemm, E. (2024). Functional MRI brain state occupancy in the presence of cerebral small vessel disease — A pre-registered replication analysis of the Hamburg City Health Study. Imaging Neuroscience, 2, 1–17. https://doi.org/10.1162/imag_a_00122

On this page