CAP.caps2plot#

CAP.caps2plot(plot_options='heatmap', visual_scope='regions', subplots=False, output_dir=None, plot_output_format='png', suffix_filename=None, suffix_title=None, show_figs=True, **kwargs)[source]#

Generate Heatmaps and Outer Product Plots for CAPs.

Produces a 2D plot for each CAP, visualized as either a heatmap or an outer product. The visualization can be generated at two levels of granularity (nodes or regions). Separate plots are generated for each group.

Parameters:

  • plot_options ({“heatmap”, “outer_product”} or list["heatmap", "outer_product"], default=”heatmap”) –

    Type of plots to create. Options are:

    • ”heatmap”: Displays the activation value (z-score if data was standardized prior to clustering) of each node or the average activation of each predefined region across all CAPs. Each column represents a different CAP, while each row represents a node/region.

    • ”outer_product”: Computed as the outer product of the CAP vector (cluster centroid) with itself (i.e. np.outer(CAP_1, CAP_1)). This shows the pairwise interactions between all nodes/regions, highlighting pairs that co-activate/co-deactivate together (positive values) or diverge where one node/region activates while the other deactivates (negative values). The main diagonal represents self-interactions (the squared activation of each node/region), while off-diagonal elements represent pairwise interactions between different nodes/regions.

    Changed in version 0.33.0: Default changed to “heatmap”

  • visual_scope ({“regions”, “nodes”} or list["regions", "nodes"], default=”regions”) –

    Determines the level of granularity of the plots. Options are:

    • ”nodes”: Visualizes each parcel from the brain parcellation individually.

    • ”regions”: Averages parcels into larger groups based on their network membership before plotting. These groupings must be defined in the parcel_approach configuration under the “regions” subkey.

  • subplots (bool, default=True) – Produce subplots for outer product plots, combining all plots into a single figure.

  • output_dir (str or None, default=None) – Directory for saving plots as png files. 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” or “pkl” (which can be further modified). Note that “pickle” is also accepted.

    Changed in version 0.33.0: Replaces as_pickle 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.

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

Returns:

self

Note

Parcellation Approach: the “nodes” and “regions” subkeys are required in parcel_approach for this method.

Property Persistence: the function creates and recomputes self.region_means for each call if “regions” is in visual_scope and and creates and recomputes self.outer_products for each call if “outer_products” is in plot_options. For self.outer_products, the final values stored are associated with the last string in the visual_scope list.

On this page