confusius.xarray¶

Save the DataArray to file, dispatching by extension.

Supported formats:

• NIfTI (.nii, .nii.gz): saved via save_nifti.
• Zarr (.zarr): saved via xarray.DataArray.to_zarr.

Parameters:

• path ¶

  (str or Path) –

  Output path. The extension determines the format.

• **kwargs ¶

  (Any, default: {} ) –

  Additional keyword arguments forwarded to the underlying saver.

Examples:

>>> import xarray as xr
>>> import numpy as np
>>> import confusius  # noqa: F401
>>> data = xr.DataArray(
...     np.zeros((10, 32, 1, 64)), dims=["time", "k", "j", "i"]
... )
>>> data.fusi.save("recording.nii.gz")

Apply a world-space affine to a DataArray's world coordinates.

The transform is composed into the DataArray's VoxelToWorldIndex, derived world coordinates are regenerated, and existing attrs["affines"] entries are re-expressed against the new world frame.

Parameters:

• affine ¶

  ((4, 4) numpy.ndarray or str) –

  Homogeneous world-space affine matrix to apply. If a string, it is looked up as a key in self.attrs["affines"].

• inplace ¶

  (bool, default: False ) –

  Whether to modify the DataArray in-place.

Returns:

• DataArray –

  The DataArray with updated spatial coordinates and attrs["affines"]. When affine is a string, that key is dropped from the result.

Raises:

• ValueError –

  If self lacks voxel-to-world geometry, if affine shape does not match the DataArray's voxel-to-world affine, or if affine is a string and self has no "affines" entry in attrs.

• KeyError –

  If affine is a string not present in self.attrs["affines"].

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> import confusius  # noqa: F401
>>> data = xr.DataArray(
...     np.zeros((3, 4)),
...     dims=["j", "i"],
...     coords={"j": np.arange(3), "i": np.arange(4)},
... )
>>> data = data.fusi.affine.set_voxel_to_world(np.eye(3))
>>> shift = np.eye(3)
>>> shift[:2, 2] = [10.0, 5.0]
>>> result = data.fusi.affine.apply(shift)
>>> float(result.fusi.affine.voxel_to_world[0, 2])
10.0

Rebase voxel coordinates to dense positions without moving world coordinates.

See reindex_voxels for details.

Parameters:

• inplace ¶

  (bool, default: False ) –

  Whether to modify the wrapped DataArray in-place.

Returns:

• DataArray –

  DataArray with voxel coordinates rebased to 0, 1, ..., dim - 1 and an updated voxel_to_world affine. World coordinates are unchanged.

Raises:

• ValueError –

  If self lacks voxel-to-world geometry, or if world spacing is undefined for any voxel dimension.

Examples:

>>> import numpy as np
>>> import confusius  # noqa: F401
>>> from confusius.xarray import create_voxeldata
>>> base = create_voxeldata(
...     np.zeros((5, 5)), dims=("j", "i"), voxel_to_world=np.eye(4)
... )
>>> data = base.isel(j=slice(2, 5), i=slice(1, 5))
>>> reindexed = data.fusi.affine.reindex_voxels()
>>> reindexed.coords["j"].values
array([0, 1, 2])
>>> float(reindexed.coords["y"].isel(j=0, i=0, k=0))
2.0

Rebase voxel coordinates onto reference's voxel labels.

See reindex_voxels_like for details.

Parameters:

• reference ¶

  (DataArray) –

  DataArray whose voxel labels and affine self should adopt.

• atol ¶

  (float, default: 1e-6 ) –

  Absolute tolerance, in reference's physical units, for the world-coordinate alignment check between self and reference.

• inplace ¶

  (bool, default: False ) –

  Whether to modify the wrapped DataArray in-place.

Returns:

• DataArray –

  self with voxel coordinates and voxel_to_world replaced by reference's. World coordinates are unchanged.

Raises:

• ValueError –

  If self or reference lacks voxel-to-world geometry, if their voxel dimensions or shapes differ, or if their world coordinates do not match within atol.

Replace the world-space unit, rebuilding the VoxelToWorldIndex.

Parameters:

• units ¶

  (str) –

  New physical unit shared by every world coordinate.

• inplace ¶

  (bool, default: False ) –

  Whether to modify the wrapped DataArray in-place.

Returns:

• DataArray –

  DataArray with rebuilt VoxelToWorldIndex-backed coordinates.

