aicsimageio package

Subpackages

Submodules

aicsimageio.aics_image module

class aicsimageio.aics_image.AICSImage(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], reader: Optional[Type[Reader]] = None, reconstruct_mosaic: bool = True, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: ImageContainer

AICSImage takes microscopy image data types (files or arrays) of varying dimensions (“ZYX”, “TCZYX”, “CYX”) and reads them as consistent 5D “TCZYX” (“Time-Channel-Z-Y-X”) ordered array(s). The data and metadata are lazy loaded and can be accessed as needed.

Parameters

  • image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.

  • reader (Optional[Type[Reader]]) – The Reader class to specifically use for reading the provided image. Default: None (find matching reader)

  • reconstruct_mosaic (bool) – Boolean for setting that data for this object to the reconstructed / stitched mosaic image. Default: True (reconstruct the mosaic image from tiles) Notes: If True and image is a mosaic, data will be fully reconstructed and stitched array. If True and base reader doesn’t support tile stitching, data won’t be stitched and instead will have an M dimension for tiles. If False and image is a mosaic, data won’t be stitched and instead will have an M dimension for tiles. If image is not a mosaic, data won’t be stitched or have an M dimension for tiles.

  • fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

  • kwargs (Any) – Extra keyword arguments that will be passed down to the reader subclass.

Examples

Initialize an image then read the file and return specified slices as a numpy array.

>>> img = AICSImage("my_file.tiff")
... zstack_t8 = img.get_image_data("ZYX", T=8, C=0)

Initialize an image, construct a delayed dask array for certain slices, then read only the specified chunk of data.

>>> img = AICSImage("my_file.czi")
... zstack_t8 = img.get_image_dask_data("ZYX", T=8, C=0)
... zstack_t8_data = zstack_t8.compute()

Initialize an image with a dask or numpy array.

>>> data = np.random.rand(100, 100)
... img = AICSImage(data)

Initialize an image from S3 with s3fs.

>>> img = AICSImage("s3://my_bucket/my_file.tiff")

Initialize an image and pass arguments to the reader using kwargs.

>>> img = AICSImage("my_file.czi", chunk_dims=["T", "Y", "X"])

Initialize an image, change scene, read data to numpy.

>>> img = AICSImage("my_many_scene.czi")
... img.set_scene("Image:3")
... img.data

Initialize an image with a specific reader. This is useful if you know the file type in advance or would like to skip a few of the file format checks we do internally. Useful when reading from remote sources to reduce network round trips.

>>> img = AICSImage("malformed_metadata.ome.tiff", reader=readers.TiffReader)

Data for a mosaic file is returned pre-stitched (if the base reader supports it).

>>> img = AICSImage("big_mosaic.czi")
... img.dims  # <Dimensions [T: 40, C: 3, Z: 1, Y: 30000, X: 45000]>

Data for mosaic file can be explicitly returned as tiles. This is the same data as a reconstructed mosaic except that the tiles are stored in their own dimension (M).

>>> img = AICSImage("big_mosaic.czi", reconstruct_mosaic=False)
... img.dims  # <Dimensions [M: 150, T: 40, C: 3, Z: 1, Y: 200, X: 300]>

Data is mosaic file but reader doesn’t support tile stitching.

>>> img = AICSImage("unsupported_mosaic.ext")
... img.dims  # <Dimensions [M: 100, T: 1, C: 2, Z: 1, Y: 400, X: 400]>

Notes

If your image is made up of mosaic tiles, data and dimension information returned from this object will be from the tiles already stitched together.

If you do not want the image pre-stitched together, you can use the base reader by either instantiating the reader independently or using the .reader property.

ReaderClass

alias of BioformatsReader

