aicsimageio package

Submodules

aicsimageio.aics_image module

class aicsimageio.aics_image.AICSImage[source]

Bases: object

AICSImage takes microscopy image data types (files) of varying dimensions (“ZYX”, “TCZYX”, “CYX”) and puts them into a consistent 6D “STCZYX” ordered dask array. The data, metadata are lazy loaded and can be accessed as needed. Note the dims are assumed to match “STCZYX” from right to left meaning if dimensional data is provided then the dimensions are assigned to be “CZYX”, 2 dimensional would be “YX”. This guessed assignment is only for file types without dimension metadata (i.e. not .ome.tiff or .czi).

Parameters

  • data (types.ImageLike) – String with path to file, numpy.ndarray, or dask.array.Array with up to six dimensions.

  • known_dims (Optional[str]) – Optional string with the known dimension order. If None, the reader will attempt to parse dim order.

  • dask_kwargs (Dict[str, Any] = {}) – A dictionary of arguments to pass to a dask cluster and or client.

  • kwargs (Dict[str, Any]) – Extra keyword arguments that can be passed down to either the reader subclass or, if using the context manager, the LocalCluster initialization.

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", S=0, T=8, C=0)

Initialize an image, construct a delayed dask array for certain slices, then read only that data.

>>> img = AICSImage("my_file.czi")
... zstack_t8 = img.get_image_dask_data("ZYX", S=0, 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 and pass arguments to the reader using kwargs.

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

Create a local dask cluster for the duration of the context manager.

>>> with AICSImage("filename.ome.tiff") as img:
...     data = img.get_image_data("ZYX", S=0, T=0, C=0)

Create a local dask cluster with arguments for the duration of the context manager.

>>> with AICSImage("filename.ome.tiff", dask_kwargs={"nworkers": 4}) as img:
...     data = img.get_image_data("ZYX", S=0, T=0, C=0)

Connect to a specific dask cluster for the duration of the context manager.

>>> with AICSImage(
...     "filename.ome.tiff",
...     dask_kwargs={"address": "tcp://localhost:1234"},
...     ) as img:
...     data = img.get_image_data("ZYX", S=0, T=0, C=0)

Notes

When using the AICSImage context manager, the processing machine or container must have networking capabilities enabled to function properly.

Constructor for AICSImage class intended for providing a unified interface for dealing with microscopy images. To extend support to a new reader simply add a new reader child class of Reader ([readers/reader.py]) and add the class to SUPPORTED_READERS variable.

property client

If connected to a Dask cluster, return the connected Client.

close()[source]

Close the connection to the Dask distributed Client. If this object created a LocalCluster, close it down as well.

property cluster

If this object created a local Dask cluster, return it.

property dask_data

Returns a dask array with dimension ordering “STCZYX”.

property data

Return the entire image as a numpy array with dimension ordering “STCZYX”.

static determine_reader()[source]

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

get_channel_names()[source]

Attempts to use the image’s metadata to get the image’s channel names.

Parameters

scene (int) – The index of the scene for which to return channel names.

Returns

channels_names – List of strings representing the channel names.

Return type

List[str]

get_image_dask_data(out_orientation: Optional[str] = None, **kwargs) → dask.array.core.Array[source]

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

Parameters

  • out_orientation (Optional[str]) – A string containing the dimension ordering desired for the returned ndarray. Default: The current image dimensions. i.e. self.dims

  • kwargs –

    • 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 out_orientation.

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

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

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

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

Returns

data – The read data with the dimension ordering that was specified with out_orientation.

Return type

dask 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(out_orientation: Optional[str] = None, **kwargs) → numpy.ndarray[source]

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

Parameters

  • out_orientation (Optional[str]) – A string containing the dimension ordering desired for the returned ndarray. Default: The current image dimensions. i.e. self.dims

  • kwargs –

    • 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 out_orientation.

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

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

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

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

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_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))
Returns

data – The read data with the dimension ordering that was specified with out_orientation.

Return type

np.ndarray

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_physical_pixel_size()[source]

Attempts to retrieve physical pixel size for the specified scene. If none available, returns 1.0 for each spatial dimension.

Parameters

scene (int) – The index of the scene for which to return physical pixel sizes.

Returns

sizes – Tuple of floats representing the pixel sizes for X, Y, Z, in that order.

Return type

Tuple[float]

property metadata
Returns

metadata – The Metadata from the Czi, or Ome.Tiff file, or other base class type with metadata. For pure image files an empty string or None is returned.

Return type

Any

property reader

This property returns the class 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.

Returns

reader – A child of Reader; CziReader OmeTiffReader, TiffReader, DefaultReader, etc.

Return type

Reader

property shape
Returns

shape – A tuple with the size of all dimensions.

Return type

Tuple[int]

size()[source]
Parameters

dims (str) – A string containing a list of dimensions being requested. The default is to return the six standard dims.

Returns

size – A tuple with the requested dimensions filled in.

Return type

Tuple[int]

property size_c
Returns

size – The size of the Channel dimension.

Return type

int

property size_s
Returns

size – The size of the Scene dimension.