Replace voxel-to-world geometry.

Parameters:

• voxel_to_world ¶

  (ArrayLike) –

  Homogeneous affine mapping native voxel coordinates to world coordinates.

• units ¶

  (str, default: None ) –

  New physical unit shared by every world coordinate. If not provided, the existing unit is kept, or "mm" if there is none yet (e.g. when attaching geometry for the first time onto a plain, not-yet-indexed DataArray).

• inplace ¶

  (bool, default: False ) –

  Whether to modify the wrapped DataArray in-place.

Returns:

• DataArray –

  DataArray with rebuilt VoxelToWorldIndex-backed coordinates.

Return the affine mapping self's world space into other's.

Computes inv(other.attrs["affines"][via]) @ self.attrs["affines"][via], giving the transform from self's world frame to other's.

Parameters:

• other ¶

  (DataArray) –

  The scan whose world space is the target.

• via ¶

  (str) –

  Key into attrs["affines"] naming the shared intermediate coordinate space (e.g. "world_to_lab").

Returns:

• (ndarray, shape(4, 4)) –

  Homogeneous affine matrix mapping self's world coordinates to other's world coordinates.

Raises:

• KeyError –

  If via is not present in either scan's attrs["affines"].

• ValueError –

  If either scan has no "affines" entry in attrs.

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> import confusius  # noqa: F401
>>> eye = np.eye(4)
>>> a = xr.DataArray(np.zeros((2, 2)), attrs={"affines": {"to_world": eye}})
>>> b = xr.DataArray(np.zeros((2, 2)), attrs={"affines": {"to_world": eye}})
>>> np.allclose(a.fusi.affine.to(b, via="to_world"), np.eye(4))
True

Fit a seed-based correlation map.

Convenience wrapper around SeedBasedMaps that constructs the estimator, calls SeedBasedMaps.fit on the wrapped DataArray, and returns the fitted estimator.

Parameters:

• seed_masks ¶

  (DataArray, default: None ) –

  Integer label map defining the seed region(s). See SeedBasedMaps for accepted formats. Mutually exclusive with seed_signals.

• seed_signals ¶

  (DataArray, default: None ) –

  Pre-computed (time, ...) seed signals used directly for correlation. When provided, seed extraction from the data is skipped. Mutually exclusive with seed_masks.

• labels_reduction ¶

  ((mean, sum, median, min, max, var, std), default: "mean" ) –

  Aggregation function applied across voxels within each seed region. Ignored when seed_signals is provided.

• clean_kwargs ¶

  (dict, default: None ) –

  Keyword arguments forwarded to clean. If not provided, no cleaning is applied.

Returns:

• SeedBasedMaps –

  Fitted estimator. Access maps_ and seed_signals_ on the returned object.

Examples:

>>> import numpy as np
>>> import xarray as xr
>>> import confusius  # noqa: F401
>>>
>>> data = xr.open_zarr("recording.zarr")["power_doppler"]
>>> seed_masks = xr.open_zarr("seed_masks.zarr")["masks"]
>>> mapper = data.fusi.connectivity.seed_map(seed_masks=seed_masks)

Reconstruct N-D volume from masked signals.

Reconstructs the full spatial volume from a DataArray of signals, which must have a space dimension. This is a convenience wrapper around confusius.extract.unmask().

Parameters:

• mask ¶

  (DataArray) –

  Boolean VoxelData mask array used for the original extraction. Provides native voxel dimensions and VoxelData geometry for reconstruction.

• fill_value ¶

  (float, default: 0.0 ) –

  Value to fill in non-masked voxels.

Returns:

• DataArray –

  Reconstructed VoxelData array with shape (..., k, j, i) where native voxel dimensions and VoxelData geometry come from the mask.

Examples:

>>> signals = data.fusi.extract.with_mask(mask)
>>> signals.dims
('time', 'space')
>>> reconstructed = signals.fusi.extract.unmask(mask)
>>> reconstructed.dims
('time', 'k', 'j', 'i')

Extract region-aggregated signals using an integer label map.

Parameters:

• labels ¶

  (DataArray) –

  Integer label map in one of two formats:

  • Flat label map: Spatial dims only, e.g. (k, j, i). Background voxels labeled 0; each unique non-zero integer identifies a distinct, non-overlapping region. The regions coordinate of the output holds the integer label values.
  • Stacked mask format: Has a leading mask dimension followed by spatial dims, e.g. (mask, k, j, i). Each layer has values in {0, region_id} and regions may overlap. The region coordinate of the output holds the mask coordinate values (e.g., region label).

