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 parameters to pass to modify certain plot parameters. Options include:

    • scale: int, default=2 – If output_dir provided, controls resolution of image when saving. Serves a similar purpose as dpi.

    • savefig_options: dict[str], default={“width”: 3, “height”: 3, “scale”: 1} – If output_dir provided, controls the width (in inches), height (in inches), and scale of the plot.

    • height: int, default=800 – Height of the plot.

    • width: int, defualt=1200 – Width of the plot.

    • line_close: bool, default=True – Whether to close the lines

    • bgcolor: str, default=”white” – Color of the background

    • scattersize: int, default=8 – Controls size of the dots when markers are used.

    • connectgaps: bool, default=True – If use_scatterpolar=True, controls if missing values are connected.

    • linewidth: int, default = 2 – The width of the line connecting the values if use_scatterpolar=True.

    • opacity: float, default=0.5 – If use_scatterpolar=True, sets the opacity of the trace.

    • fill: str, default=”toself” – If “toself” the are of the dots and within the boundaries of the line will be filled.

    • mode: str, default=”markers+lines” – Determines how the trace is drawn. Can include “lines”, “markers”, “lines+markers”, “lines+markers+text”.

    • radialaxis: dict, default={“showline”: False, “linewidth”: 2, “linecolor”: “rgba(0, 0, 0, 0.25)”, “gridcolor”: “rgba(0, 0, 0, 0.25)”, ticks”: “outside”, “tickfont”: {“size”: 14, “color”: “black”}} – Customizes the radial axis. Refer to Plotly’s radialaxis Documentation or Plotly’s polar Documentation for valid keys.

    • angularaxis: dict, default={“showline”: True, “linewidth”: 2, “linecolor”: “rgba(0, 0, 0, 0.25)”, “gridcolor”: “rgba(0, 0, 0, 0.25)”, “tickfont”: {“size”: 16, “color”: “black”}} – Customizes the angular axis. Refer to Plotly’s angularaxis Documentation or Plotly’s polar Documentation for valid keys.

    • color_discrete_map: dict, default={“High Amplitude”: “red”, “Low Amplitude”: “blue”} – Change the color of the “High Amplitude” and “Low Amplitude” groups. Must use the keys “High Amplitude” and “Low Amplitude”.

    • title_font: dict, default={“family”: “Times New Roman”, “size”: 30, “color”: “black”} – Modifies the font of the title. Refer to Plotly’s layout Documentation for valid keys.

    • title_x: float, default=0.5 – Modifies x position of title.

    • title_y: float, default=None – Modifies y position of title.

    • legend: dict, default={“yanchor”: “top”, “xanchor”: “left”, “y”: 0.99, “x”: 0.01, title_font_family”: “Times New Roman”, “font”: {“size”: 12, “color”: “black”}} – Customizes the legend. Refer to Plotly’s layout Documentation for valid keys

    • engine: {“kaleido”, “orca”}, default=”kaleido” – Engine used for saving plots.

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.

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: By default, this function uses “kaleido” (a dependency of NeuroCAPs) to save plots. For other engines such as “orca”, those packages must be installed seperately.

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