neurocaps.analysis.CAP.caps2plot

CAP.caps2plot(output_dir=None, suffix_title=None, plot_options='outer_product', visual_scope='regions', show_figs=True, subplots=False, **kwargs)[source]

Generate Heatmaps and Outer Product Plots for CAPs.

Plot CAPs as heatmaps or outer products at the node or region/network levels. This function produces a seaborn.heatmap for each CAP. Note, if groups were given when the CAP class was initialized, separate plots will be generated for all groups.

Parameters:

output_dir (os.PathLike 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.
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.
plot_options ({"outer_product", "heatmap"} or list["outer_product", "heatmap"], default="outer_product") -- Type of plots to create. Options are "outer_product" or "heatmap".
visual_scope ({"regions", "nodes"} or list["regions", "nodes"], default="regions") -- Determines whether plotting is done at the region level or node level. For "regions", the values of all nodes in the same regions (including both hemispheres) are averaged together then plotted. For "nodes", plots individual node values separately.
show_figs (bool, default=True) -- Display figures.
subplots (bool, default=True) -- Produce subplots for outer product plots, combining all plots into a single figure.
kwargs (dict) --
Keyword arguments used when saving figures. Valid keywords include:
- dpi: int, default=300
  Dots per inch for the figure. Default is 300 if output_dir is provided and dpi is not specified.
- 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 to fix 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.
- hemisphere_labels: bool, default=False
  Only available when visual_scope="nodes". Simplifies node labels to show only left/right hemisphere divisions with a separation line, rather than listing individual node labels. If set to True, edgecolors is ignored and linewidths and linecolor affect only the hemisphere division line. This option is available exclusively for "Custom" and "Schaefer" parcellations. Note, for the "Custom" parcellations, nodes must be ordered with left hemisphere nodes first, followed by right hemisphere nodes.
- cmap: str or callable default="coolwarm"
  Color map for the plot cells. For this parameter, you can use pre-made color palettes or create custom ones. Below is a list of valid options:
  - Strings to call seaborn's pre-made palettes.
  - seaborn.diverging_palette function to generate custom palettes.
  - matplotlib.colors.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.

Returns:

seaborn.heatmap -- An instance of seaborn.heatmap.

Note

Parcellation Approach: the "nodes" and "regions" sub-keys are required in parcel_approach for this function.

Color Palettes: For valid pre-made palettes for seaborn, refer to https://seaborn.pydata.org/tutorial/color_palettes.html