plotting¶
nltools.plotting — Visualization utilities for neuroimaging analysis.
This package provides standalone plotting functions organized into focused submodules:
brain: Surface plots, flatmaps, and interactive brain viewers
adjacency: Adjacency matrix visualizations (stacked, silhouette, distance)
prediction: Model output plots (ROC, SVM margin, regression, logistic)
decomposition: ICA/PCA component viewer
All public functions are re-exported here for convenience:
from nltools.plotting import plot_surf, plot_roc, component_viewer # all workMethods:
| Name | Description |
|---|---|
component_viewer | Interactively view the results of a BrainData.decompose() run. |
plot_between_label_distance | Heatmap of average pairwise distance between every label pair. |
plot_dist_from_hyperplane | Plot SVM Classification Distance from Hyperplane. |
plot_flatmap | Plot brain data on cortical flatmap. |
plot_interactive_brain | Create an interactive brain visualization with nilearn. |
plot_mean_label_distance | Violin plot of within- vs between-label distances. |
plot_probability | Plot Classification Probability. |
plot_roc | Plot 1-Specificity by Sensitivity. |
plot_scatter | Plot Prediction Scatterplot. |
plot_silhouette | Silhouette plot indicating between- vs within-label distance. |
plot_stacked_adjacency | Create stacked adjacency to illustrate similarity. |
plot_surf | Plot volumetric data on fsaverage surfaces in a tight 2×2 montage. |
Modules:
| Name | Description |
|---|---|
adjacency | Adjacency matrix visualization — stacked plots, distance, and silhouette. |
brain | Brain visualization — surface plots, flatmaps, and interactive viewers. |
decomposition | ICA/PCA component viewer — interactive decomposition explorer. |
prediction | Model output visualization — ROC, SVM margin, regression, and logistic plots. |
Methods¶
component_viewer¶
component_viewer(output, tr = 2.0)Interactively view the results of a BrainData.decompose() run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output | (dict) output dictionary from running BrainData.decompose() | required | |
tr | (float) repetition time of data | 2.0 |
Returns:
| Type | Description |
|---|---|
| None (renders interactive widgets inline) |
plot_between_label_distance¶
plot_between_label_distance(distance, labels, *, ax = None, permutation_test = True, n_permute = 5000, **kwargs)Heatmap of average pairwise distance between every label pair.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a group label for each row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, also compute mean-difference and p-value matrices. | True | |
n_permute | Number of permutations. | 5000 | |
**kwargs | Passed to seaborn.heatmap. | {} |
Returns:
| Type | Description |
|---|---|
| Without permutation_test: (long_df, within_mean_df) | |
| With permutation_test: (long_df, within_mean_df, mean_diff_df, p_df) | |
All frames are polars DataFrames. long_df has columns | |
| [Distance, Group, Comparison]. The three square-matrix-like frames | |
| are long format with columns [label1, label2, ] so they can | |
| be pivoted to a matrix if needed. |
plot_dist_from_hyperplane¶
plot_dist_from_hyperplane(stats_output)Plot SVM Classification Distance from Hyperplane.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid of distance from hyperplane |
plot_flatmap¶
plot_flatmap(brain, *, threshold = None, cmap = 'RdBu_r', vmax = None, vmin = None, template = 'fsaverage5', with_curvature = True, curvature_contrast = 0.5, curvature_brightness = 0.5, transparency = 'auto', colorbar = True, colorbar_orientation = 'horizontal', figsize = (12, 6), title = None, radius_mm = 3.0, interpolation = 'linear', axes = None, save = None)Plot brain data on cortical flatmap.
Projects MNI152 volumetric data onto an fsaverage surface and renders as a 2D flattened cortical map. Uses nilearn’s vol_to_surf for projection and matplotlib’s tripcolor for rendering.
This function provides publication-quality flatmap visualizations without requiring external dependencies like pycortex.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData, nibabel Nifti1Image, or file path to NIfTI image. Data must be in MNI152 space. | required | |
threshold | float or str | Values below this absolute threshold are masked. Can be a float or percentile string like ‘95%’. Defaults to None (no threshold). | None |
cmap | str | Matplotlib colormap for data. Defaults to ‘RdBu_r’ (diverging red-blue). | ‘RdBu_r’ |
vmax | float | Maximum value for colormap. If None, uses symmetric max of absolute values. | None |
vmin | float | Minimum value for colormap. If None and vmax is set, uses -vmax for diverging maps. | None |
template | str | fsaverage resolution. Options: ‘fsaverage3’ (642 vertices), ‘fsaverage4’ (2562), ‘fsaverage5’ (10242, default), ‘fsaverage6’ (40962), ‘fsaverage’ (163842, full resolution). | ‘fsaverage5’ |
with_curvature | bool | Show sulcal/gyral pattern as grayscale background. Defaults to True. | True |
curvature_contrast | float | Contrast of curvature (0=flat gray, 1=full contrast). Defaults to 0.5. | 0.5 |
curvature_brightness | float | Mean brightness of curvature (0=dark, 1=bright). Defaults to 0.5. | 0.5 |
transparency | BrainData, Nifti1Image, str, Path, or “auto” | Binary mask used to render vertices outside the mask as transparent (so the curvature shows through). "auto" (default) uses the input BrainData’s .mask when available, matching the behavior of the volumetric .plot(). Pass None to disable masking entirely. | ‘auto’ |
colorbar | bool | Show colorbar. Defaults to True. | True |
colorbar_orientation | str | ‘horizontal’ or ‘vertical’. Defaults to ‘horizontal’. | ‘horizontal’ |
figsize | tuple | Figure size (width, height). Defaults to (12, 6). | (12, 6) |
title | str | Figure title. Defaults to None. | None |
radius_mm | float | Sampling radius in mm for vol_to_surf projection. Larger values provide smoother projections. Defaults to 3.0. | 3.0 |
interpolation | str | Interpolation for vol_to_surf. Options: ‘linear’, ‘nearest_most_frequent’. Defaults to ‘linear’. | ‘linear’ |
axes | Axes | Existing axes to plot on. If None, creates new figure. Defaults to None. | None |
save | str | File path to save figure. Defaults to None. | None |
Returns:
| Type | Description |
|---|---|
| matplotlib.figure.Figure: The figure containing the flatmap. |
Examples:
Basic flatmap with default settings:
>>> from nltools.plotting import plot_flatmap
>>> from nltools.data import BrainData
>>> brain = BrainData('stats.nii.gz')
>>> fig = plot_flatmap(brain)Thresholded with custom colormap:
>>> fig = plot_flatmap(brain, threshold=2.5, cmap='hot')Percentile threshold, no curvature:
>>> fig = plot_flatmap(brain, threshold='95%', with_curvature=False)High resolution for publication:
>>> fig = plot_flatmap(brain, template='fsaverage6', figsize=(16, 8))
>>> fig.savefig('flatmap.pdf', dpi=300)Note
Data is projected from MNI152 space to fsaverage surface space. Small alignment differences are expected at boundaries.
Higher resolution templates (fsaverage6, fsaverage) produce sharper images but take longer to render.
The flat surfaces are cached by nilearn after first download (~50MB for fsaverage5).
plot_interactive_brain¶
plot_interactive_brain(brain, *, threshold = 1e-06, surface = False, percentile_threshold = False, anatomical = None, **kwargs)Create an interactive brain visualization with nilearn.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData | a BrainData instance of 1d or 2d shape (i.e. 3d or 4d volume) | required |
threshold | float / str | threshold to initialize the visualization, may be a percentile string; default 1e-6 | 1e-06 |
surface | bool | whether to create a surface-based plot; default False | False |
percentile_threshold | bool | whether to interpret threshold values as percentiles | False |
kwargs | optional arguments to nilearn.view_img or nilearn.view_img_on_surf | {} |
Returns:
| Type | Description |
|---|---|
| None (renders widgets inline) |
plot_mean_label_distance¶
plot_mean_label_distance(distance, labels, *, ax = None, permutation_test = False, n_permute = 5000, fontsize = 18, **kwargs)Violin plot of within- vs between-label distances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a group label for each row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, run a two-sample permutation test per group. | False | |
n_permute | Number of permutations. | 5000 | |
fontsize | Font size for plot labels. | 18 | |
**kwargs | Passed to seaborn.violinplot. | {} |
Returns:
| Type | Description |
|---|---|
| pl.DataFrame with columns [Distance, Group, Type] in long format. | |
| If permutation_test=True, returns (pl.DataFrame, dict of per-group stats). |
plot_probability¶
plot_probability(stats_output)Plot Classification Probability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid scatterplot |
plot_roc¶
plot_roc(fpr, tpr)Plot 1-Specificity by Sensitivity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fpr | false positive rate from Roc.calculate | required | |
tpr | true positive rate from Roc.calculate | required |
Returns:
| Type | Description |
|---|---|
| a matplotlib Figure |
plot_scatter¶
plot_scatter(stats_output)Plot Prediction Scatterplot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid scatterplot |
plot_silhouette¶
plot_silhouette(distance, labels, *, ax = None, permutation_test = True, n_permute = 5000, colors = None, figsize = (6, 4))Silhouette plot indicating between- vs within-label distance.
Uses the simplified silhouette definition from the original nltools implementation: within(i) = mean distance to other points in the same cluster; between(i) = mean distance to all points in other clusters (not the strict Rousseeuw min-over-clusters). Score is (between - within) / max(between, within).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a cluster label per row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, run a one-sample permutation test per cluster on positive-mean silhouette scores. | True | |
n_permute | Number of permutations. | 5000 | |
colors | Optional list of RGB triplets, one per cluster (default: seaborn ‘hls’ palette). | None | |
figsize | Figure size tuple. Default (6, 4). | (6, 4) |
Returns:
| Type | Description |
|---|---|
| pl.DataFrame with columns [label, mean_silhouette]. If permutation_test | |
is True, adds a p column (1.0 for clusters with non-positive mean). |
plot_stacked_adjacency¶
plot_stacked_adjacency(adjacency1, adjacency2, normalize = True, **kwargs)Create stacked adjacency to illustrate similarity.
adjacency1 is drawn in the upper triangle and adjacency2 in the lower,
consistently whether or not normalize is set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adjacency1 | Adjacency instance shown in the upper triangle. | required | |
adjacency2 | Adjacency instance shown in the lower triangle. | required | |
normalize | Normalize matrices before stacking. Default True. | True | |
**kwargs | Passed through to seaborn.heatmap. | {} |
Returns:
| Type | Description |
|---|---|
| matplotlib axes with the stacked heatmap. |
plot_surf¶
plot_surf(brain, *, hemi = 'both', view = 'montage', surface = 'pial', template = 'fsaverage5', threshold = None, cmap = 'RdBu_r', vmin = None, vmax = None, transparency = 'auto', bg_on_data = False, colorbar = True, colorbar_orientation = 'horizontal', figsize = (10, 8), title = None, radius_mm = 3.0, interpolation = 'linear', zoom = 1.2, axes = None, save = None)Plot volumetric data on fsaverage surfaces in a tight 2×2 montage.
Like nilearn’s plot_img_on_surf but with actually-tight framing
(via Axes3D.set_box_aspect(zoom=...) + set_axis_off), an
auto-applied transparency mask (same convention as plot_flatmap),
and a single shared colorbar instead of one-per-subplot.
The grid is len(view) × len(hemi) — rows = views, cols = hemispheres.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData, nibabel Nifti1Image, or file path (MNI-space). | required | |
hemi | str or list | "left", "right", "both" (default), or a list subset like ["left"]. | ‘both’ |
view | str or list | "montage" (default, → ["lateral", "medial"]), a single view string, or any list subset of ("lateral", "medial", "dorsal", "ventral", "anterior", "posterior"). | ‘montage’ |
surface | str | fsaverage mesh to render on. One of "pial" (default), "inflated", "white", "sphere". | ‘pial’ |
template | str | fsaverage resolution ("fsaverage3" … "fsaverage"). Default "fsaverage5". | ‘fsaverage5’ |
threshold | float or str | Absolute cutoff (0.3) or percentile string ("95%"). | None |
cmap | str | Matplotlib colormap. Default "RdBu_r". | ‘RdBu_r’ |
vmin, vmax | float | Colormap range. Defaults to symmetric ±max-abs. | required |
transparency | BrainData, Nifti1Image, str, Path, or “auto” | Binary mask used to NaN-out vertices outside the mask so the background shines through. "auto" uses BrainData.mask. | ‘auto’ |
bg_on_data | bool | Whether to multiply data by background. | False |
colorbar | bool | Show a single shared colorbar. Default True. | True |
colorbar_orientation | str | "horizontal" (default) or "vertical". | ‘horizontal’ |
figsize | tuple | Figure size. Default (10, 8). | (10, 8) |
title | str | Figure title. | None |
radius_mm | float | vol_to_surf sampling radius. Default 3.0. | 3.0 |
interpolation | str | vol_to_surf interpolation. Default "linear". | ‘linear’ |
zoom | float | Zoom factor for each 3D axis (Axes3D.set_box_aspect(zoom=...)). Default 1.2; try 1.4 for the tightest clean framing. | 1.2 |
axes | ndarray of Axes3D | Pre-existing 3D axes to draw into. Shape should be (len(view), len(hemi)). | None |
save | str | Path to save the figure. | None |
Returns:
| Type | Description |
|---|---|
| matplotlib.figure.Figure |
Modules¶
adjacency¶
Adjacency matrix visualization — stacked plots, distance, and silhouette.
Methods:
| Name | Description |
|---|---|
plot_between_label_distance | Heatmap of average pairwise distance between every label pair. |
plot_mean_label_distance | Violin plot of within- vs between-label distances. |
plot_silhouette | Silhouette plot indicating between- vs within-label distance. |
plot_stacked_adjacency | Create stacked adjacency to illustrate similarity. |
Methods¶
plot_between_label_distance¶
plot_between_label_distance(distance, labels, *, ax = None, permutation_test = True, n_permute = 5000, **kwargs)Heatmap of average pairwise distance between every label pair.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a group label for each row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, also compute mean-difference and p-value matrices. | True | |
n_permute | Number of permutations. | 5000 | |
**kwargs | Passed to seaborn.heatmap. | {} |
Returns:
| Type | Description |
|---|---|
| Without permutation_test: (long_df, within_mean_df) | |
| With permutation_test: (long_df, within_mean_df, mean_diff_df, p_df) | |
All frames are polars DataFrames. long_df has columns | |
| [Distance, Group, Comparison]. The three square-matrix-like frames | |
| are long format with columns [label1, label2, ] so they can | |
| be pivoted to a matrix if needed. |
plot_mean_label_distance¶
plot_mean_label_distance(distance, labels, *, ax = None, permutation_test = False, n_permute = 5000, fontsize = 18, **kwargs)Violin plot of within- vs between-label distances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a group label for each row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, run a two-sample permutation test per group. | False | |
n_permute | Number of permutations. | 5000 | |
fontsize | Font size for plot labels. | 18 | |
**kwargs | Passed to seaborn.violinplot. | {} |
Returns:
| Type | Description |
|---|---|
| pl.DataFrame with columns [Distance, Group, Type] in long format. | |
| If permutation_test=True, returns (pl.DataFrame, dict of per-group stats). |
plot_silhouette¶
plot_silhouette(distance, labels, *, ax = None, permutation_test = True, n_permute = 5000, colors = None, figsize = (6, 4))Silhouette plot indicating between- vs within-label distance.
Uses the simplified silhouette definition from the original nltools implementation: within(i) = mean distance to other points in the same cluster; between(i) = mean distance to all points in other clusters (not the strict Rousseeuw min-over-clusters). Score is (between - within) / max(between, within).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
distance | Square pairwise distance matrix (np.ndarray or polars DataFrame). | required | |
labels | Array-like of length N giving a cluster label per row/column. | required | |
ax | Matplotlib axis to plot on (optional). | None | |
permutation_test | If True, run a one-sample permutation test per cluster on positive-mean silhouette scores. | True | |
n_permute | Number of permutations. | 5000 | |
colors | Optional list of RGB triplets, one per cluster (default: seaborn ‘hls’ palette). | None | |
figsize | Figure size tuple. Default (6, 4). | (6, 4) |
Returns:
| Type | Description |
|---|---|
| pl.DataFrame with columns [label, mean_silhouette]. If permutation_test | |
is True, adds a p column (1.0 for clusters with non-positive mean). |
plot_stacked_adjacency¶
plot_stacked_adjacency(adjacency1, adjacency2, normalize = True, **kwargs)Create stacked adjacency to illustrate similarity.
adjacency1 is drawn in the upper triangle and adjacency2 in the lower,
consistently whether or not normalize is set.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adjacency1 | Adjacency instance shown in the upper triangle. | required | |
adjacency2 | Adjacency instance shown in the lower triangle. | required | |
normalize | Normalize matrices before stacking. Default True. | True | |
**kwargs | Passed through to seaborn.heatmap. | {} |
Returns:
| Type | Description |
|---|---|
| matplotlib axes with the stacked heatmap. |
brain¶
Brain visualization — surface plots, flatmaps, and interactive viewers.
Methods:
| Name | Description |
|---|---|
plot_flatmap | Plot brain data on cortical flatmap. |
plot_interactive_brain | Create an interactive brain visualization with nilearn. |
plot_surf | Plot volumetric data on fsaverage surfaces in a tight 2×2 montage. |
Methods¶
plot_flatmap¶
plot_flatmap(brain, *, threshold = None, cmap = 'RdBu_r', vmax = None, vmin = None, template = 'fsaverage5', with_curvature = True, curvature_contrast = 0.5, curvature_brightness = 0.5, transparency = 'auto', colorbar = True, colorbar_orientation = 'horizontal', figsize = (12, 6), title = None, radius_mm = 3.0, interpolation = 'linear', axes = None, save = None)Plot brain data on cortical flatmap.
Projects MNI152 volumetric data onto an fsaverage surface and renders as a 2D flattened cortical map. Uses nilearn’s vol_to_surf for projection and matplotlib’s tripcolor for rendering.
This function provides publication-quality flatmap visualizations without requiring external dependencies like pycortex.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData, nibabel Nifti1Image, or file path to NIfTI image. Data must be in MNI152 space. | required | |
threshold | float or str | Values below this absolute threshold are masked. Can be a float or percentile string like ‘95%’. Defaults to None (no threshold). | None |
cmap | str | Matplotlib colormap for data. Defaults to ‘RdBu_r’ (diverging red-blue). | ‘RdBu_r’ |
vmax | float | Maximum value for colormap. If None, uses symmetric max of absolute values. | None |
vmin | float | Minimum value for colormap. If None and vmax is set, uses -vmax for diverging maps. | None |
template | str | fsaverage resolution. Options: ‘fsaverage3’ (642 vertices), ‘fsaverage4’ (2562), ‘fsaverage5’ (10242, default), ‘fsaverage6’ (40962), ‘fsaverage’ (163842, full resolution). | ‘fsaverage5’ |
with_curvature | bool | Show sulcal/gyral pattern as grayscale background. Defaults to True. | True |
curvature_contrast | float | Contrast of curvature (0=flat gray, 1=full contrast). Defaults to 0.5. | 0.5 |
curvature_brightness | float | Mean brightness of curvature (0=dark, 1=bright). Defaults to 0.5. | 0.5 |
transparency | BrainData, Nifti1Image, str, Path, or “auto” | Binary mask used to render vertices outside the mask as transparent (so the curvature shows through). "auto" (default) uses the input BrainData’s .mask when available, matching the behavior of the volumetric .plot(). Pass None to disable masking entirely. | ‘auto’ |
colorbar | bool | Show colorbar. Defaults to True. | True |
colorbar_orientation | str | ‘horizontal’ or ‘vertical’. Defaults to ‘horizontal’. | ‘horizontal’ |
figsize | tuple | Figure size (width, height). Defaults to (12, 6). | (12, 6) |
title | str | Figure title. Defaults to None. | None |
radius_mm | float | Sampling radius in mm for vol_to_surf projection. Larger values provide smoother projections. Defaults to 3.0. | 3.0 |
interpolation | str | Interpolation for vol_to_surf. Options: ‘linear’, ‘nearest_most_frequent’. Defaults to ‘linear’. | ‘linear’ |
axes | Axes | Existing axes to plot on. If None, creates new figure. Defaults to None. | None |
save | str | File path to save figure. Defaults to None. | None |
Returns:
| Type | Description |
|---|---|
| matplotlib.figure.Figure: The figure containing the flatmap. |
Examples:
Basic flatmap with default settings:
>>> from nltools.plotting import plot_flatmap
>>> from nltools.data import BrainData
>>> brain = BrainData('stats.nii.gz')
>>> fig = plot_flatmap(brain)Thresholded with custom colormap:
>>> fig = plot_flatmap(brain, threshold=2.5, cmap='hot')Percentile threshold, no curvature:
>>> fig = plot_flatmap(brain, threshold='95%', with_curvature=False)High resolution for publication:
>>> fig = plot_flatmap(brain, template='fsaverage6', figsize=(16, 8))
>>> fig.savefig('flatmap.pdf', dpi=300)Note
Data is projected from MNI152 space to fsaverage surface space. Small alignment differences are expected at boundaries.
Higher resolution templates (fsaverage6, fsaverage) produce sharper images but take longer to render.
The flat surfaces are cached by nilearn after first download (~50MB for fsaverage5).
plot_interactive_brain¶
plot_interactive_brain(brain, *, threshold = 1e-06, surface = False, percentile_threshold = False, anatomical = None, **kwargs)Create an interactive brain visualization with nilearn.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData | a BrainData instance of 1d or 2d shape (i.e. 3d or 4d volume) | required |
threshold | float / str | threshold to initialize the visualization, may be a percentile string; default 1e-6 | 1e-06 |
surface | bool | whether to create a surface-based plot; default False | False |
percentile_threshold | bool | whether to interpret threshold values as percentiles | False |
kwargs | optional arguments to nilearn.view_img or nilearn.view_img_on_surf | {} |
Returns:
| Type | Description |
|---|---|
| None (renders widgets inline) |
plot_surf¶
plot_surf(brain, *, hemi = 'both', view = 'montage', surface = 'pial', template = 'fsaverage5', threshold = None, cmap = 'RdBu_r', vmin = None, vmax = None, transparency = 'auto', bg_on_data = False, colorbar = True, colorbar_orientation = 'horizontal', figsize = (10, 8), title = None, radius_mm = 3.0, interpolation = 'linear', zoom = 1.2, axes = None, save = None)Plot volumetric data on fsaverage surfaces in a tight 2×2 montage.
Like nilearn’s plot_img_on_surf but with actually-tight framing
(via Axes3D.set_box_aspect(zoom=...) + set_axis_off), an
auto-applied transparency mask (same convention as plot_flatmap),
and a single shared colorbar instead of one-per-subplot.
The grid is len(view) × len(hemi) — rows = views, cols = hemispheres.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
brain | BrainData, nibabel Nifti1Image, or file path (MNI-space). | required | |
hemi | str or list | "left", "right", "both" (default), or a list subset like ["left"]. | ‘both’ |
view | str or list | "montage" (default, → ["lateral", "medial"]), a single view string, or any list subset of ("lateral", "medial", "dorsal", "ventral", "anterior", "posterior"). | ‘montage’ |
surface | str | fsaverage mesh to render on. One of "pial" (default), "inflated", "white", "sphere". | ‘pial’ |
template | str | fsaverage resolution ("fsaverage3" … "fsaverage"). Default "fsaverage5". | ‘fsaverage5’ |
threshold | float or str | Absolute cutoff (0.3) or percentile string ("95%"). | None |
cmap | str | Matplotlib colormap. Default "RdBu_r". | ‘RdBu_r’ |
vmin, vmax | float | Colormap range. Defaults to symmetric ±max-abs. | required |
transparency | BrainData, Nifti1Image, str, Path, or “auto” | Binary mask used to NaN-out vertices outside the mask so the background shines through. "auto" uses BrainData.mask. | ‘auto’ |
bg_on_data | bool | Whether to multiply data by background. | False |
colorbar | bool | Show a single shared colorbar. Default True. | True |
colorbar_orientation | str | "horizontal" (default) or "vertical". | ‘horizontal’ |
figsize | tuple | Figure size. Default (10, 8). | (10, 8) |
title | str | Figure title. | None |
radius_mm | float | vol_to_surf sampling radius. Default 3.0. | 3.0 |
interpolation | str | vol_to_surf interpolation. Default "linear". | ‘linear’ |
zoom | float | Zoom factor for each 3D axis (Axes3D.set_box_aspect(zoom=...)). Default 1.2; try 1.4 for the tightest clean framing. | 1.2 |
axes | ndarray of Axes3D | Pre-existing 3D axes to draw into. Shape should be (len(view), len(hemi)). | None |
save | str | Path to save the figure. | None |
Returns:
| Type | Description |
|---|---|
| matplotlib.figure.Figure |
decomposition¶
ICA/PCA component viewer — interactive decomposition explorer.
Methods:
| Name | Description |
|---|---|
component_viewer | Interactively view the results of a BrainData.decompose() run. |
Methods¶
component_viewer¶
component_viewer(output, tr = 2.0)Interactively view the results of a BrainData.decompose() run.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output | (dict) output dictionary from running BrainData.decompose() | required | |
tr | (float) repetition time of data | 2.0 |
Returns:
| Type | Description |
|---|---|
| None (renders interactive widgets inline) |
prediction¶
Model output visualization — ROC, SVM margin, regression, and logistic plots.
Methods:
| Name | Description |
|---|---|
plot_dist_from_hyperplane | Plot SVM Classification Distance from Hyperplane. |
plot_probability | Plot Classification Probability. |
plot_roc | Plot 1-Specificity by Sensitivity. |
plot_scatter | Plot Prediction Scatterplot. |
Methods¶
plot_dist_from_hyperplane¶
plot_dist_from_hyperplane(stats_output)Plot SVM Classification Distance from Hyperplane.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid of distance from hyperplane |
plot_probability¶
plot_probability(stats_output)Plot Classification Probability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid scatterplot |
plot_roc¶
plot_roc(fpr, tpr)Plot 1-Specificity by Sensitivity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fpr | false positive rate from Roc.calculate | required | |
tpr | true positive rate from Roc.calculate | required |
Returns:
| Type | Description |
|---|---|
| a matplotlib Figure |
plot_scatter¶
plot_scatter(stats_output)Plot Prediction Scatterplot.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stats_output | pandas DataFrame with prediction output | required |
Returns:
| Type | Description |
|---|---|
| a seaborn FacetGrid scatterplot |