• reduction ¶

  ((mean, sum, median, min, max, var, std), default: "mean" ) –

  Aggregation function applied across voxels in each region:

  • "mean": arithmetic mean.
  • "sum": sum of values.
  • "median": median value.
  • "min": minimum value.
  • "max": maximum value.
  • "var": variance.
  • "std": standard deviation.

Returns:

• DataArray –

  Array with spatial dimensions replaced by a region dimension. The region dimension has integer coordinates corresponding to each unique non-zero label in labels. All non-spatial dimensions are preserved.

  For example:

  • (time, k, j, i) → (time, region)
  • (time, pose, k, j, i) → (time, pose, region)
  • (k, j, i) → (region,)

Raises:

• ValueError –

  If labels dimensions don't match data's spatial dimensions, if coordinates don't match, or if reduction is not a valid option.

• TypeError –

  If labels is not integer dtype.

Examples:

>>> signals = data.fusi.extract.with_labels(labels)
>>> signals.dims
("time", "region")
>>> signals.coords["region"].values
array([1, 2, 3])
>>>
>>> # Sum per region instead of mean.
>>> sums = data.fusi.extract.with_labels(labels, reduction="sum")

Extract signals using a boolean or single-label integer mask.

Parameters:

• mask ¶

  (DataArray) –

  Mask defining which voxels to extract. Its dimensions define the spatial dimensions that will be flattened. Must have boolean dtype, or integer dtype with exactly one non-zero value (0 = background, one region id = foreground). The latter format is produced by get_masks. Coordinates must match data.

Returns:

• DataArray –

  Array with spatial dimensions flattened into a space dimension. All non-spatial dimensions are preserved. The space dimension has a MultiIndex storing spatial coordinates.

  For simple round-trip reconstruction, use .unstack("space") which re-creates the original DataArray using the smallest bounding box. For full mask shape reconstruction, use .fusi.extract.unmask().

Raises:

• ValueError –

  If mask dimensions don't match data's spatial dimensions.

• TypeError –

  If mask is not boolean dtype.

Examples:

>>> signals = data.fusi.extract.with_mask(mask)
>>> signals.dims
("time", "space")
>>>
>>> # Quick bounding box reconstruction
>>> bbox = signals.unstack("space")
>>>
>>> # Full mask shape reconstruction
>>> full = signals.fusi.extract.unmask(mask)

Process beamformed IQ into axial velocity volumes.

This method computes axial velocity volumes from beamformed IQ data using nested sliding windows. A first sliding window is used for clutter filtering. Inside each clutter-filtered window, axial velocity volumes are computed using a second sliding window.

Parameters:

• clutter_window_width ¶

  (int, default: None ) –

  Width of the sliding temporal window for clutter filtering, in volumes. If not provided, uses the chunk size of the IQ data along the temporal dimension.

• clutter_window_stride ¶

  (int, default: None ) –

  Stride of the sliding temporal window for clutter filtering, in volumes. If not provided, equals clutter_window_width.

• filter_method ¶

  ((svd_indices, svd_energy, svd_cumulative_energy, butterworth), default: "svd_indices" ) –

  Clutter filtering method to apply before velocity computation.

  • "svd_indices": Static SVD filter using singular vector indices.
  • "svd_energy": Adaptive SVD filter using singular vector energies.
  • "svd_cumulative_energy": Adaptive SVD filter using cumulative energies.
  • "butterworth": Butterworth frequency-domain filter.

• clutter_mask ¶

  ((k, j, i) xarray.DataArray, default: None ) –

  Boolean mask to define clutter regions. Only used by SVD-based clutter filters to compute clutter vectors from masked voxels. If not provided, all voxels are used. The mask spatial dimensions and coordinates must match the IQ data.

• low_cutoff ¶

  (int or float, default: None ) –

  Low cutoff for clutter filtering. Interpretation depends on filter_method. If not provided, uses method-specific defaults.

• high_cutoff ¶

  (int or float, default: None ) –

  High cutoff for clutter filtering. Interpretation depends on filter_method. If not provided, uses method-specific defaults.

• butterworth_order ¶

  (int, default: 4 ) –

  Order of Butterworth filter. Effective order is doubled due to forward-backward filtering.

