Skip to content

Reshape Array

Source

Utilities for reshaping arrays between original and transformed space.

AxesTransform dataclass

Transformation between original and transformed space axes.

All transformation decisions are derived from the original axes string, shape.

Attributes:

  • original_axes (str) –

    User defined attribute. Axes string of the input data (e.g. "YXC", "STCZYX").

  • original_shape (tuple[int, ...]) –

    User defined attribute. Shape corresponding to original_axes.

  • sample_dims (list[str]) –

    Computed property. Original dimensions merged into S. Spatial (Y, X and Z), as well as channels, are never considered sample dimensions.

  • original_has_z (bool) –

    Computed property. Whether original data contains a Z axis.

  • original_dim_sizes (dict[str, int]) –

    Computed property. Map from axis name to original size.

  • transformed_axes (str) –

    Computed property. Transformed axes string: "SC(Z)YX".

  • transformed_shape (tuple[int, ...]) –

    Computed property. Expected shape after forward transformation.

  • order_permutation (list[int]) –

    Computed property. Permutation to reorder original axes to STCZYX reference order in SC(Z)YX space.

c_added_to_original property

C is added as a singleton dimension.

Returns:

  • bool –

    True if C is not in original axes, False otherwise.

order_permutation property

Permutation to reorder original axes to STCZYX reference order.

Returns:

  • list[int] –

    List of indices representing the permutation to reorder original axes to STCZYX reference order. Only includes axes present in the original axes.

original_axes instance-attribute

Original axes string of the input data (e.g. "YXC", "STCZYX").

original_dim_sizes property

Map from axis name to original size.

Returns:

  • dict[str, int] –

    Dictionary mapping axis name to its size in the original shape.

original_has_z property

Original data contains a Z axis.

Returns:

  • bool –

    True if Z is in original axes, False otherwise.

original_shape instance-attribute

Shape corresponding to original_axes.

sample_dims property

Original dimensions merged into S.

Spatial (Y, X and Z), as well as channels, are never considered sample dimensions.

Returns:

  • list[str] –

    List of original axes that are considered sample dimensions and merged into S. Will be in the order they appear in the reference STCZYX.

transformed_axes property

Transformed axes string, SC(Z)YX or SCYX.

Returns:

  • str –

    Transformed axes string. Will be SCZYX if original data has Z axis, otherwise SCYX.

transformed_shape property

Expected shape in transformed space.

Returns:

  • tuple[int, ...] –

    Expected shape after forward transformation, in the order of transformed_axes.

__post_init__()

Validate original axes and shape.

calc_original_S_idx(sample_idx)

Calculate the original index for the S dimension given sample_idx.

Parameters:

  • sample_idx (int) –

    Transformed sample index.

Returns:

  • int –

    Index along the S axis.

calc_original_T_idx(sample_idx)

Calculate the original index for the T dimension given sample_idx.

Parameters:

  • sample_idx (int) –

    Transformed sample index.

Returns:

  • int –

    Index along the T axis.

RestoredAxesTransform dataclass

Transformation from transformed space back to original axes order.

The only difference between the current shape and the original shape is that the C dimension might have been added, removed or have different dimension.

current_is_tile is used to determine whether the current shape is a tile shape (C(Z)YX) or a full array shape (SC(Z)YX).

This class is used in the following cases: - Restoring a full array from SC(Z)YX to original axes order, after prediction. - Restoring a tile from C(Z)YX to original axes order, before writing it in a Zarr. - Generate slices in a fully restored array to index a restored tile (Zarr). - Adjust shape based on channel difference between original and current shape, used to ensure that Zarr shard and chunk sizes are compatible with the restored array shape.

canonical_order property

Whether the new axis follows canonical order.

Canonical order is STCZYX.

Returns:

  • bool –

    True if it follows canonical order, False otherwise.

current_axes property

Current axes in transformed space.

Returns:

  • str –

    Axes of the current data in transformed space.

Raises:

  • ValueError –

    If the length of the shape is not compatible with the expected length given current_is_tile.

current_c_size property

Current number of channels in transformed space.

Returns:

  • int –

    Number of channels in the transformed space.

current_is_tile = False class-attribute instance-attribute

Whether current_shape is a tile shape (C(Z)YX). This is used to identify the axes order in current_shape.

current_shape instance-attribute

Current transformed shape, either SC(Z)YX or C(Z)YX.

drop_current_c property

Whether current C should be dropped.

Returns:

  • bool –

    True if C in target_axes.

original_axes instance-attribute

Original axes string of the full data.

original_c_size property

Original C dimension size if present.

Returns:

  • int or None –

    Original C size, or None if original axes do not contain C.

original_dim_sizes property

Original dimensions size.

Returns:

  • dict[str, int] –

    Dictionary mapping axis name to its size in the original shape.

original_shape instance-attribute

Original shape of the full data.

restored_array_shape property

Shape of the destination array indexed by stitch slices.

This shape follows restored_axes and matches original shape except for C, which keeps transformed-space channel dimension.

Returns:

  • tuple[int, ...] –

    Shape of the destination array indexed by stitch slices, following restored_axes.

restored_axes property

Restored axes order for the current output.