SUPPORTED_READERS: List[Type[Reader]] = [<class 'aicsimageio.readers.bioformats_reader.BioformatsReader'>, <class 'aicsimageio.readers.default_reader.DefaultReader'>, <class 'aicsimageio.readers.array_like_reader.ArrayLikeReader'>, <class 'aicsimageio.readers.czi_reader.CziReader'>, <class 'aicsimageio.readers.dv_reader.DVReader'>, <class 'aicsimageio.readers.lif_reader.LifReader'>, <class 'aicsimageio.readers.nd2_reader.ND2Reader'>, <class 'aicsimageio.readers.bfio_reader.OmeTiledTiffReader'>, <class 'aicsimageio.readers.ome_tiff_reader.OmeTiffReader'>, <class 'aicsimageio.readers.tiff_reader.TiffReader'>, <class 'aicsimageio.readers.ome_zarr_reader.OmeZarrReader'>, <class 'aicsimageio.readers.sldy_reader.SldyReader'>]
property channel_names: List[str]
Returns

channel_names – Using available metadata, the list of strings representing channel names.

Return type

List[str]

property current_scene: str
Returns

scene – The current operating scene.

Return type

str

property current_scene_index: int
Returns

scene_index – The current operating scene index in the file.

Return type

int

property dask_data: Array
Returns

dask_data – The image as a dask array with standard dimension ordering.

Return type

da.Array

Notes

If the image contains mosaic tiles, data is returned already stitched together.

property data: ndarray
Returns

data – The image as a numpy array with standard dimension ordering.

Return type

np.ndarray

Notes

If the image contains mosaic tiles, data is returned already stitched together. Recommended to use dask_data for large mosaic images.

static determine_reader(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], fs_kwargs: Dict[str, Any] = {}, **kwargs: Any) → Type[Reader][source]

Cheaply check to see if a given file is a recognized type and return the appropriate reader for the image.

Returns

ReaderClass – The reader that supports the provided image.

Return type

Type[Reader]

Raises

exceptions.UnsupportedFileFormatError – No reader could be found that supports the provided image.

property dims: Dimensions
Returns

dims – Object with the paired dimension names and their sizes.

Return type

dimensions.Dimensions

property dtype: dtype
Returns

dtype – Data-type of the image array’s elements.

Return type

np.dtype

get_dask_stack(**kwargs: Any) → Array[source]

Get all scenes stacked in to a single array.

Returns

  • stack (da.Array) – The fully stacked array. This can be 6+ dimensions with Scene being the first dimension.

  • kwargs (Any) – Extra keyword arguments that will be passed down to the generate stack function.

See also

aicsimageio.transforms.generate_stack

Underlying function for generating various scene stacks.

get_image_dask_data(dimension_order_out: Optional[str] = None, **kwargs: Any) → Array[source]

Get specific dimension image data out of an image as a dask array.

Parameters

  • dimension_order_out (Optional[str]) – A string containing the dimension ordering desired for the returned ndarray. Default: dimensions.DEFAULT_DIMENSION_ORDER (with or without Samples)

  • kwargs (Any) –

    • C=1: specifies Channel 1

    • T=3: specifies the fourth index in T

    • D=n: D is Dimension letter and n is the index desired. D should not be present in the dimension_order_out.

    • D=[a, b, c]: D is Dimension letter and a, b, c is the list of indices desired. D should be present in the dimension_order_out.

    • D=(a, b, c): D is Dimension letter and a, b, c is the tuple of indices desired. D should be present in the dimension_order_out.

    • D=range(…): D is Dimension letter and range is the standard Python range function. D should be present in the dimension_order_out.

    • D=slice(…): D is Dimension letter and slice is the standard Python slice function. D should be present in the dimension_order_out.

Returns

data – The image data with the specified dimension ordering.

Return type

da.Array

Examples

Specific index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... c1 = img.get_image_dask_data("ZYX", C=1)

List of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_and_second = img.get_image_dask_data("CZYX", C=[0, 1])

Tuple of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_and_last = img.get_image_dask_data("CZYX", C=(0, -1))

Range of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_three = img.get_image_dask_data("CZYX", C=range(3))