Return type

int

property size_t
Returns

size – The size of the Time dimension.

Return type

int

property size_x
Returns

size – The size of the Spatial X dimension.

Return type

int

property size_y
Returns

size – The size of the Spatial Y dimension.

Return type

int

property size_z
Returns

size – The size of the Spatial Z dimension.

Return type

int

view_napari(rgb: bool = False, **kwargs)[source]

If installed, load the image in a napari viewer.

Parameters

  • rgb (bool) – Is the image RGB / RGBA Default: False (is not RGB)

  • **kwargs – Extra arguments passed down to the viewer

aicsimageio.aics_image.imread(data: Union[str, pathlib.Path, bytes, io.BufferedIOBase, numpy.ndarray, dask.array.core.Array], **kwargs) → numpy.ndarray[source]

Read image as a numpy ndarray.

Parameters

  • data (types.ImageLike) – A filepath, in memory numpy array, or preconfigured dask array.

  • kwargs (Dict[str, Any]) – Any extra arguments to passed down to AICSImage and subsequent readers.

Returns

data – The image read and configured as a numpy ndarray.

Return type

np.ndarray

aicsimageio.aics_image.imread_dask(data: Union[str, pathlib.Path, bytes, io.BufferedIOBase, numpy.ndarray, dask.array.core.Array], **kwargs) → dask.array.core.Array[source]

Read image as a dask array.

Parameters

  • data (types.ImageLike) – A filepath, in memory numpy array, or preconfigured dask array.

  • kwargs (Dict[str, Any]) – Any extra arguments to passed down to AICSImage and subsequent readers.

Returns

data – The image read and configured as a dask array.

Return type

da.core.Array

aicsimageio.buffer_reader module

class aicsimageio.buffer_reader.BufferReader(buffer: Union[str, pathlib.Path, bytes, io.BufferedIOBase])[source]

Bases: object

INTEL_ENDIAN = b'II'
MOTOROLA_ENDIAN = b'MM'
read_bytes(n_bytes: int)[source]
read_uint16()[source]
read_uint32()[source]
read_uint64()[source]
reset()[source]

aicsimageio.constants module

class aicsimageio.constants.Dimensions[source]

Bases: object

Channel = 'C'
DefaultOrder = 'STCZYX'
DefaultOrderList = ['S', 'T', 'C', 'Z', 'Y', 'X']
Scene = 'S'
SpatialX = 'X'
SpatialY = 'Y'
SpatialZ = 'Z'
Time = 'T'

aicsimageio.dask_utils module

aicsimageio.dask_utils.cluster_and_client(address: Optional[str] = None, **kwargs)[source]

If provided an address, create a Dask Client connection. If not provided an address, create a LocalCluster and Client connection. If not provided an address, other Dask kwargs are accepted and passed down to the LocalCluster object.

These objects will only live for the duration of this context manager.

Examples

>>> with cluster_and_client() as (cluster, client):
...     img1 = AICSImage("1.tiff")
...     img2 = AICSImage("2.czi")
...     other processing

Notes

When using this context manager, the processing machine or container must have networking capabilities enabled to function properly.

aicsimageio.dask_utils.shutdown_cluster_and_client()[source]

Shutdown a cluster and client.

Notes

When using this function, the processing machine or container must have networking capabilities enabled to function properly.

aicsimageio.dask_utils.spawn_cluster_and_client()[source]

If provided an address, create a Dask Client connection. If not provided an address, create a LocalCluster and Client connection. If not provided an address, other Dask kwargs are accepted and passed down to the LocalCluster object.

Notes

When using this function, the processing machine or container must have networking capabilities enabled to function properly.

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.InconsistentPixelType[source]

Bases: Exception

This exception is returned when the metadata has conflicting pixel types.

exception aicsimageio.exceptions.InconsistentShapeError[source]

Bases: Exception

A general function to use when the shape returned or requested from an array operation is invalid.

exception aicsimageio.exceptions.InvalidDimensionOrderingError(message: str, **kwargs)[source]

Bases: Exception

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

exception aicsimageio.exceptions.UnsupportedFileFormatError(data, **kwargs)[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.transforms module

aicsimageio.transforms.reshape_data(data: Union[numpy.ndarray, dask.array.core.Array], given_dims: str, return_dims: str, **kwargs) → Union[numpy.ndarray, dask.array.core.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 – An array in return_dims order, if return_dims=DEFAULT_DIMS then the return would have order “STCZYX”

Return type

types.ArrayLike

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[numpy.ndarray, dask.array.core.Array], given_dims: str, return_dims: str) → Union[numpy.ndarray, dask.array.core.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

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 – An array in return_dims order, if return_dims=DEFAULT_DIMS then the return would have order “STCZYX”

Return type

types.ArrayLike

aicsimageio.types module

Collection of types used across multiple objects and functions.

class aicsimageio.types.LoadResults(data, dims, metadata)[source]

Bases: tuple

Create new instance of LoadResults(data, dims, metadata)

data

Alias for field number 0

dims

Alias for field number 1

metadata

Alias for field number 2

Module contents