nispace.plotting.brainplot

nispace.plotting.brainplot(data, parcellation=None, kind=None, space=None, surf_mesh='inflated', views=None, plot_contours=False, zoom=None, bg_on_data=True, darkness=0.7, dim='auto', threshold='auto', alpha=0.8, display_mode=None, cut_coords=None, bg_img=None, draw_cross=False, draw_brain=True, black_bg=False, cmap=None, vmin=None, vmax=None, shared_colorscale=False, symmetric_cmap='auto', colorbar=True, colorbar_label='', colorbar_inset=None, ncols=1, title='auto', hspace=None, wspace=None, figsize=None, fig=None, axes=None, title_kwargs=None, verbose=False, **kwargs)

Plot brain maps onto surfaces or anatomical volumes.

Parameters:

• data (pd.DataFrame, pd.Series, array-like, NIfTI image, or GIfTI pair) – Tabular input: shape (n_maps, n_parcels) — requires parcellation. NIfTI image (nib.Nifti1Image or path): 3D volume for glass/slice plots — parcellation must be None. GIfTI pair: (lh, rh) tuple or list of such tuples for surface plots, where each element is a nib.GiftiImage, a path, or a vertex-data array — parcellation must be None.

• parcellation (Parcellation, str, Path, NIfTI image, GIfTI image, tuple, or None) –

  Parcellation to use for mapping tabular data onto the brain. Required when data is tabular; must be None for NIfTI/GIfTI image input. Accepted forms:

  • Parcellation — a fitted NiSpace Parcellation object.

  • str — NiSpace library name (e.g. "Schaefer400") or a file-system path to a NIfTI/GIfTI parcellation image.

  • pathlib.Path — path to a NIfTI or GIfTI parcellation image.

  • nib.Nifti1Image — volumetric parcellation image.

  • nib.GiftiImage or tuple — surface parcellation; pass a (lh, rh) tuple where each element is a GiftiImage or path.

• kind ({"surface", "glass", "slice", "combined"}, optional) – Rendering mode. Defaults to "surface" when parcellation is a GIfTI image/tuple, "surface" for surface-only Parcellation objects, and "glass" otherwise. Use "combined" for surface+glass side-by-side (not yet implemented); pass "glass" or "slice" to render any parcellation as a plain MNI volume.

• space (str, optional) – Parcellation space to use for rendering. Defaults to fsLR for surface plots and MNI152NLin2009cAsym for volume plots. For GIfTI image input, the resolution is auto-detected from vertex count and space determines fsLR vs fsaverage (default: fsLR).

• surf_mesh ({"inflated", "pial", "midthickness", "veryinflated"}) – Surface geometry. For fsLR, available options depend on resolution (veryinflated only at 32k/164k). Ignored for non-surface plots.

• views (list of str, optional) – Surface views as “<hemi>_<perspective>” strings. Default: [“left_lateral”, “left_medial”, “right_medial”, “right_lateral”].

• plot_contours (bool) – Draw black parcel borders on surface plots.

• zoom (float, optional) – Zoom factor applied to each brain panel. Defaults to 1.5 for surface plots and 1.0 for glass/slice (no zoom).

• bg_on_data (bool) – Overlay sulcal shading on top of the statistical map.

• darkness (float) – Darkness of sulcal background shading (0 = bright, 1 = dark).

• dim (float or "auto") – Dimming factor for the anatomical background in slice plots. Roughly −2 (more contrast) to +2 (dimmer). Default "auto".

• threshold (float, "auto", or None) – Values with absolute value below threshold are not displayed. Default "auto" sets threshold to min(|data|) / 2, masking background zeros while keeping all parcel values visible. Pass None to disable thresholding entirely.

• alpha (float, optional) – Transparency of the statistical map. Default 0.8 for all kinds.

• display_mode (str, optional) – Nilearn display mode for glass/slice. Defaults to “lyrz” for glass (left, posterior, right, top) and “ortho” for slice.

• cut_coords (int or list, optional) – Number of auto-cuts or explicit coordinates for slice plots.

• bg_img (NIfTI image or path, optional) – Background anatomical for slice plots. Auto-fetched from NiSpace templates when None.

• draw_cross (bool) – Draw crosshair lines at slice positions.

• draw_brain (bool) – Draw the glass brain outline (grey wireframe). Set to False to show only the statistical overlay without the brain silhouette. Only applies to kind="glass".

• black_bg (bool) – Use a black figure and axes background. For glass/slice this is forwarded to nilearn’s black_bg parameter; for surface it sets the figure patch and 3-D axes pane colors to black.

• cmap (str, optional) – Colormap name. Defaults to “RdBu_r” when the colorscale is symmetric and “viridis” otherwise (see symmetric_cmap).

• vmin (float, optional) – Color scale limits. None = auto-computed per map.

• vmax (float, optional) – Color scale limits. None = auto-computed per map.

• shared_colorscale (bool) – Compute vmin/vmax across all maps (one shared colorbar). Always True for combined parcellations.

• symmetric_cmap (bool or "auto") – Center color limits at 0. True → RdBu_r, False → viridis (unless cmap is set explicitly). “auto” (default) detects from the data: symmetric if values span both sides of zero, sequential otherwise.

• colorbar (bool) – Show colorbar. When shared, one horizontal bar is placed at the bottom center of the figure.

• colorbar_label (str) – Title string displayed above the colorbar. Empty string (default) means no title.

• colorbar_inset (list of float, optional) – Position of the colorbar axes as [x0, y0, width, height] in parent-axes coordinates. Defaults to [1.02, 0.15, 0.02, 0.7] for glass brain and [1.04, 0.25, 0.02, 0.5] for surface/slice.

• ncols (int) – Number of map columns in the subplot grid.

• title (str, list, or bool, optional) – Map title above each brain. "auto" (default) uses the map’s index label for tabular input and shows no title for NIfTI/GIfTI image input (where no meaningful label is available). Pass a string, a list of strings (one per map), or False/None to disable.

• hspace (float) – Vertical spacing between map rows (passed to GridSpec/subplots).

• wspace (float, optional) – Horizontal spacing between map columns (fraction of axes width). Defaults to 0.1 for glass/slice and 0.02 for surface; auto-increased for multi-column layouts to leave room for per-column colorbars.

• figsize (tuple, optional) – Figure size in inches. Auto-computed if None.

• fig (matplotlib.Figure, optional) – Existing figure to draw into.

• axes (list of matplotlib.Axes, optional) – Axes to draw into (must match layout when fig is provided).

• title_kwargs (dict, optional) – Extra keyword arguments passed to fig.text() for the title. Standard matplotlib text params (fontsize, color, etc.) are accepted; defaults are {"fontsize": "large", "fontweight": "bold"}. A special "y" key sets the title y-position as a fraction of the axes height (default: 0.92 inside the axes for surface, 1.02 above for others).

• verbose (bool) – Enable verbose logging.

• **kwargs – Extra keyword arguments forwarded to the underlying nilearn function (plot_surf_stat_map, plot_glass_brain, or plot_stat_map depending on kind).

Returns:

• fig (matplotlib.Figure)

• axes_list (list of matplotlib.Axes)