Slice selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... every_other = img.get_image_dask_data("CZYX", C=slice(0, -1, 2))

Notes

If a requested dimension is not present in the data the dimension is added with a depth of 1.

See aicsimageio.transforms.reshape_data for more details.

get_image_data(dimension_order_out: Optional[str] = None, **kwargs: Any) → ndarray[source]

Read the image as a numpy array then return specific dimension image data.

Parameters

  • dimension_order_out (Optional[str]) – A string containing the dimension ordering desired for the returned ndarray. Default: dimensions.DEFAULT_DIMENSION_ORDER (with or without Samples)

  • kwargs (Any) –

    • C=1: specifies Channel 1

    • T=3: specifies the fourth index in T

    • D=n: D is Dimension letter and n is the index desired. D should not be present in the dimension_order_out.

    • D=[a, b, c]: D is Dimension letter and a, b, c is the list of indices desired. D should be present in the dimension_order_out.

    • D=(a, b, c): D is Dimension letter and a, b, c is the tuple of indices desired. D should be present in the dimension_order_out.

    • D=range(…): D is Dimension letter and range is the standard Python range function. D should be present in the dimension_order_out.

    • D=slice(…): D is Dimension letter and slice is the standard Python slice function. D should be present in the dimension_order_out.

Returns

data – The image data with the specified dimension ordering.

Return type

np.ndarray

Examples

Specific index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... c1 = img.get_image_data("ZYX", C=1)

List of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_and_second = img.get_image_data("CZYX", C=[0, 1])

Tuple of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_and_last = img.get_image_data("CZYX", C=(0, -1))

Range of index selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... first_three = img.get_image_dask_data("CZYX", C=range(3))

Slice selection

>>> img = AICSImage("s_1_t_1_c_10_z_20.ome.tiff")
... every_other = img.get_image_data("CZYX", C=slice(0, -1, 2))

Notes

  • If a requested dimension is not present in the data the dimension is added with a depth of 1.

  • This will preload the entire image before returning the requested data.

See aicsimageio.transforms.reshape_data for more details.

get_mosaic_tile_position(mosaic_tile_index: int, **kwargs: int) → Tuple[int, int][source]

Get the absolute position of the top left point for a single mosaic tile.

Parameters

  • mosaic_tile_index (int) – The index for the mosaic tile to retrieve position information for.

  • kwargs (int) – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

    Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”).

Returns

  • top (int) – The Y coordinate for the tile position.

  • left (int) – The X coordinate for the tile position.

Raises

UnexpectedShapeError – The image has no mosaic dimension available.

get_mosaic_tile_positions(**kwargs: int) → List[Tuple[int, int]][source]

Get the absolute positions of the top left points for each mosaic tile matching the specified dimensions and current scene.

Parameters

kwargs (int) – The keywords below allow you to specify the dimensions that you wish to match. If you under-specify the constraints you can easily end up with a massive image stack.

Z = 1 # The Z-dimension. C = 2 # The C-dimension (“channel”). T = 3 # The T-dimension (“time”). M = 4 # The mosaic tile index

Returns

mosaic_tile_positions – List of the Y and X coordinate for the tile positions.

Return type

List[Tuple[int, int]]

Raises

  • UnexpectedShapeError – The image has no mosaic dimension available.

  • NotImplementedError – Unable to combine M dimension with other dimensions when finding tiles matching kwargs

get_stack(**kwargs: Any) → ndarray[source]

Get all scenes stacked in to a single array.

Returns

  • stack (np.ndarray) – The fully stacked array. This can be 6+ dimensions with Scene being the first dimension.

  • kwargs (Any) – Extra keyword arguments that will be passed down to the generate stack function.

See also

aicsimageio.transforms.generate_stack

Underlying function for generating various scene stacks.

get_xarray_dask_stack(**kwargs: Any) → DataArray[source]

Get all scenes stacked in to a single array.

