plotting.images

plotting.images

Attributes¶

Name	Description
`GRID_FRAME_QUALITY`
`GRID_LOSSLESS_MAX_PIXELS`
`MRSI_FRAME_QUALITY`
`VoxelCoord`
`VoxelCoordsInput`
`VoxelStyle`
`VoxelStylesInput`

Classes¶

Name	Description
VoxelOverlayParams	Keyword arguments accepted by `overlay_voxel_on_T1`.

VoxelOverlayParams¶

plotting.images.VoxelOverlayParams()

Keyword arguments accepted by overlay_voxel_on_T1.

Attributes¶

Name	Description
`blocky`
`image_kwargs`
`overlay_kwargs`
`scale_overlay`
`show_overlay`
`title`
`voxel_kwargs`

Functions¶

Name	Description
display_images	Display a grid of 2D/3D/4D images, with a slice slider for 3D/4D input.
display_nifti	Orient a NIfTI image and display it via `display_images`.
draw_voxel_overlays_on_ax	Draw voxel outlines on an axis.
fast_bounds	Quickly estimate lower/upper display bounds by sampling a subset of the data.
get_voxel_visible_slice_range	Return inclusive third-dimension slice range where a voxel is visible.
inspect_MRSI_spectra	Display an interactive widget to inspect MRSI spectra over a T1 image.
mrsi_spectra_for_display	Build the exact ppm axis and spectra grid `inspect_MRSI_spectra` displays.
overlay_image_data_on_T1	Display T1, resampled data, and overlay images side by side with a slice slider.
overlay_nifti_data_on_T1	Resample a data NIfTI into T1 space and overlay it on the T1 image.
overlay_voxel_on_T1	Overlay one or more voxels (and optionally MRSI data) on a T1 slice.

display_images¶

plotting.images.display_images(
    images,
    titles=None,
    fig_title='',
    cmap=None,
    imshow_kws=None,
    colorbar=False,
    colorbar_kws=None,
    fig_kws=None,
    vmin=None,
    vmax=None,
    v_percentile=1.0,
    zeros_as_nan=True,
    zooms=None,
    panel_height=None,
    grid_max_height=None,
    **kwargs,
)

Display a grid of 2D/3D/4D images, with a slice slider for 3D/4D input.

The panels are rendered straight to images at the data’s own resolution and handed to an interactive widget that draws the titles and colorbar around them as HTML; no matplotlib Figure is involved, which is why nothing is returned.

Parameters¶

Name	Type	Description	Default
images	ndarray or list	Image data (2D, 3D, or 4D) or a list of arrays to stack along a new last axis.	required
titles	list[str]	Titles for each image, by default None.	`None`
fig_title	str	Overall figure title, by default “”.	`''`
cmap	str	Colormap to use. Defaults to `rcParams["image.cmap"]`.	`None`
imshow_kws	dict	Accepted and ignored: there is no `imshow` call left to forward them to. Kept so existing call sites keep working.	`None`
colorbar	bool	Whether to display a colorbar, by default False.	`False`
colorbar_kws	dict	Only the `"mode"` key is read, either `"single"` (one colorbar for the grid) or `"each"` (one per panel, autoscaled to that panel and slice). Remaining keys are ignored -- the colorbar is HTML now, not a matplotlib artist.	`None`
fig_kws	dict	Accepted and ignored: there is no `Figure` left to configure. Kept so existing call sites keep working.	`None`
vmin	float	Lower display bound. Estimated from the data if omitted.	`None`
vmax	float	Upper display bound. Estimated from the data if omitted.	`None`
v_percentile	float	Percentile used to estimate `vmin`/`vmax` when not given, by default 1.0.	`1.0`
zeros_as_nan	bool	If True, zeros are treated as NaN: kept out of the `vmin`/`vmax` estimate so the background cannot drag the scaling down, and rendered transparent rather than as the colormap’s low end. By default True.	`True`
zooms	tuple[float, float]	Physical (row, col) voxel edge lengths of the displayed slice, e.g. from `utils.nifti.get_display_zooms`. When given, panels are rendered with an aspect ratio that matches real anatomy instead of one square pixel per voxel; the through-plane spacing is irrelevant since only one 2D slice is ever on screen at a time. Defaults to the pixel-count aspect ratio (square voxels) when omitted.	`None`
panel_height	str or float	How tall a single panel may grow, as a CSS length (`"30rem"`, `"400px"`) or a bare number read as rem. The compact default suits a row of low-resolution panels; raise it to read a high-resolution anatomical series. Defaults to `rcParams["grid.panel_height"]`.	`None`
grid_max_height	str or float	How tall the panel box may grow before it scrolls, same units. Worth raising alongside `panel_height` for a tall single-column view. Defaults to `rcParams["grid.max_height"]`.	`None`
**kwargs		Accepted and ignored: axis parameters such as `aspect`, `xlabel` or `xticks` have no Axes to apply to. Kept so existing call sites keep working.	`{}`

