neurocaps.analysis.CAP.caps2radar

CAP.caps2radar(output_dir=None, suffix_title=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:

Extract Cluster Centroids:

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

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])
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)
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)
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 as well as the name of the saved file if output_dir is provided.
show_figs (bool, default=True) -- Display figures. If this function detects that it is not being ran in an interactive Python environment, then it uses plotly.offline, creates an html file named "temp-plot.html", and opens each plot in the default browser.
use_scatterpolar (bool, default=False) -- Uses plotly.graph_objects.Scatterpolar instead of plotly.express.line_polar. The primary difference is that plotly.graph_objects.Scatterpolar shows the scatter dots. However, this can be acheived with plotly.express.line_polar by setting mode to "markers+lines". There also seems to be a difference in default opacity behavior.
as_html (bool, default=False) -- When output_dir is specified, plots are saved as html images instead of png images. The advantage is that plotly's radar plots will retain its interactive properties, can be opened in a browser.
kwargs (dict) --
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. The height and width are multiplied by the dpi.
- height: int, default=800
  Height of the plot. Value is multiplied by the dpi when saving.
- width: int, defualt=1200
  Width of the plot. Value is multiplied by the dpi when saving.
- 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.
- 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.
- color_discrete_map: dict, default={"High Amplitude": "red", "Low Amplitude": "blue"},
  Change color of the "High Amplitude" and "Low Amplitude" groups. Must use the keys "High Amplitude" and "Low Amplitude" to work.
- title_font: dict, default={"family": "Times New Roman", "size": 30, "color": "black"}
  Modifies the font of the title.
- 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.
- engine: {"kaleido", "orca"}, default="kaleido"
  Engine used for saving plots.

Returns:

plotly.express.line_polar -- An instance of plotly.express.line_polar.
plotly.graph_objects.Scatterpolar -- An instance of plotly.graph_objects.Scatterpolar.

Note

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.

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

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.

Radial Axis Kwargs: For valid keys for radialaxis refer to plotly's documentation at https://plotly.com/python-api-reference/generated/plotly.graph_objects.layout.polar.radialaxis.html or https://plotly.com/python/reference/layout/polar/ for valid kwargs.

Angular Axis Kwargs: For valid keys for angularaxis refer to plotly's documentation at https://plotly.com/python-api-reference/generated/plotly.graph_objects.layout.polar.angularaxis.html or https://plotly.com/python/reference/layout/polar/ for valid kwargs.

Legend and Title Font Kwargs: For valid keys for legend and title_font, refer to plotly's documentation at https://plotly.com/python/reference/layout/ for valid kwargs.

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