Returns

  • stack (xr.DataArray) – The fully stacked array. This can be 6+ dimensions with Scene being the first dimension.

  • kwargs (Any) – Extra keyword arguments that will be passed down to the generate stack function.

See also

aicsimageio.transforms.generate_stack

Underlying function for generating various scene stacks.

Notes

When requesting an xarray stack, the first scene’s coordinate planes are used for the returned xarray DataArray object coordinate planes.

get_xarray_stack(**kwargs: Any) → DataArray[source]

Get all scenes stacked in to a single array.

Returns

  • stack (xr.DataArray) – The fully stacked array. This can be 6+ dimensions with Scene being the first dimension.

  • kwargs (Any) – Extra keyword arguments that will be passed down to the generate stack function.

See also

aicsimageio.transforms.generate_stack

Underlying function for generating various scene stacks.

Notes

When requesting an xarray stack, the first scene’s coordinate planes are used for the returned xarray DataArray object coordinate planes.

property metadata: Any
Returns

metadata – Passthrough to the base image reader metadata property. For more information, see the specific image format reader you are using for details on its metadata property.

Return type

Any

property mosaic_tile_dims: Optional[Dimensions]
Returns

tile_dims – The dimensions for each tile in the mosaic image. If the image is not a mosaic image, returns None.

Return type

Optional[Dimensions]

property ome_metadata: OME
Returns

metadata – The original metadata transformed into the OME specfication. This likely isn’t a complete transformation but is guarenteed to be a valid transformation.

Return type

OME

Raises

NotImplementedError – No metadata transformer available.

property physical_pixel_sizes: PhysicalPixelSizes
Returns

sizes – Using available metadata, the floats representing physical pixel sizes for dimensions Z, Y, and X.

Return type

PhysicalPixelSizes

Notes

We currently do not handle unit attachment to these values. Please see the file metadata for unit information.

property reader: Reader
Returns

reader – The object created to read the image file type. The intent is that if the AICSImage class doesn’t provide a raw enough interface then the base class can be used directly.

Return type

Reader

reader_path = 'aicsimageio.readers.bioformats_reader.BioformatsReader'
reader_paths = ['aicsimageio.readers.bioformats_reader.BioformatsReader']
save(uri: Union[str, Path], select_scenes: Optional[Union[List[str], Tuple[str, ...]]] = None) → None[source]

Saves the file data to OME-TIFF format with general naive best practices.

Parameters

  • uri (types.PathLike) – The URI or local path for where to save the data. Note: Can only write to local file systems.

  • select_scenes (Optional[Union[List[str], Tuple[str, …]]]) – Which scenes in the image to save to the file. Default: None (save all scenes)

Notes

See aicsimageio.writers.OmeTiffWriter for more in-depth specification and the aicsimageio.writers module as a whole for list of all available file writers.

When reading in the produced OME-TIFF file, scenes IDs may have changed. This is due to how certain file and metadata formats do or do-not have IDs and simply names. In converting to OME-TIFF we will always store the scene ids in each Image’s name attribute but IDs will be generated. The order of the scenes will be the same (or whatever order was specified / provided).

property scenes: Tuple[str, ...]
Returns

scenes – A tuple of valid scene ids in the file.

Return type

Tuple[str, …]

Notes

Scene IDs are strings - not a range of integers.

When iterating over scenes please use:

>>> for id in image.scenes

and not:

>>> for i in range(len(image.scenes))
set_scene(scene_id: Union[str, int]) → None[source]

Set the operating scene.

Parameters

scene_id (Union[str, int]) – The scene id (if string) or scene index (if integer) to set as the operating scene.

Raises

  • IndexError – The provided scene id or index is not found in the available scene id list.

  • TypeError – The provided value wasn’t a string (scene id) or integer (scene index).

property shape: Tuple[int, ...]
Returns

shape – Tuple of the image array’s dimensions.

Return type

Tuple[int, …]

property xarray_dask_data: DataArray
Returns