• velocity_window_width ¶

  (int, default: None ) –

  Width of the sliding temporal window for velocity estimation, in volumes. If not provided, equals clutter_window_width.

• velocity_window_stride ¶

  (int, default: None ) –

  Stride of the sliding temporal window for velocity estimation, in volumes. If not provided, equals velocity_window_width.

• lag ¶

  (int, default: 1 ) –

  Temporal lag in volumes for autocorrelation computation. Must be positive.

• spatial_kernel ¶

  (int or tuple[int, int, int] or list[int], default: 3 ) –

  Size of the median filter kernel applied spatially to denoise. A scalar uses the same kernel size on all spatial axes; a length-3 sequence specifies (k, j, i) sizes directly. Values must be positive. Any even sizes are rounded up to the next odd size. If all sizes are 1, no spatial filtering is applied.

Returns:

• (clutter_windows * velocity_windows, k, j, i) xarray.DataArray –

  Axial velocity volumes with updated time coordinates, where clutter_windows is the number of clutter filter sliding windows and velocity_windows is the number of velocity sliding windows per clutter window. Velocity values are in meters per second.

Examples:

>>> import xarray as xr
>>> ds = xr.open_zarr("iq_data.zarr")
>>> iq = ds["iq"]
>>> velocity = iq.fusi.iq.process_to_axial_velocity(
...     clutter_window_width=50,
...     velocity_window_width=25,
... )

Process beamformed IQ into B-mode volumes.

This method computes B-mode volumes from beamformed IQ data using a single sliding temporal window. Unlike power Doppler, no clutter filtering is applied; the mean magnitude (not squared magnitude) of the IQ data within each window is computed.

Parameters:

• bmode_window_width ¶

  (int, default: None ) –

  Width of the sliding temporal window for B-mode integration, in volumes. If not provided, uses the chunk size of the IQ data along the temporal dimension.

• bmode_window_stride ¶

  (int, default: None ) –

  Stride of the sliding temporal window, in volumes. If not provided, equals bmode_window_width.

Returns:

• (windows, k, j, i) xarray.DataArray –

  B-mode volumes with updated time coordinates, where windows is the number of sliding windows.

Examples:

>>> import xarray as xr
>>> ds = xr.open_zarr("iq_data.zarr")
>>> iq = ds["iq"]
>>> bmode = iq.fusi.iq.process_to_bmode(bmode_window_width=50)

Process beamformed IQ into power Doppler volumes.

This method computes power Doppler volumes from beamformed IQ data using nested sliding windows. A first sliding window is used for clutter filtering. Inside each clutter-filtered window, power Doppler volumes are computed using a second sliding window.

Parameters:

• clutter_window_width ¶

  (int, default: None ) –

  Width of the sliding temporal window for clutter filtering, in volumes. If not provided, uses the chunk size of the IQ data along the temporal dimension.

• clutter_window_stride ¶

  (int, default: None ) –

  Stride of the sliding temporal window for clutter filtering, in volumes. If not provided, equals clutter_window_width.

• filter_method ¶

  ((svd_indices, svd_energy, svd_cumulative_energy, butterworth), default: "svd_indices" ) –

  Clutter filtering method to apply before power Doppler computation.

  • "svd_indices": Static SVD filter using singular vector indices.
  • "svd_energy": Adaptive SVD filter using singular vector energies.
  • "svd_cumulative_energy": Adaptive SVD filter using cumulative energies.
  • "butterworth": Butterworth frequency-domain filter.

• clutter_mask ¶

  ((k, j, i) xarray.DataArray, default: None ) –

  Boolean mask to define clutter regions. Only used by SVD-based clutter filters to compute clutter vectors from masked voxels. If not provided, all voxels are used. The mask spatial dimensions and coordinates must match the IQ data.

• low_cutoff ¶

  (int or float, default: None ) –

  Low cutoff for clutter filtering. Interpretation depends on filter_method. If not provided, uses method-specific defaults.

• high_cutoff ¶

  (int or float, default: None ) –

  High cutoff for clutter filtering. Interpretation depends on filter_method. If not provided, uses method-specific defaults.

• butterworth_order ¶

  (int, default: 4 ) –

  Order of Butterworth filter. Effective order is doubled due to forward-backward filtering.

• doppler_window_width ¶

  (int, default: None ) –

  Width of the sliding temporal window for power Doppler integration, in volumes. If not provided, equals clutter_window_width.

