ngio.common API documentation¶

ngio.common ¶

Common classes and functions that are used across the package.

ArrayLike `module-attribute` ¶

ArrayLike: TypeAlias = ndarray | Array | Delayed

Dimensions ¶

Dimensions(shape: tuple[int, ...], axes_mapper: AxesMapper)

Dimension metadata.

Create a Dimension object from a Zarr array.

Parameters:

shape (tuple[int, ...]) –

The shape of the Zarr array.
axes_mapper (AxesMapper) –

The axes mapper object.

Source code in ngio/common/_dimensions.py

def __init__(
    self,
    shape: tuple[int, ...],
    axes_mapper: AxesMapper,
) -> None:
    """Create a Dimension object from a Zarr array.

    Args:
        shape: The shape of the Zarr array.
        axes_mapper: The axes mapper object.
    """
    self._shape = shape
    self._axes_mapper = axes_mapper

    if len(self._shape) != len(self._axes_mapper.on_disk_axes):
        raise NgioValidationError(
            "The number of dimensions must match the number of axes. "
            f"Expected Axis {self._axes_mapper.on_disk_axes_names} but got shape "
            f"{self._shape}."
        )

axes_mapper `property` ¶

axes_mapper: AxesMapper

Return the axes mapper object.

on_disk_shape `property` ¶

on_disk_shape: tuple[int, ...]

Return the shape as a tuple.

is_time_series `property` ¶

is_time_series: bool

Return whether the data is a time series.

is_2d `property` ¶

is_2d: bool

Return whether the data is 2D.

is_2d_time_series `property` ¶

is_2d_time_series: bool

Return whether the data is a 2D time series.

is_3d `property` ¶

is_3d: bool

Return whether the data is 3D.

is_3d_time_series `property` ¶

is_3d_time_series: bool

Return whether the data is a 3D time series.

is_multi_channels `property` ¶

is_multi_channels: bool

Return whether the data has multiple channels.

get ¶

get(axis_name: str, default: int | None = None) -> int

Return the dimension of the given axis name.

Parameters:

axis_name (str) –

The name of the axis (either canonical or non-canonical).
default (int | None, default: None ) –

The default value to return if the axis does not exist. If None, an error is raised.

Source code in ngio/common/_dimensions.py

def get(self, axis_name: str, default: int | None = None) -> int:
    """Return the dimension of the given axis name.

    Args:
        axis_name: The name of the axis (either canonical or non-canonical).
        default: The default value to return if the axis does not exist. If None,
            an error is raised.
    """
    index = self._axes_mapper.get_index(axis_name)
    if index is None:
        if default is not None:
            return default
        raise NgioValueError(f"Axis {axis_name} does not exist.")

    return self._shape[index]

has_axis ¶

has_axis(axis_name: str) -> bool

Return whether the axis exists.

Source code in ngio/common/_dimensions.py

def has_axis(self, axis_name: str) -> bool:
    """Return whether the axis exists."""
    index = self._axes_mapper.get_axis(axis_name)
    if index is None:
        return False
    return True

AbstractTransform ¶

Abstract base class for a generic transform.

transform_numpy ¶

transform_numpy(array: ndarray) -> ndarray

Transform a numpy array.

Source code in ngio/common/_io_transforms.py

def transform_numpy(self, array: np.ndarray) -> np.ndarray:
    """Transform a numpy array."""
    raise NotImplementedError("Subclasses should implement this method.")

transform_dask ¶

transform_dask(array: Array) -> Array

Transform a dask array.

Source code in ngio/common/_io_transforms.py

def transform_dask(self, array: da.Array) -> da.Array:
    """Transform a dask array."""
    raise NotImplementedError("Subclasses should implement this method.")

transform_delayed ¶

transform_delayed(array: Delayed) -> Delayed

Transform a delayed dask array.

Source code in ngio/common/_io_transforms.py

def transform_delayed(self, array: Delayed) -> Delayed:
    """Transform a delayed dask array."""
    return delayed(self.transform_numpy)(array)

TransformProtocol ¶

Bases: Protocol

Protocol numpy, dask, or delayed array transforms.

transform_numpy ¶

transform_numpy(array: ndarray) -> ndarray

Transform a numpy array.

Source code in ngio/common/_io_transforms.py

def transform_numpy(self, array: np.ndarray) -> np.ndarray:
    """Transform a numpy array."""
    ...

transform_dask ¶

transform_dask(array: Array) -> Array

Transform a dask array.

Source code in ngio/common/_io_transforms.py

def transform_dask(self, array: da.Array) -> da.Array:
    """Transform a dask array."""
    ...

transform_delayed ¶

transform_delayed(array: Delayed) -> Delayed

Transform a delayed dask array.

Source code in ngio/common/_io_transforms.py

def transform_delayed(self, array: Delayed) -> Delayed:
    """Transform a delayed dask array."""
    ...

Roi ¶

Bases: BaseModel

Region of interest (ROI) metadata.

name `instance-attribute` ¶

name: str

x_length `instance-attribute` ¶

