CAP.caps2radar#

CAP.caps2radar(output_dir=None, suffix_title=None, suffix_filename=None, show_figs=True, use_scatterpolar=False, as_html=False, as_json=False, **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 cluster centroid and each a-priori region or network in the parcellation defined by parcel_approach. One image 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.

The process involves the following steps:

  1. Extract Cluster Centroids:

  • Each CAP is represented by a cluster centroid, which is a 1 x ROI (Region of Interest) vector.

  1. Generate Binary Vectors:

  • For each 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 1D 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])

  1. 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 less than 0 as 0 to isolate the low amplitude activations; Also invert the sign
low_amp = high_amp = np.where(cap_1_cluster_centroid < 0, -cap_1_cluster_centroid, 0)

  1. 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 with the positive and negative activations
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
high_cos = high_dot / (high_norm * bin_norm)
low_cos = low_dot / (low_norm * bin_norm)

  1. 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.

Parameters:

  • 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.

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

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

  • 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.

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

  • as_html (bool, default=False) – When output_dir is specified, plots are saved as html file instead of png images.

  • as_json (bool, default=False) –

    When output_dir is specified, plots are saved as json file, which can be further modified, instead of png images.

    Added in version 0.26.5.

  • **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.

      Changed in version 0.26.0: Default changed from “none” to “toself”.

    • 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

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