• doppler_window_stride ¶

  (int, default: None ) –

  Stride of the sliding temporal window for power Doppler integration, in volumes. If not provided, equals doppler_window_width.

Returns:

• (clutter_windows * doppler_windows, k, j, i) xarray.DataArray –

  Power Doppler volumes with updated time coordinates, where clutter_windows is the number of clutter filter sliding windows and doppler_windows is the number of power Doppler sliding windows per clutter window.

Examples:

>>> import xarray as xr
>>> ds = xr.open_zarr("iq_data.zarr")
>>> iq = ds["iq"]
>>> pwd = iq.fusi.iq.process_to_power_doppler(
...     clutter_window_width=50,
...     doppler_window_width=25,
...     low_cutoff=40,
... )

Plot voxel intensities across time as a raster image.

A carpet plot (also known as "grayplot" or "Power plot") displays voxel intensities as a 2D raster image with time on the x-axis and voxels on the y-axis. Each row represents one voxel's time series, typically standardized to z-scores.

Parameters:

• mask ¶

  (DataArray, default: None ) –

  Boolean mask with same spatial dimensions and coordinates as data. True values indicate voxels to include. If not provided, all non-zero voxels from the data are included.

• detrend_order ¶

  (int, default: None ) –

  Polynomial order for detrending:

  • 0: Remove mean (constant detrending).
  • 1: Remove linear trend using least squares regression (default).
  • 2+: Remove polynomial trend of specified order.

  If not provided, no detrending is applied.

• standardize ¶

  (bool, default: True ) –

  Whether to standardize each voxel's time series to z-scores.

• cmap ¶

  (str, default: "gray" ) –

  Matplotlib colormap name.

• vmin ¶

  (float, default: None ) –

  Minimum value for colormap. If not provided, uses mean - 2*std.

• vmax ¶

  (float, default: None ) –

  Maximum value for colormap. If not provided, uses mean + 2*std.

• decimation_threshold ¶

  (int or None, default: 800 ) –

  If the number of timepoints exceeds this value, data is downsampled along the time axis to improve plotting performance. Set to None to disable downsampling.

• figsize ¶

  (tuple[float, float], default: (10, 5) ) –

  Figure size in inches (width, height).

• title ¶

  (str, default: None ) –

  Plot title.

• fontsize ¶

  (float, default: None ) –

  Base font size for text elements. Title uses fontsize directly; axis labels and colorbar label use 0.9 * fontsize; tick labels use 0.85 * fontsize. If not provided, uses the active Matplotlib defaults.

• bg_color ¶

  (str, default: "white" ) –

  Background color for the figure and axes. Any matplotlib-compatible color string (e.g. "black", "white", "#1a1a2e").

• fg_color ¶

  (str, default: None ) –

  Color for text, labels, ticks, and spines. If not provided, derived automatically from bg_color using the WCAG relative luminance formula (white on dark backgrounds, black on light ones).

• ax ¶

  (Axes, default: None ) –

  Axes to plot on. If not provided, creates new figure and axes.

Returns:

• figure ( Figure or SubFigure ) –

  Figure object containing the carpet plot.

• axes ( Axes ) –

  Axes object with the carpet plot.

Examples:

>>> import xarray as xr
>>> data = xr.open_zarr("output.zarr")["iq"]
>>> fig, ax = data.fusi.plot.carpet()

>>> # With linear detrending.
>>> fig, ax = data.fusi.plot.carpet(detrend_order=1)

>>> # With mask.
>>> mask = np.abs(data.isel(time=0)) > threshold
>>> fig, ax = data.fusi.plot.carpet(mask=mask)

Plot a red/cyan composite of this volume against other.

Self drives the red channel; other drives the cyan channel. See confusius.plotting.plot_composite for full details.

Parameters:

• other ¶

  (DataArray) –

  Second volume, plotted in cyan. When resample=True, resampled onto this DataArray's grid before blending.

• resample ¶

  (bool, default: True ) –

  Whether to resample other onto this DataArray's grid using an identity transform before blending. When False, the two arrays must already share dims and shape, and their coordinates must match within rtol/atol; once validated, other's coordinates are replaced with this DataArray's so the two volumes share an exact coordinate frame downstream.

• resample_kwargs ¶

  (dict, default: None ) –

  Extra keyword arguments forwarded to resample_like when resample=True. Ignored when resample=False.

