abczarr.ome.pyramid

Build a multiscale image pyramid from a base-resolution array.

A multiscale image is a stack of the same image at falling resolutions. The base level and its OME metadata are written first, through an ImageConfig or by any other means. create_pyramid then adds the coarser levels and extends that metadata to describe them.

Each coarser level is a windowed reduction of the level above it, in the way dask.array.coarsen reduces every block of voxels to a single value. Each axis halves by default. The factor argument sets how much each axis shrinks, and an axis given a factor of 1 keeps its full resolution, which suits a channel or time axis whose values should not be blended together.

The coordinate transform on each new level is read from the base level's transform and scaled by the factor, so the metadata continues to place every level in the coordinate system the base level was written into. The version of the existing metadata is kept.

Functions:

default_levels

default_levels(shape: ShapeLike, chunks: ShapeLike, factor: FactorSpec = 2) -> int

The number of extra levels that shrinks an array down to one chunk.

The count is how many times an axis can be divided by its factor before it reaches its chunk size, taken over the axis that needs the most divisions. The result is never negative. An axis with a factor of 1 is left out of the count.

Parameters:

Name	Type	Description	Default
`shape`	`tuple of int`	The full-resolution array's shape.	required
`chunks`	`tuple of int`	The full-resolution array's chunk shape.	required
`factor`	`(int, sequence or mapping)`	How much each axis shrinks per level, as in downsample_array. A mapping keyed by dimension name needs the array, so pass the resolved per-axis factors here instead.	`2`

downsample_array

downsample_array(group: ZarrGroup, source: str, target: str, *, factor: FactorSpec = 2, method: str = 'mean') -> ZarrArray

Write target as source coarsened by factor.

The array named source is read from group and shrunk one axis at a time by that axis's factor, with a windowed reduction chosen by method. An axis whose factor is 1, or that is already length one, keeps its resolution. An axis whose length is not a multiple of its factor is trimmed to the largest multiple before the reduction. The result is written as a new array named target in the same group and returned.

Parameters:

Name	Type	Description	Default
`group`	`ZarrGroup`	The group that holds `source` and receives `target`.	required
`source`	`str`	The name of the array to downsample.	required
`target`	`str`	The name to give the downsampled array.	required
`factor`	`(int, sequence or mapping)`	How much each axis shrinks. A single `int` (the default, 2) halves every axis. A sequence gives one factor per axis. A mapping keys a factor by axis index or dimension name and halves the rest.	`2`
`method`	`str`	How to combine each window of voxels: `"mean"` (the default), `"median"`, `"min"`, `"max"`, or `"sum"`.	`'mean'`

Returns:

Type	Description
`ZarrArray`	The new coarser array.

create_pyramid

create_pyramid(group: ZarrGroup, source: str, *, levels: int | None = None, factor: FactorSpec = 2, method: str = 'mean', name: str | Callable[[int], str] = '{level}') -> list[ZarrArray]

Add downsampled levels below source and record them in the metadata.

Level 0 is the array already named source, and its OME metadata is already written on group. Each further level is the one above it coarsened by factor through downsample_array. Building stops after levels extra levels, or earlier once no axis can shrink further. Every level's array is returned, the base first and the coarsest last.

The group's OME metadata is read and extended to name the new levels. Each new level's coordinate transform is the base level's transform scaled by the factor, so every level stays in the coordinate system the base level was written into. The version of the existing metadata is kept.

Parameters:

Name	Type	Description	Default
`group`	`ZarrGroup`	The group that holds `source` and its OME metadata. The coarser levels are written into the group, and the metadata is extended to describe them.	required
`source`	`str`	The name of the full-resolution array (level 0).	required
`levels`	`int`	How many coarser levels to add. The default fills the pyramid down to about one chunk, through default_levels.	`None`
`factor`	`(int, sequence or mapping)`	How much each axis shrinks per level, as in downsample_array.	`2`
`method`	`str`	The windowed reduction, as in downsample_array.	`'mean'`
`name`	`str or callable`	How to name each coarser level. A format string is given the level index as `level` and the cumulative shrink as `scale`, so the default `"{level}"` names levels `"1"`, `"2"`, and so on, and `"{scale}"` names them by factor. A callable is given the level index and returns the name. Level 0 keeps the name `source`.	`'{level}'`

Returns:

Type	Description
`list of ZarrArray`	Every level, the base first and the coarsest last.

Raises:

Type	Description
`ValueError`	If `group` has no OME metadata to extend.