xarray_dask_data – The delayed image and metadata as an annotated data array.

Return type

xr.DataArray

Notes

If the image contains mosaic tiles, data is returned already stitched together.

property xarray_data: DataArray
Returns

xarray_data – The fully read image and metadata as an annotated data array.

Return type

xr.DataArray

Notes

If the image contains mosaic tiles, data is returned already stitched together. Recommended to use xarray_dask_data for large mosaic images.

aicsimageio.aics_image.imread(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], scene_id: Optional[str] = None, **kwargs: Any) → ndarray[source]

Read image as a numpy array.

Parameters

  • image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.

  • scene_id (Optional[str]) – An optional scene id to create the numpy array with. Default: None (First Scene)

  • kwargs (Any) – Extra keyword arguments to be passed down to the AICSImage and Reader subclass.

Returns

data – The image read, scene selected, and returned as an AICS standard shaped np.ndarray.

Return type

np.ndarray

aicsimageio.aics_image.imread_dask(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], scene_id: Optional[str] = None, **kwargs: Any) → Array[source]

Read image as a delayed dask array.

Parameters

  • image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.

  • scene_id (Optional[str]) – An optional scene id to create the dask array with. Default: None (First Scene)

  • kwargs (Any) – Extra keyword arguments to be passed down to the AICSImage and Reader subclass.

Returns

data – The image read, scene selected, and returned as an AICS standard shaped delayed dask array.

Return type

da.core.Array

aicsimageio.aics_image.imread_xarray(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], scene_id: Optional[str] = None, **kwargs: Any) → DataArray[source]

Read image as an in-memory xarray DataArray.

Parameters

  • image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.

  • scene_id (Optional[str]) – An optional scene id to create the DataArray with. Default: None (First Scene)

  • kwargs (Any) – Extra keyword arguments to be passed down to the AICSImage and Reader subclass.

Returns

data – The image read, scene selected, and returned as an AICS standard shaped in-memory DataArray.

Return type

xr.DataArray

aicsimageio.aics_image.imread_xarray_dask(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], scene_id: Optional[str] = None, **kwargs: Any) → DataArray[source]

Read image as a delayed xarray DataArray.

Parameters

  • image (types.ImageLike) – A string, Path, fsspec supported URI, or arraylike to read.

  • scene_id (Optional[str]) – An optional scene id to create the DataArray with. Default: None (First Scene)

  • kwargs (Any) – Extra keyword arguments to be passed down to the AICSImage and Reader subclass.

Returns

data – The image read, scene selected, and returned as an AICS standard shaped delayed xarray DataArray.

Return type

xr.DataArray

aicsimageio.constants module

aicsimageio.dimensions module

class aicsimageio.dimensions.DimensionNames[source]

Bases: object

Channel = 'C'
MosaicTile = 'M'
Samples = 'S'
SpatialX = 'X'
SpatialY = 'Y'
SpatialZ = 'Z'
Time = 'T'
class aicsimageio.dimensions.Dimensions(dims: Collection[str], shape: Tuple[int, ...])[source]

Bases: object

A general object for managing the pairing of dimension name and dimension size.

Parameters

  • dims (Collection[str]) – An ordered string or collection of the dimensions to pair with their sizes.

  • shape (Tuple[int, …]) – An ordered tuple of the dimensions sizes to pair with their names.

Examples

>>> dims = Dimensions("TCZYX", (1, 4, 75, 624, 924))
... dims.X
... dims['T', 'X']
items() → ItemsView[str, int][source]
property order: str
Returns

order – The natural order of the dimensions as a single string.

Return type

str

property shape: Tuple[int, ...]
Returns

shape – The dimension sizes in their natural order.

Return type

Tuple[int, …]

aicsimageio.exceptions module

exception aicsimageio.exceptions.ConflictingArgumentsError[source]

Bases: Exception

This exception is returned when 2 arguments to the same function are in conflict.