• rtol ¶

  (float, default: 1e-5 ) –

  Relative tolerance used to validate that this DataArray and other share coordinates when resample=False. Widen to accept acquisitions on slightly offset grids known to be equivalent. Ignored when resample=True.

• atol ¶

  (float, default: 1e-8 ) –

  Absolute tolerance used to validate that this DataArray and other share coordinates when resample=False. Ignored when resample=True.

• normalize_strategy ¶

  ((per_volume, per_slice, shared), default: "per_volume" ) –

  Intensity normalisation strategy.

  • "per_volume": rescale each input to [0, 1] independently over its full volume.
  • "per_slice": rescale each 2D slice independently.
  • "shared": rescale both volumes together using a shared [min, max] range, preserving the absolute-intensity relationship between the two inputs.

• slice_coords ¶

  (list[Hashable], default: None ) –

  Coordinate values along slice_mode at which to extract slices. Slices are selected by nearest-neighbour lookup. If not provided, all coordinate values from this DataArray are used.

• slice_mode ¶

  (str, default: "z" ) –

  World dimension ("z", "y", "x") or extra non-voxel dimension to slice. Native voxel dimensions ("k", "j", "i") are not valid slice modes. After slicing, each panel must be 2D.

• transpose ¶

  (bool, default: False ) –

  Whether to swap the row/column display dims of each slice panel.

• alpha ¶

  (float or ndarray, default: None ) –

  Opacity of the composite image, either a single value or a per-voxel array matching the shape of the displayed slices. If not provided, the image is fully opaque.

• show_titles ¶

  (bool, default: True ) –

  Whether to display subplot titles showing the slice coordinate.

• show_axis_labels ¶

  (bool, default: True ) –

  Whether to display axis labels (with units when available).

• show_axis_ticks ¶

  (bool, default: True ) –

  Whether to display axis tick labels.

• show_axes ¶

  (bool, default: True ) –

  Whether to show axis decorations. When False, overrides show_axis_labels and show_axis_ticks.

• fontsize ¶

  (float, default: None ) –

  Base font size for all text elements. Subplot titles use fontsize directly; axis labels use 0.9 * fontsize; tick labels use 0.85 * fontsize. If not provided, uses the active Matplotlib defaults.

• yincrease ¶

  (bool, default: False ) –

  Whether the y-axis increases upward (True) or downward (False).

• xincrease ¶

  (bool, default: True ) –

  Whether the x-axis increases to the right (True) or left (False).

• bg_color ¶

  (str, default: "black" ) –

  Background color for the figure and axes. Any matplotlib-compatible color string (e.g. "black", "white", "#1a1a2e").

• fg_color ¶

  (str, default: None ) –

  Color for text, labels, ticks, and spines. If not provided, derived automatically from bg_color using the WCAG relative luminance formula (white on dark backgrounds, black on light ones).

• figure ¶

  (Figure, default: None ) –

  Existing figure to draw into. If not provided, a new figure is created.

• axes ¶

  (ndarray, default: None ) –

  Existing 2D array of matplotlib.axes.Axes to draw into. If not provided, new axes are created inside figure.

• nrows ¶

  (int, default: None ) –

  Number of rows in the subplot grid. If not provided, computed automatically.

• ncols ¶

  (int, default: None ) –

  Number of columns in the subplot grid. If not provided, computed automatically.

• dpi ¶

  (int, default: None ) –

  Figure resolution in dots per inch. Ignored when figure is provided.

• resample_interpolation ¶

  ((linear, nearest, bspline), default: "linear" ) –

  Interpolation method used when resampling oblique (non-axis-aligned) voxel-to-world data onto an axis-aligned world grid for display. Distinct from resample_kwargs, which controls resampling other onto this DataArray's grid for compositing.

• resample_fill_value ¶

  (float, default: None ) –

  Value assigned to voxels outside this DataArray's/other's field of view after display resampling. If not provided, defaults to each array's own minimum value.

Returns:

• VolumePlotter –

  Object managing the figure, axes, and coordinate mapping for overlays.

Examples:

>>> import xarray as xr
>>> import confusius  # Register accessor.
>>> fixed = xr.open_zarr("fixed.zarr")["power_doppler"]
>>> moving = xr.open_zarr("moving.zarr")["power_doppler"]
>>> plotter = fixed.fusi.plot.composite(moving)

>>> # Same-grid comparison without resampling, with joint scaling.
>>> plotter = fixed.fusi.plot.composite(
...     registered_moving, resample=False, normalize_strategy="shared"
... )