Returns¶

Name	Type	Description
	None	The grid is displayed as a widget. For a single-slice input the widget simply has no slider.

display_nifti¶

plotting.images.display_nifti(nii, orientation=None, **kwargs)

Orient a NIfTI image and display it via display_images.

Parameters¶

Name	Type	Description	Default
nii	nibabel.spatialimages.SpatialImage or GESeries.NiiBase	The NIfTI image (or wrapper) to display.	required
orientation	tuple[str, str, str]	Target axis orientation codes, by default None.	`None`
**kwargs		Additional keyword arguments forwarded to `display_images`.	`{}`

Returns¶

Name	Type	Description
	None	See `display_images` -- the image grid is displayed, not returned.

draw_voxel_overlays_on_ax¶

plotting.images.draw_voxel_overlays_on_ax(
    ax,
    voxel_coords,
    mrsi_to_display_affine,
    voxel_kwargs=None,
)

Draw voxel outlines on an axis.

mrsi_to_display_affine must map MRSI voxel indices to display pixel coordinates (row, col) as produced by orient_nifti. Use utils.nifti.get_display_affine to obtain the display affine for the T1, then compute mrsi_to_display = inv(display_affine) @ MRSI.RAW_exp.nii.affine.

The voxel’s four in-plane corners (voxel index +/- 0.5 along axes 0 and 1) are projected through the full affine, so this is correct for display affines that transpose or rotate the axes -- reading the affine diagonal is not, because get_display_affine bakes an axis transpose into an anti-diagonal affine.

fast_bounds¶

plotting.images.fast_bounds(
    data,
    max_target_samples=20000,
    p_lower=1.0,
    p_upper=99.0,
    exclude_zeros=False,
    max_discrete_levels=16,
)

Quickly estimate lower/upper display bounds by sampling a subset of the data.

The sample is drawn before the data is filtered, so the cost scales with max_target_samples rather than with the size of data. Continuous data is then summarised by percentiles; discrete data -- a label map or a binary mask -- by its exact min/max, since percentiles collapse onto a single level once the background outweighs the labels.

Parameters¶

Name	Type	Description	Default
data	ndarray	The input data array from which to estimate the bounds.	required
max_target_samples	int	The number of voxels drawn for the estimate. Defaults to 20000, which keeps the percentile standard error well below display resolution.	`20000`
p_lower	float	The lower percentile to calculate. Defaults to 1.0 (the 1st percentile).	`1.0`
p_upper	float	The upper percentile to calculate. Defaults to 99.0 (the 99th percentile).	`99.0`
exclude_zeros	bool	If True, drop exact zeros before taking the percentiles. Background voxels are usually exactly 0 and would otherwise dominate the lower percentile and flatten the contrast of the anatomy itself. Ignored when the sample is all zeros -- a warning is logged and the zeros are kept so the bounds stay finite. Defaults to False.	`False`
max_discrete_levels	int	Arrays whose sample holds at most this many distinct integer-valued levels are read as label maps and bounded by min/max instead of by percentiles. Defaults to 16.	`16`

Returns¶

Name	Type	Description
	tuple[float, float]	The estimated lower and upper bounds for visualization, always with `upper > lower`.

get_voxel_visible_slice_range¶