exception aicsimageio.exceptions.InvalidDimensionOrderingError[source]

Bases: Exception

A general exception that can be thrown when handling dimension ordering or validation. Should be provided with a message for the user to be given more context.

exception aicsimageio.exceptions.UnexpectedShapeError[source]

Bases: Exception

A general exception that can be thrown when handling shape validation. Should be provided with a message for the user to be given more context.

exception aicsimageio.exceptions.UnsupportedFileFormatError(reader_name: str, path: str, msg_extra: Optional[str] = None)[source]

Bases: Exception

This exception is intended to communicate that the file extension is not one of the supported file types and cannot be parsed with AICSImage.

aicsimageio.formats module

aicsimageio.image_container module

class aicsimageio.image_container.ImageContainer[source]

Bases: ABC

property channel_names: Optional[List[str]]
property current_scene: str
property current_scene_index: int
property dask_data: Array
property data: ndarray
property dims: Dimensions
property dtype: dtype
abstract get_image_dask_data(dimension_order_out: Optional[str] = None, **kwargs: Any) → Array[source]
abstract get_image_data(dimension_order_out: Optional[str] = None, **kwargs: Any) → ndarray[source]
property metadata: Any
property physical_pixel_sizes: PhysicalPixelSizes
abstract property scenes: Tuple[str, ...]
abstract set_scene(scene_id: Union[str, int]) → None[source]
property shape: Tuple[int, ...]
property xarray_dask_data: DataArray
property xarray_data: DataArray

aicsimageio.transforms module

aicsimageio.transforms.generate_stack(image_container: ImageContainer, mode: Literal['data', 'dask_data', 'xarray_data', 'xarray_dask_data'], drop_non_matching_scenes: bool = False, select_scenes: Optional[Union[list[Union[str, int]], tuple[Union[str, int], ...]]] = None, scene_character: str = 'I', scene_coord_values: str = 'index') → Union[ndarray, Array, DataArray][source]

Stack each scene contained in the reader into a single array. This method handles the logic of determining which stack function to use (dask or numpy) and whether or not to return a labelled array (xr.DataArray). Users should prefer to use one of get_stack, get_dask_stack, get_xarray_stack, or get_xarray_dask_stack.

Parameters

  • mode (Literal[“data”, “dask_data”, “xarray_data”, “xarray_dask_data”]) – String describing the style of data to return. Should be one of: “data”, “dask_data”, “xarray_data”, “xarray_dask_data”.

  • drop_non_matching_scenes (bool) – During the scene iteration process, if the next scene to be added to the stack has different shape or dtype, should it be dropped or raise an error. Default: False (raise an error)

  • select_scenes (Optional[) – Union[List[Union[str, int]], Tuple[Union[str, int], …]]] Which scenes to stack into a single array. Scenes can be provided as a list or tuple of scene indices or names. It is recommended to use the scene integer index instead of the scene name to avoid duplicate scene name lookup issues. Default: None (stack all scenes)

  • scene_character (str) – Character to use as the name of the scene dimension on the output array. Default “I”

  • scene_coord_values (str) – How to assign coordinates to the scene dimension of the final array. If scene_coord_values=”names” use the scene name from the reader object. If scene_coord_values=”index” don’t attach any coordinates and fall back to integer values. Default: “index”

Returns

stack – The fully stacked array. This can be 6+ dimensions with Scene being the first dimension.

Return type

types.MetaArrayLike

aicsimageio.transforms.reduce_to_slice(L: Union[List, Tuple]) → Union[int, List, slice, Tuple][source]
aicsimageio.transforms.reshape_data(data: Union[ndarray, Array], given_dims: str, return_dims: str, **kwargs: Any) → Union[ndarray, Array][source]

Reshape the data into return_dims, pad missing dimensions, and prune extra dimensions. Warns the user to use the base reader if the depth of the Dimension being removed is not 1.

