Skip to content

confusius.spatial

spatial

Spatial processing module for fUSI volumetric data.

Modules:

  • smooth –

    Spatial smoothing functions for fUSI volumetric data.

Functions:

  • smooth_volume –

    Smooth a DataArray spatially using a Gaussian kernel.

smooth_volume 

smooth_volume(
    data: DataArray,
    fwhm: float | dict[str, float],
    ensure_finite: bool = False,
) -> DataArray

Smooth a DataArray spatially using a Gaussian kernel.

FWHM values are specified in physical units and converted to voxel-space sigma values using the coordinate spacing of each dimension. Smoothing is only applied to dimensions with uniform coordinate spacing.

Parameters:

  • data

    (DataArray) –

    Input data to smooth. Can have any number of dimensions, including a time dimension.

    Chunking along smoothed dimensions is not supported

    Dimensions selected for smoothing must NOT be chunked. Chunk only along other dimensions, e.g. data.chunk({"time": 10}) when smoothing spatial axes.

  • fwhm

    (float or dict[str, float]) –

    Full width at half maximum of the Gaussian kernel in physical unit. A scalar applies the same FWHM to all dimensions except "time". A dict maps dimension names to per-dimension FWHM values, e.g. {"z": 0.5, "y": 0.2, "x": 0.2}; only the listed dimensions are smoothed. Dimensions of length 1 are left untouched.

  • ensure_finite

    (bool, default: False ) –

    Whether to replace non-finite values (NaN, Inf) with zero before filtering. This prevents NaNs from propagating to neighbouring voxels through the Gaussian kernel.

Returns:

  • DataArray –

    Smoothed data with the same shape, dimensions, coordinates, and attributes as the input.

Raises:

  • ValueError –

    If fwhm is a dict and any key is not present in the DataArray, or if any smoothed dimension has non-uniform or undefined coordinate spacing, or is chunked (for Dask-backed arrays).

Notes

The Gaussian sigma in voxel units is computed as:

\[ \sigma_{\text{vox}} = \frac{\text{FWHM}}{ 2 \sqrt{2 \ln 2} \cdot \Delta} \]

where \(\Delta\) is the coordinate spacing for that dimension, in the same physical units as fwhm.

Smoothing is applied via scipy.ndimage.gaussian_filter with zero sigma for non-smoothed dimensions, making the operation separable and efficient.

Examples:

Smooth isotropically with a 0.3 (coordinate-unit) FWHM kernel:

>>> import xarray as xr
>>> import numpy as np
>>> import confusius  # noqa: F401
>>> data = xr.DataArray(
...     np.random.randn(5, 10, 1, 20),
...     dims=["time", "z", "y", "x"],
...     coords={
...         "time": np.arange(5) * 0.2,
...         "z": np.arange(10) * 0.1,
...         "y": np.zeros(1),
...         "x": np.arange(20) * 0.1,
...     },
... )
>>> smoothed = smooth_volume(data, fwhm=0.3)

Smooth with anisotropic kernels:

>>> smoothed = smooth_volume(data, fwhm={"z": 0.5, "y": 0.2, "x": 0.2})

Smooth only selected dimensions:

>>> smoothed = smooth_volume(data, fwhm={"z": 0.3, "x": 0.3})

Suppress NaN propagation when some voxels are masked:

>>> smoothed = smooth_volume(data, fwhm=0.3, ensure_finite=True)