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 –

    Keyword arguments used when saving figures. Valid keywords include:

    • dpi: int, default=300 – Dots per inch for the figure.

    • figsize: tuple, default=(8, 6) – Size of the figure in inches.

    • fontsize: int, default=14 – Font size for the title of individual plots or subplots.

    • hspace: float, default=0.4 – Height space between subplots.

    • wspace: float, default=0.4 – Width space between subplots.

    • xticklabels_size: int, default=8 – Font size for x-axis tick labels.

    • yticklabels_size: int, default=8 – Font size for y-axis tick labels.

    • shrink: float, default=0.8 – Fraction by which to shrink the colorbar.

    • cbarlabels_size: int, default=8 – Font size for the colorbar labels.

    • nrow: int, default=varies (max 5) – Number of rows for subplots. Default varies but the maximum is 5.

    • ncol: int or None, default=None – Number of columns for subplots. Default varies but the maximum is 5.

    • suptitle_fontsize: float, default=0.7 – Font size for the main title when subplot is True.

    • tight_layout: bool, default=True – Use tight layout for subplots.

    • rect: list[int], default=[0, 0.03, 1, 0.95] – Rectangle parameter for tight_layout when subplots are True. Fixes whitespace issues.

    • sharey: bool, default=True – Share y-axis labels for subplots.

    • xlabel_rotation: int, default=0 – Rotation angle for x-axis labels.

    • ylabel_rotation: int, default=0 – Rotation angle for y-axis labels.

    • annot: bool, default=False – Add values to cells.

    • annot_kws: dict, default=None – Customize the annotations.

    • fmt: str, default=”.2g” – Modify how the annotated vales are presented.

    • linewidths: float, default=0 – Padding between each cell in the plot.

    • borderwidths: float, default=0 – Width of the border around the plot.

    • linecolor: str, default=”black” – Color of the line that seperates each cell.

    • edgecolors: str or None, default=None – Color of the edges.

    • alpha: float or None, default=None – Controls transparency and ranges from 0 (transparent) to 1 (opaque).

    • bbox_inches: str or None, default=”tight” – Alters size of the whitespace in the saved image.

    • cmap: str, callable default=”coolwarm” – Color map for the plot cells. Options include strings to call seaborn’s pre-made palettes, seaborn.diverging_palette function to generate custom palettes, and matplotlib.color.LinearSegmentedColormap to generate custom palettes.

    • vmin: float or None, default=None – The minimum value to display in colormap.

    • vmax: float or None, default=None – The maximum value to display in colormap.

    • add_custom_node_labels: bool, default=False – When visual_scope is set to “nodes” and a “Custom” parcel_approach is used, adds simplified node names to the plot’s axes. Instead of labeling every individual node, the node list is “collapsed” by region. A single label is then placed at the beginning of the group of nodes corresponding to that region (e.g., “LH Visual” or “Hippocampus”), while the other nodes in that group are not explicitly labeled. This is done to minimize cluttering of the axes labels.

      Important

      This feature should be used with caution. It is recommended to leave this argument as False for the following conditions:

      1. Large Number of Nodes: Enabling labels for a parcellation with many nodes can clutter the plot axes and make them unreadable.

      2. Non-Consecutive Node Indices: The labeling logic assumes that the numerical indices for all nodes within a given region are defined as a consecutive block (e.g., "RegionA": [0, 1, 2], "RegionB": [3, 4]). If the indices are non-consecutive or interleaved (e.g., "RegionA": [0, 2], "RegionB": [1, 3]), the axis labels will be misplaced. Note that this issue only affects the visual labeling on the plot; the underlying data matrix remains correctly ordered and plotted.

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.

Color Palettes: Refer to seaborn’s Color Palettes for valid pre-made palettes.

On this page