multiscale-spatial-image

2.1.0 verified Sat May 09 auth: no python

Generate a multiscale, chunked, multi-dimensional spatial image data structure that can be serialized to OME-NGFF. Version 2.1.0 is the latest, supports Python >=3.11, and uses xarray DataTree (instead of the archived datatree package).

pip install multiscale-spatial-image

Common errors

error AttributeError: module 'multiscale_spatial_image' has no attribute 'to_multiscale' ↓

cause Installed an older version (v0.x) where the function was in a submodule.

fix

Upgrade to >=1.0.0: 'pip install --upgrade multiscale-spatial-image'. Then use 'from multiscale_spatial_image import to_multiscale'.

error ImportError: cannot import name 'MultiscaleSpatialImage' from 'multiscale_spatial_image' ↓

cause Incorrect import path or outdated package version.

fix

Ensure package is installed and version >=1.0.0. Run 'pip install --upgrade multiscale-spatial-image'. Then use 'from multiscale_spatial_image import MultiscaleSpatialImage'.

error KeyError: 'scales' ↓

cause Trying to access 'ms_image.scales' on a v1.x or earlier object; v1.x used 'ms_image.groups' or similar.

fix

For v2.x, use 'ms_image.scales'. For v1.x, use 'list(ms_image.children)' or upgrade to v2.x.

error ValueError: chunks must be a dict or a single integer ↓

cause Passing chunks argument in wrong format to to_multiscale (e.g., a tuple).

fix

Provide chunks as a dict mapping dimension names to chunk sizes, e.g., chunks={'y': 64, 'x': 64}.

Warnings

breaking In v2.0.0, the underlying data structure changed from the standalone 'datatree' library to xarray's built-in DataTree. Code using old datatree API (e.g., 'dt.children') will break. ↓

fix Migrate to xarray.DataTree API: use 'ms_image.scales' to list scale levels and access nodes via 'ms_image[scale_key]'.

breaking v2.x requires Python >=3.11. Python 3.8-3.10 support dropped. ↓

fix Update Python to 3.11 or higher.

deprecated Using 'from multiscale_spatial_image.to_multiscale import to_multiscale' is deprecated; the function is now at module level. ↓

fix Use 'from multiscale_spatial_image import to_multiscale'.

Imports

MultiscaleSpatialImage

wrong

from multiscale_spatial_image import MultiscaleSpatialImage

correct

from multiscale_spatial_image import MultiscaleSpatialImage

No common mistake; ensure correct import.

to_multiscale

wrong

from multiscale_spatial_image.to_multiscale import to_multiscale

correct

from multiscale_spatial_image import to_multiscale

to_multiscale is a module-level function, not a submodule.

Quickstart

Quickstart: create a multiscale spatial image from an xarray DataArray and export to OME-NGFF.

import numpy as np
import xarray as xr
from multiscale_spatial_image import MultiscaleSpatialImage, to_multiscale

# Create a simple 2D spatial image (channels, y, x)
data = np.random.rand(3, 256, 256)
xarr = xr.DataArray(
    data,
    dims=("c", "y", "x"),
    coords={"c": ["R", "G", "B"], "y": range(256), "x": range(256)},
    name="image"
)

# Generate multiscale representation (2 scales)
ms_image = to_multiscale(xarr, scale_factors=[2], chunks=64)

print(ms_image)
print(ms_image.scales)  # List of scale keys, e.g., ["scale0", "scale1"]

# Save to OME-NGFF (Zarr) store
ms_image.to_zarr("output.zarr")