plotting.images.get_voxel_visible_slice_range(
    voxel_coord,
    mrsi_to_display_affine,
    n_slices=None,
)

Return inclusive third-dimension slice range where a voxel is visible.

inspect_MRSI_spectra¶

plotting.images.inspect_MRSI_spectra(
    T1,
    MRSI,
    blocky=True,
    magnitude=False,
    autophase=True,
)

Display an interactive widget to inspect MRSI spectra over a T1 image.

Shows the T1 image with an MRSI overlay and a spectrum plot; clicking, the keyboard arrows, or the slice slider update the selected voxel and its spectrum. All interaction runs client-side (no Python kernel needed after the widget is displayed): every anatomical slice is pre-rendered, and every voxel’s spectrum is precomputed into a single buffer embedded in the widget.

Parameters¶

Name	Type	Description	Default
T1	GESeries.MRISeries	The T1-weighted anatomical series.	required
MRSI	GESeries.MRSISeries	The MRSI series to inspect.	required
blocky	bool	If True, resample the raw (blocky) MRSI grid rather than the interpolated NIfTI, by default True.	`True`
magnitude	bool	If True, display the magnitude spectrum, by default False.	`False`
autophase	bool	If True (and `magnitude` is False), phase each voxel independently before display, by default True. See `mrsi_spectra_for_display` for why this is done per voxel rather than through a single global fit.	`True`

mrsi_spectra_for_display¶

plotting.images.mrsi_spectra_for_display(
    MRSI,
    *,
    magnitude=False,
    autophase=True,
)

Build the exact ppm axis and spectra grid inspect_MRSI_spectra displays.

Split out of the widget so the displayed numbers can be inspected directly — the inspector ships precisely this array, so plotting spectra[x, y, z] against ppm reproduces a voxel’s panel exactly:

ppm, spectra = mrsi_spectra_for_display(mrsi) # doctest: +SKIP plt.plot(ppm, spectra[8, 8, 8]) # doctest: +SKIP

Parameters¶

Name	Type	Description	Default
MRSI	GESeries.MRSISeries	The MRSI series to read spectra from.	required
magnitude	bool	If True, return the magnitude spectrum, by default False.	`False`
autophase	bool	If True (and `magnitude` is False), phase each voxel independently, by default True.	`True`

Returns¶

Name	Type	Description
ppm	ndarray	1-D ppm axis, spanning the full acquired sweep.
spectra	ndarray	Real-valued grid indexed `[x, y, mrsi_slice, point]`, matching the voxel coordinates the widget’s picker reports.

overlay_image_data_on_T1¶

plotting.images.overlay_image_data_on_T1(
    t1_images,
    data_images=None,
    mask=None,
    mask_contour=None,
    only_overlay=False,
    mask_kwargs=None,
    engine=None,
    ax=None,
    **kwargs,
)

Display T1, resampled data, and overlay images side by side with a slice slider.

Parameters¶

Name	Type	Description	Default
t1_images	ndarray	T1-weighted anatomical image data.	required
data_images	ndarray	Data image, resampled into T1 space, to overlay. Required unless `ax` is given for a T1-only draw.	`None`
mask	ndarray	Boolean mask applied to the overlay data, by default None.	`None`
mask_contour	ndarray or bool	Mask (or `True` to reuse `mask`) whose contour is drawn on the overlay axis. Matplotlib engine only -- the raster engine has no cheap contour equivalent and warns and ignores it.	`None`
only_overlay	bool	If True, only show the overlay axis instead of T1, data, and overlay side by side, by default False.	`False`
mask_kwargs	dict	Keyword arguments customizing the mask contour’s appearance.	`None`
engine	('raster', 'matplotlib')	Rendering path. Defaults to `"raster"` (fast, no `Figure`) unless `ax` is given, which forces matplotlib -- there is no client-side `Axes` for a raster widget to draw into. If both are given, `ax` wins and a mismatched `engine="raster"` is ignored with a warning.	`"raster"`
ax	matplotlib.axes.Axes	Draw a single overlay panel onto this axis instead of displaying the T1/data/overlay widget. Implies the matplotlib engine.	`None`
**kwargs		Additional keyword arguments forwarded to the resolved rendering path. The raster engine also takes `panel_height` and `grid_max_height`, which size the widget exactly as they do in `display_images`.	`{}`