Plot mask contours as a grid of 2D slice panels.

Displays contour lines for each labeled region across a grid of subplots. See confusius.plotting.plot_contours for full details.

Parameters:

• colors ¶

  (dict[int | str, str] or str, default: None ) –

  Color specification for contour lines. A dict maps each label (integer index or region acronym string) to a color; a str applies one color to all regions. If not provided, colors are derived from attrs["cmap"] and attrs["norm"] when present, otherwise from the tab10/tab20 colormap.

• linewidths ¶

  (float, default: 1.5 ) –

  Width of contour lines in points.

• linestyles ¶

  (str, default: "solid" ) –

  Line style for contour lines (e.g. "solid", "dashed").

• slice_mode ¶

  (str, default: "z" ) –

  World dimension ("z", "y", "x") or extra non-voxel dimension to slice. Native voxel dimensions ("k", "j", "i") are not valid slice modes. After slicing, each panel must be 2D.

• slice_coords ¶

  (list[Hashable], default: None ) –

  Coordinate values along slice_mode at which to extract slices. Slices are selected by nearest-neighbour lookup. If not provided, all coordinate values along slice_mode are used.

• transpose ¶

  (bool, default: False ) –

  Whether to swap the row/column display dims of each slice panel.

• fontsize ¶

  (float, default: None ) –

  Base font size for text elements. Subplot titles use fontsize directly; axis labels use 0.9 * fontsize; tick labels use 0.85 * fontsize. If not provided, uses the active Matplotlib defaults.

• yincrease ¶

  (bool, default: False ) –

  Whether the y-axis increases upward (True) or downward (False).

• xincrease ¶

  (bool, default: True ) –

  Whether the x-axis increases to the right (True) or left (False).

• bg_color ¶

  (str, default: "black" ) –

  Background color for the figure and axes. Any matplotlib-compatible color string (e.g. "black", "white", "#1a1a2e").

• fg_color ¶

  (str, default: None ) –

  Color for text, labels, ticks, and spines. If not provided, derived automatically from bg_color using the WCAG relative luminance formula (white on dark backgrounds, black on light ones).

• figure ¶

  (Figure, default: None ) –

  Existing figure to draw into. If not provided, a new figure is created.

• axes ¶

  (ndarray, default: None ) –

  Existing 2D array of matplotlib.axes.Axes to draw into. If not provided, new axes are created inside figure.

• **kwargs ¶

  –

  Additional keyword arguments passed to matplotlib.axes.Axes.plot.

Returns:

• VolumePlotter –

  Object managing the figure, axes, and coordinate mapping for overlays.

Examples:

>>> import xarray as xr
>>> import confusius  # Register accessor.
>>> mask = xr.open_zarr("output.zarr")["roi_mask"]
>>> plotter = mask.fusi.plot.contours(colors={1: "red", 2: "blue"})

>>> # Overlay contours on an existing volume plot.
>>> volume = xr.open_zarr("output.zarr")["power_doppler"]
>>> plotter = volume.fusi.plot.volume(slice_mode="z")
>>> plotter.add_contours(mask, colors="yellow")

Open napari to interactively paint integer labels over fUSI data.

Displays the data as an image layer and adds an empty Labels layer on top. The user paints integer labels directly on the image using napari's brush tool. After painting, pass the returned Labels layer to [labels_from_layer][confusius.plotting.FUSIPlotAccessor.labels_from_layer] to obtain an integer label map in the same spatial coordinates as the data.

Parameters:

• labels_layer_name ¶

  (str, default: "labels" ) –

  Name assigned to the Labels layer added to the viewer.

• viewer ¶

  (Viewer, default: None ) –

  Existing napari viewer to add layers to. If not provided, a new viewer is created.

• **plot_kwargs ¶

  –

  Additional keyword arguments forwarded to plot_napari for the image layer (e.g. colormap, contrast_limits).

Returns:

• viewer ( Viewer ) –

  The napari viewer instance with the image and Labels layers.

• labels_layer ( Labels ) –

  The empty Labels layer initialised to zeros. After painting labels in the viewer, pass it to [labels_from_layer][confusius.plotting.FUSIPlotAccessor.labels_from_layer] to convert the paintings to an integer label map.

Examples:

>>> import xarray as xr
>>> import confusius  # Register accessor.
>>> pwd = xr.open_zarr("output.zarr")["power_doppler"].compute()
>>> # Display time-averaged image with an interactive Labels layer.
>>> viewer, labels_layer = pwd.mean("time").fusi.plot.draw_napari_labels()
>>> # … paint labels in the viewer …
>>> # Convert painted labels to an integer label map.
>>> label_map = pwd.mean("time").fusi.plot.labels_from_layer(labels_layer)

Convert a napari Labels layer to an integer label map DataArray.

Reads the integer array painted in labels_layer and wraps it in an xarray.DataArray whose spatial dimensions and coordinates match those of the data.

Parameters:

• labels_layer ¶

  (Labels) –

  A Labels layer populated by the user (e.g. via [draw_napari_labels][confusius.plotting.FUSIPlotAccessor.draw_napari_labels]). Integer values identify distinct regions; zero is the background.

Returns:

• DataArray –

  Integer DataArray with the same spatial dimensions and coordinates as the data. Zero values indicate background (unlabelled) voxels.

Examples:

>>> import xarray as xr
>>> import confusius  # Register accessor.
>>> pwd = xr.open_zarr("output.zarr")["power_doppler"].compute()
>>> viewer, labels_layer = pwd.mean("time").fusi.plot.draw_napari_labels()
>>> # … paint labels in the viewer …
>>> label_map = pwd.mean("time").fusi.plot.labels_from_layer(labels_layer)
>>> # Use the label map for region-based analysis.
>>> from confusius.extract import extract_with_labels
>>> signals = extract_with_labels(pwd, label_map)

Display data in napari viewer.

Parameters:

• show_colorbar ¶

  (bool, default: True ) –

  Whether to show the colorbar. Only applies to image layers.

• show_scale_bar ¶

  (bool, default: True ) –

  Whether to show the scale bar.

• dim_order ¶

  (tuple[str, ...], default: None ) –

  Dimension ordering for the spatial axes (last three dimensions). If not provided, singleton spatial dimensions (e.g. the elevation axis of a single-slice acquisition) are placed first so the canvas always shows the two axes that actually vary; otherwise the dimensions' native ordering in data is used.

• viewer ¶

  (Viewer, default: None ) –

  Existing napari viewer to add the layer to. If not provided, a new viewer is created.

• layer_type ¶

  ((image, labels), default: "image" ) –

  Type of layer to create. Use "image" for fUSI data and "labels" for ROI masks, segmentations, or other label data.

• resample_interpolation ¶

  ((linear, nearest, bspline), default: "linear" ) –

  Interpolation method used when resampling oblique (non-axis-aligned) voxel-to-world data onto an axis-aligned world grid for display. If not provided, defaults to "nearest" for layer_type="labels" and "linear" otherwise.

• resample_fill_value ¶

  (float, default: None ) –

  Value assigned to voxels outside this DataArray's field of view after resampling oblique data. If not provided, defaults to its own minimum value.

• **layer_kwargs ¶

  –

  Additional keyword arguments passed to the layer creation method. For image layers, if data.attrs contains "cmap" and "colormap" is not in layer_kwargs, the attribute is used as the colormap.

Returns:

• viewer ( Viewer ) –

  The napari viewer instance with the layer added.

• layer ( Image or Labels ) –

  The layer added to the viewer.

Examples:

>>> import xarray as xr
>>> import confusius  # Register accessor.
>>> data = xr.open_zarr("output.zarr")["iq"]
>>> viewer, layer = data.fusi.plot.napari()

>>> # Custom contrast limits
>>> viewer, layer = data.fusi.plot.napari(contrast_limits=(0, 100))

>>> # Different dimension ordering (e.g., depth, elevation, lateral)
>>> viewer, layer = data.fusi.plot.napari(dim_order=("y", "z", "x"))

>>> # Add a second dataset as a new layer in an existing viewer
>>> viewer, layer = data1.fusi.plot.napari()
>>> viewer, layer = data2.fusi.plot.napari(viewer=viewer)

>>> # Display ROI labels (e.g., segmentation mask)
>>> roi_mask = xr.open_zarr("output.zarr")["roi_mask"]
>>> viewer, layer = roi_mask.fusi.plot.napari(layer_type="labels")

>>> # Overlay labels on existing image
>>> viewer, layer = data.fusi.plot.napari()
>>> viewer, layer = roi_mask.fusi.plot.napari(viewer=viewer, layer_type="labels")