Parameters

  • data (types.ArrayLike) – Either a dask array or numpy.ndarray of arbitrary shape but with the dimensions specified in given_dims

  • given_dims (str) – The dimension ordering of data, “CZYX”, “VBTCXZY” etc

  • return_dims (str) – The dimension ordering of the return data

  • kwargs –

    • C=1 => desired specific channel, if C in the input data has depth 3 then C=1 returns the 2nd slice (0 indexed)

    • Z=10 => desired specific channel, if Z in the input data has depth 20 then Z=10 returns the 11th slice

    • T=[0, 1] => desired specific timepoints, if T in the input data has depth 100 then T=[0, 1] returns the 1st and 2nd slice (0 indexed)

    • T=(0, 1) => desired specific timepoints, if T in the input data has depth 100 then T=(0, 1) returns the 1st and 2nd slice (0 indexed)

    • T=(0, -1) => desired specific timepoints, if T in the input data has depth 100 then T=(0, -1) returns the first and last slice

    • T=range(10) => desired specific timepoints, if T in the input data has depth 100 then T=range(10) returns the first ten slices

    • T=slice(0, -1, 5) => desired specific timepoints, T=slice(0, -1, 5) returns every fifth timepoint

Returns

data – The data with the specified dimension ordering.

Return type

types.ArrayLike

Raises

  • ConflictingArgumentsError – Missing dimension in return dims when using range, slice, or multi-index dimension selection for the requested dimension.

  • IndexError – Requested dimension index not present in data.

Examples

Specific index selection

>>> data = np.random.rand((10, 100, 100))
... z1 = reshape_data(data, "ZYX", "YX", Z=1)

List of index selection

>>> data = np.random.rand((10, 100, 100))
... first_and_second = reshape_data(data, "ZYX", "YX", Z=[0, 1])

Tuple of index selection

>>> data = np.random.rand((10, 100, 100))
... first_and_last = reshape_data(data, "ZYX", "YX", Z=(0, -1))

Range of index selection

>>> data = np.random.rand((10, 100, 100))
... first_three = reshape_data(data, "ZYX", "YX", Z=range(3))

Slice selection

>>> data = np.random.rand((10, 100, 100))
... every_other = reshape_data(data, "ZYX", "YX", Z=slice(0, -1, 2))

Empty dimension expansion

>>> data = np.random.rand((10, 100, 100))
... with_time = reshape_data(data, "ZYX", "TZYX")

Dimension order shuffle

>>> data = np.random.rand((10, 100, 100))
... as_zx_base = reshape_data(data, "ZYX", "YZX")

Selections, empty dimension expansions, and dimension order shuffle

>>> data = np.random.rand((10, 100, 100))
... example = reshape_data(data, "CYX", "BSTCZYX", C=slice(0, -1, 3))
aicsimageio.transforms.transpose_to_dims(data: Union[ndarray, Array], given_dims: str, return_dims: str) → Union[ndarray, Array][source]

This shuffles the data dimensions from given_dims to return_dims. Each dimension must be present in given_dims must be used in return_dims

Parameters

  • data (types.ArrayLike) – Either a dask array or numpy.ndarray of arbitrary shape but with the dimensions specified in given_dims

  • given_dims (str) – The dimension ordering of data, “CZYX”, “VBTCXZY” etc

  • return_dims (str) – The dimension ordering of the return data

Returns

data – The data with the specified dimension ordering.

Return type

types.ArrayLike

Raises

ConflictingArgumentsError – given_dims and return_dims are incompatible.

aicsimageio.types module

class aicsimageio.types.PhysicalPixelSizes(Z, Y, X)[source]

Bases: NamedTuple

Create new instance of PhysicalPixelSizes(Z, Y, X)

X: Optional[float]

Alias for field number 2

Y: Optional[float]

Alias for field number 1

Z: Optional[float]

Alias for field number 0

Module contents

Top-level package for AICSImageIO.

aicsimageio.get_module_version() → str[source]