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.

  • c_added (bool) –

    Computed property. Whether C is added as a singleton.

  • has_z (bool) –

    Computed property. Whether original data contains a Z axis.

  • 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 property

C is added as a singleton dimension.

Returns:

  • bool –

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

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.

has_z property

Original data contains a Z axis.

Returns:

  • bool –

    True if Z is 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.

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.

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_original_stitch_slices(original_axes, original_shape, sample_idx, stitch_coords, crop_size)

Get slices to stitch tile back into original array.

sample_idx andstitch_coords` are expressed with respect to the transformed space (SCZYX or SCYX). The returned slices will index into the original array for stitching the tile back in place.

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.

  • 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 to index into the original array for stitching the tile back in place.

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)

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

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.

Returns:

  • ndarray –

    Array with original axes order and shape restored.

Raises:

  • ValueError –

    If input array is not 4D (SCYX) or 5D (SCZYX), or if restoring shape is not supported for the given original axes (e.g. T as Z with CZI format).

restore_tile(tile, original_axes, original_shape)

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.

Returns:

  • ndarray –

    Tile with original spatial axes order restored.