neurocaps.analysis.CAP.caps2radar#

CAP.caps2radar(output_dir=None, suffix_title=None, suffix_filename=None, show_figs=True, use_scatterpolar=False, as_html=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 a parcellation. This function assumes the mean for each ROI is 0 due to standardization.

Cosine similarity is computed separately for high and low amplitudes by comparing them to the binary vector of the a-priori region, representing the region or network of interest. This provides a measure of how closely the CAP's positive and negative activation patterns align with each selected region.

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.

  • To simplify the comparison between positive and negative activations using cosine similarity, the negative activations are inverted (i.e., multiplied by -1). This inversion converts the negative values into positive ones, allowing the cosine similarity calculation to return a positive value. The positive similarity score represents how closely the a-priori region aligns with both the high and low amplitude aspects of the 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. The cosine similarity values range from 0 to 1, representing how closely the a-priori region aligns with the positive and negative activations of the CAP centroid.

Note, if groups were given when the CAP class was initialized, separate radar plots will be generated per CAP for all groups.

Parameters:

  • output_dir (os.PathLike 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 images instead of png images.

  • **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="none" -- 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

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. Plotly is capable of handling NaN values.

Parcellation Approach: If using "Custom" for parcel_approach the "regions" sub-key is required.

Saving Plots: By default, this function uses "kaleido" (which is also a dependency in this package) to save plots. For other engines such as "orca", those packages must be installed seperately.

Tick Values: if the tickvals or range sub-keys 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