x_length: float

y_length `instance-attribute` ¶

y_length: float

z_length `class-attribute` `instance-attribute` ¶

z_length: float = 1.0

t_length `class-attribute` `instance-attribute` ¶

t_length: float = 1.0

x `class-attribute` `instance-attribute` ¶

x: float = 0.0

y `class-attribute` `instance-attribute` ¶

y: float = 0.0

z `class-attribute` `instance-attribute` ¶

z: float = 0.0

t `class-attribute` `instance-attribute` ¶

t: float = 0.0

unit `class-attribute` `instance-attribute` ¶

unit: SpaceUnits | str | None = Field(
    DefaultSpaceUnit, repr=False
)

model_config `class-attribute` `instance-attribute` ¶

model_config = ConfigDict(extra='allow')

to_pixel_roi ¶

to_pixel_roi(
    pixel_size: PixelSize, dimensions: Dimensions
) -> RoiPixels

Convert to raster coordinates.

Source code in ngio/common/_roi.py

def to_pixel_roi(
    self, pixel_size: PixelSize, dimensions: Dimensions
) -> "RoiPixels":
    """Convert to raster coordinates."""
    dim_x = dimensions.get("x")
    dim_y = dimensions.get("y")
    # Will default to 1 if z does not exist
    dim_z = dimensions.get("z", default=1)
    dim_t = dimensions.get("t", default=1)
    extra_dict = self.model_extra if self.model_extra else {}

    return RoiPixels(
        name=self.name,
        x=_to_raster(self.x, pixel_size.x, dim_x),
        y=_to_raster(self.y, pixel_size.y, dim_y),
        z=_to_raster(self.z, pixel_size.z, dim_z),
        t=_to_raster(self.t, pixel_size.t, dim_t),
        x_length=_to_raster(self.x_length, pixel_size.x, dim_x),
        y_length=_to_raster(self.y_length, pixel_size.y, dim_y),
        z_length=_to_raster(self.z_length, pixel_size.z, dim_z),
        t_length=_to_raster(self.t_length, pixel_size.t, dim_t),
        **extra_dict,
    )

zoom ¶

zoom(zoom_factor: float = 1) -> Roi

Zoom the ROI by a factor.

Parameters:

zoom_factor (float, default: 1 ) –

The zoom factor. If the zoom factor is less than 1 the ROI will be zoomed in. If the zoom factor is greater than 1 the ROI will be zoomed out. If the zoom factor is 1 the ROI will not be changed.

Source code in ngio/common/_roi.py

def zoom(self, zoom_factor: float = 1) -> "Roi":
    """Zoom the ROI by a factor.

    Args:
        zoom_factor: The zoom factor. If the zoom factor
            is less than 1 the ROI will be zoomed in.
            If the zoom factor is greater than 1 the ROI will be zoomed out.
            If the zoom factor is 1 the ROI will not be changed.
    """
    return zoom_roi(self, zoom_factor)

RoiPixels ¶

Bases: BaseModel

Region of interest (ROI) metadata.

name `instance-attribute` ¶

name: str

x_length `instance-attribute` ¶

x_length: int

y_length `instance-attribute` ¶

y_length: int

z_length `class-attribute` `instance-attribute` ¶

z_length: int = 1

t_length `class-attribute` `instance-attribute` ¶

t_length: int = 1

x `class-attribute` `instance-attribute` ¶

x: int = 0

y `class-attribute` `instance-attribute` ¶

y: int = 0

z `class-attribute` `instance-attribute` ¶

z: int = 0

t `class-attribute` `instance-attribute` ¶

t: int = 0

model_config `class-attribute` `instance-attribute` ¶

model_config = ConfigDict(extra='allow')

to_roi ¶

to_roi(pixel_size: PixelSize) -> Roi

Convert to world coordinates.

Source code in ngio/common/_roi.py

def to_roi(self, pixel_size: PixelSize) -> Roi:
    """Convert to world coordinates."""
    extra_dict = self.model_extra if self.model_extra else {}
    return Roi(
        name=self.name,
        x=_to_world(self.x, pixel_size.x),
        y=_to_world(self.y, pixel_size.y),
        z=_to_world(self.z, pixel_size.z),
        t=_to_world(self.t, pixel_size.t),
        x_length=_to_world(self.x_length, pixel_size.x),
        y_length=_to_world(self.y_length, pixel_size.y),
        z_length=_to_world(self.z_length, pixel_size.z),
        t_length=_to_world(self.t_length, pixel_size.t),
        unit=pixel_size.space_unit,
        **extra_dict,
    )

to_slices ¶

to_slices() -> dict[str, slice]

Return the slices for the ROI.

Source code in ngio/common/_roi.py

def to_slices(self) -> dict[str, slice]:
    """Return the slices for the ROI."""
    return {
        "x": slice(self.x, self.x + self.x_length),
        "y": slice(self.y, self.y + self.y_length),
        "z": slice(self.z, self.z + self.z_length),
        "t": slice(self.t, self.t + self.t_length),
    }