Tiles do not carry S/T dimensions, so S/T axes are removed from the output axes order if current_is_tile is True.

Returns:

  • list[str] –

    List of axes in the restored data output, following restored_array_axes.

sample_dims property

Original sample dimensions.

Returns:

  • list[str] –

    Original sample dimensions.

target_axes instance-attribute

Target axes order for the restored output. It should have the same sample axes as original_axes, although these can be in a different order.

__post_init__()

Validate current shape and axes.

adjust_shape(shape)

Adjust shape to match the restored array shape.

This method is meant to adjust chunks and shapes from Zarr arrays.

Note that if C is absent and need to be added, then it is added as a singleton. Otherwise, the C dimension is kept as is, even when current C size is different from the original.

Parameters:

Returns:

  • tuple[int, ...] –

    Adjusted shape that matches the restored array shape.

restore(data)

Restore transformed data to the output layout used by original axes.

Parameters:

  • data (ndarray) –

    Input data array in transformed space.

Returns:

  • ndarray –

    Data array restored to the target axes order.

stitch_slices(sample_idx, stitch_coords, crop_size)

Build slices that index into the restored output dimensions.

Parameters:

  • sample_idx (int) –

    Index of the sample in transformed space (S axis) to stitch back.

  • stitch_coords (Sequence[int]) –

    Starting coordinates of the tile in the original spatial axes (Y, X and Z if present).

  • crop_size (Sequence[int]) –

    Size of the tile in the original spatial axes (Y, X and Z if present).

Returns:

  • tuple[slice | int, ...] –

    Slices that index into the restored output dimensions.

adjust_shape_for_channels(data_shape, axes, n_channels)

Adjust a shape with a different number of channels.

This method is used in two contexts: subsetting channels during data loading and creating prediction arrays from input shape with different number of output channels.

Parameters:

  • data_shape (Sequence[int]) –

    Data shape.

  • axes (str) –

    Axes string describing data_shape.

  • n_channels (int) –

    Number of channels to update data_shape with.

Returns:

Raises:

channel_slice(channels)

Create a slice or sequence for indexing channels while preserving dimensions.

Parameters:

  • channels (Sequence[int] | None) –

    The channel indices to select, or None to select all channels.

Returns:

  • EllipsisType | Sequence[int] –

    An indexing object that can be used to index the channel dimension while preserving it.

get_patch_slices(original_axes, original_shape, sample_idx, channels, coords, patch_size)

Get slices to extract patch from an array.

The argument original_axes describes the dimension order of the array.

sample_idx is expressed with respect to the transformed space where the "S" and "T" dimensions are flattened together, if both or either are present.

Parameters:

  • original_axes (str) –

    Original axes string of the full data.

  • original_shape (Sequence[int]) –

    Original shape of the full data.

  • sample_idx (int) –

    Index of the sample in transformed space (S axis) to stitch back.

  • channels (sequence of int or None) –

    Channel indices to extract. If None, all channels will be extracted.

  • coords (Sequence[int]) –

    Starting coordinates of the patch in the original spatial axes (Y, X and Z if present).

  • patch_size (Sequence[int]) –

    Size of the patch in the spatial axes (Y, X and Z if present).

Returns:

reshape_array(array, original_axes)

Reshape array from arbitrary axes order to SC(Z)YX.

Parameters:

  • array (ndarray) –

    Input array.

  • original_axes (str) –

    Original axes string describing current dimension order (e.g. YXC).

Returns:

  • ndarray –

    Array reshaped to SC(Z)YX.

reshape_patch(patch, original_axes)

Reshape patch from arbitrary axes order to C(Z)YX.

Parameters:

  • patch (ndarray) –

    Input patch, patches do not include the "S" or "T" dimension.

  • original_axes (str) –

    Axes string that describes the original dimensions of the data the patch was sampled from, (e.g. SYXC).

Returns:

  • ndarray –

    Patch reshaped to C(Z)YX.

restore_array(array, original_axes, original_shape, target_axes=None)

Restore array from SC(Z)YX space back to original axes and shape.

If array has different spatial dimensions or number of channels than the original array, then the restored array will have the same shape as array in those dimensions, but will still be reordered to match the target axes.

Parameters:

  • array (ndarray) –

    Array in SC(Z)YX format.

  • original_axes (str) –

    Original axes string (e.g. YXC).

  • original_shape (Sequence[int]) –

    Original shape of the data, used to determine sample dimensions size.

  • target_axes (str, default: None ) –

    Target axes order to which the array should be restored. Can be set to original_axes to restore the original axes order.

Returns:

  • ndarray –

    Array with original axes order and shape restored.

restore_tile(tile, original_axes, original_shape, target_axes=None)

Restore single tile from C(Z)YX space back to original axes and shape.

Parameters:

  • tile (ndarray) –

    Tile in C(Z)YX format.

  • original_axes (str) –

    Original axes string of the full data.

  • original_shape (Sequence[int]) –

    Original shape of the full data.

  • target_axes (str | None, default: None ) –

    Target axes order to which the tile should be restored. Can be set to None to restore the original axes order.

Returns:

  • ndarray –

    Tile with original spatial axes order restored.