Returns¶

Name	Type	Description
	tuple[Figure, list[Axes]] or tuple[list[AxesImage], QuadContourSet \| None] or None	`ax` given: the plotted images and contours. `engine="matplotlib"` with no `ax`: `(Figure, axes)` for single-slice input, `None` (widget displayed) for multi-slice. Raster engine (default): always `None` (widget displayed), single-slice included.

overlay_nifti_data_on_T1¶

plotting.images.overlay_nifti_data_on_T1(
    t1_nii,
    data_nii,
    orientation=None,
    display_plane=None,
    resample_kwargs=None,
    mask=None,
    **kwargs,
)

Resample a data NIfTI into T1 space and overlay it on the T1 image.

Parameters¶

Name	Type	Description	Default
t1_nii	nibabel.spatialimages.SpatialImage	Anatomical T1 NIfTI image to overlay onto.	required
data_nii	nibabel.spatialimages.SpatialImage	Data NIfTI image to resample and overlay.	required
orientation	tuple[str, str, str]	Target axis orientation codes, by default None.	`None`
display_plane	utils.nifti.DISPLAY_PLANES	Anatomical plane to display, by default None.	`None`
resample_kwargs	dict	Extra keyword arguments passed to `resample_and_orient_nifti`.	`None`
mask	ndarray or GESeries.NiiBase	Boolean mask applied to the data before or after resampling, depending on whether its shape matches the data or the T1 image.	`None`
**kwargs		Additional keyword arguments forwarded to `overlay_image_data_on_T1`.	`{}`

Returns¶

Name	Type	Description
	tuple[Figure, list[Axes]] or None	See `overlay_image_data_on_T1`.

overlay_voxel_on_T1¶

plotting.images.overlay_voxel_on_T1(
    t1,
    MRSI,
    voxel_coords,
    ax=None,
    figsize=(6, 6),
    **kwargs,
)

Overlay one or more voxels (and optionally MRSI data) on a T1 slice.

Displays a slice of a T1-weighted MRI image, overlays voxel(s) at the specified coordinates, and optionally overlays MRSI data resampled into T1 space. If ax is omitted, creates its own figure and axes.

Parameters¶

Name	Type	Description	Default
t1	GESeries.MRISeries	The T1-weighted MRI series containing the anatomical image data.	required
MRSI	GESeries.MRSISeries	The MRSI series containing the spectroscopic imaging data.	required
voxel_coords	tuple[int, int, int] or ndarray or list[tuple[int, int, int]]	The coordinates of the voxel(s) in MRSI space. If a list is given, all voxels must share the same z-coordinate.	required
ax	matplotlib.axes.Axes	The axis on which to plot the image and overlays. If `None`, a new figure and axis are created.	`None`
figsize	tuple[int, int]	The size of the figure in inches, used only when `ax` is `None`. Defaults to (6, 6).	`(6, 6)`
**kwargs	Unpack[VoxelOverlayParams]	show_overlay : bool, optional Whether to overlay the MRSI data on the T1 image. Defaults to True. scale_overlay : bool, optional Whether to scale the MRSI data to `[0, 1]` for better visualization when overlaid. Defaults to True. title : str, optional Title for the plot. Defaults to one naming the anatomical slice index. voxel_kwargs : dict or list[dict], optional Keyword arguments customizing the voxel rectangle(s)’ appearance. If a list, it must match the number of voxels. Defaults to None. image_kwargs : dict, optional Keyword arguments customizing the T1 image’s appearance. overlay_kwargs : dict, optional Keyword arguments customizing the MRSI overlay’s appearance.	`{}`

Returns¶

Name	Type	Description
	tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] or matplotlib.axes.Axes	The created `(fig, ax)` if `ax` was `None`, otherwise the axis with the plotted image and overlays.

Notes¶

The MRSI data is resampled to T1 space using the provided affine transformations, then scaled to [0, 1] if scale_overlay is True. The voxel rectangle(s) are drawn at the specified coordinates, adjusted to align with the anatomical space.