aicsimageio.readers package

Subpackages

aicsimageio.readers.sldy_reader package

Submodules

aicsimageio.readers.array_like_reader module

class aicsimageio.readers.array_like_reader.ArrayLikeReader(image: Union[List[Union[ndarray, Array, DataArray]], ndarray, Array, DataArray], dim_order: Optional[Union[List[str], str]] = None, channel_names: Optional[Union[List[str], List[List[str]]]] = None, physical_pixel_sizes: Optional[Union[List[float], Dict[str, float], PhysicalPixelSizes]] = None, **kwargs: Any)[source]

Bases: Reader

A catch all for numpy, dask, or xarray to Reader interface.

See Notes for more details.

Parameters

image (Union[List[MetaArrayLike], MetaArrayLike]) – A single, numpy ndarray, dask Array, or xarray DataArray, or list of many. If provided a list, each item in the list will be exposed through the scene API. If provided an xarray DataArray alone or as an element of the list, the dim_order and channel_names kwargs are ignored if there non-xarray default dimension (or channel coordinate) information attached the xarray object. The channel and dimension information are updated independent of the other. If either is using xarray default values, they will be replaced by AICSImageIO defaults will be added.
dim_order (Optional[Union[List[str], str]]) – A string of dimensions to be applied to all array(s) or a list of string dimension names to be mapped onto the list of arrays provided to image. I.E. “TYX”. Default: None (guess dimensions for single array or multiple arrays)
channel_names (Optional[Union[List[str], List[List[str]]]]) – A list of string channel names to be applied to all array(s) or a list of lists of string channel names to be mapped onto the list of arrays provided to image. Default: None (create OME channel IDs for names for single or multiple arrays)
physical_pixel_sizes (Optional[) – Union[List[float], Dict[str, float], PhysicalPixelSizes]
] – A specification of this image’s physical pixel sizes. Can be provided as a list, dict or PhysicalPixelSizes object. If a list is passed, the assumed order is [Z, Y, X]. If a dict is passed, it must contain “Z”, “Y” and “X” as keys. Default: None

Raises

exceptions.ConflictingArgumentsError – Raised when the number of scenes provided is different from the number of items provided to the metadata parameters if as a list.
exceptions.ConflictingArgumentsError – Raised when channel_names is provided but the channel dimension was either not guessed or not provided in dim_order.
ValueError – Provided dim_order string or channel_names are not the same length as the number of dimensions or the size of the channel dimensions for the array at the matching index.

Notes

If you want to combine multiple numpy ndarrays or dask arrays with xarray DataArrays and attach metadata to all non-xarray.DataArrays, you can do so, the metadata for the xarray DataArray scenes will simply be ignored if it the non-xarray defaults.

In such cases, it is recommended that you provide metadata for those scenes as None. I.E.

>>> some_metadata_attached_xr = ...
... some_np = ...
... some_dask = ...
... reader = ArrayLikeReader(
...     image=[some_metadata_attached_xr, some_np, some_dask],
...     dim_order=[None, "CTYX", "ZTYX"],
...     channel_names=[None, ["A", "B", C"], None],
... )

Will create a three scene ArrayLikeReader with the metadata and coordinate information filled xarray DataArray as the first scene, a numpy array with CTYX as the dimensions and [“A”, “B”, “C”] as the channel names, and a dask array with ZTYX as the dimensions and no channel names (as there is no channel dimension).

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

aicsimageio.readers.bfio_reader module

class aicsimageio.readers.bfio_reader.BfioReader(image: Union[str, Path], chunk_dims: Optional[Union[List[str], str]] = None, out_order: str = 'TCZYX', fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: Reader

Abstract bfio reader to utilize optimized readers for ome tiled tiffs and ome zarr.

Parameters

image (types.PathLike) – Path to image file.
chunk_dims (List[str]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, and Dimensions.SpatialX will always be added to the list if not present during dask array construction.
out_order (List[str]) – The output dimension ordering. Default: DEFAULT_DIMENSION_ORDER
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Notes

If the OME metadata in your file isn’t OME schema compliant or does not validate this will fail to read your file and raise an exception.

If the OME metadata in your file doesn’t use the latest OME schema (2016-06), this reader will make a request to the referenced remote OME schema to validate.

backend: Optional[str] = None

property channel_names: Optional[List[str]]

Returns: channel_names – Using available metadata, the list of strings representing channel names. If no channel dimension present in the data, returns None.
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 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 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]

For all BfioReader subclasses, the only allowed value is the name of the first scene since only the first scene can be read by BioReader objects. This method exists primarily to help this Reader fit into existing unit test templates and in case BioReader is updated to support multiple scenes.

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 does not reference the first scene.
TypeError – The provided value wasn’t a string (scene id) or integer (scene index).

class aicsimageio.readers.bfio_reader.OmeTiledTiffReader(image: Union[str, Path], chunk_dims: Optional[Union[List[str], str]] = None, out_order: str = 'TCZYX', fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: BfioReader

Wrapper around bfio.BioReader(backend=”python”).

The OmeTiledTiffReader is an optimized TIFF reader written in pure Python, built on top of tifffile. This reader is optimized for speed and scalability, but will only read TIFF files that meet the following requirements:

TileWidth and TileHeight tags must both be set to 1024
The Description tag must contain OMEXML
The OMEXML channel ordering must be set to XYZCT
Channels cannot be interleaved, meaning individual channels must be planes.

The advantage of the reader for files that meet these requirements are improvements in reading speed, especially when accessing data using dask.

This TIFF reader will only read the first image and pyramid layer. If pyramid layers or images beyond the first image in the file need to be read, use the OmeTiffReader.

Parameters

image (types.PathLike) – Path to image file.
chunk_dims (List[str]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, and Dimensions.SpatialX will always be added to the list if not present during dask array construction.
out_order (List[str]) – The output dimension ordering. Default: DEFAULT_DIMENSION_ORDER

Notes

If the OME metadata in your file isn’t OME schema compliant or does not validate this will fail to read your file and raise an exception.

If the OME metadata in your file doesn’t use the latest OME schema (2016-06), this reader will make a request to the referenced remote OME schema to validate.

backend: str = 'python'

aicsimageio.readers.bioformats_reader module

class aicsimageio.readers.bioformats_reader.BioFile(path: types.PathLike, series: int = 0, meta: bool = True, *, original_meta: bool = False, memoize: Union[int, bool] = 0, options: Dict[str, bool] = {}, dask_tiles: bool = False, tile_size: Optional[Tuple[int, int]] = None)[source]

Bases: object

Read image and metadata from file supported by Bioformats.

BioFile instances must be closed using the ‘close’ method, which is automatically called when using the ‘with’ context manager.

BioFile instances are not thread-safe.

Bio-Formats is licensed under GPLv2 and is not included in this package.

Parameters

path (str or Path) – path to file
series (int, optional) – the image series to read, by default 0
meta (bool, optional) – whether to get metadata as well, by default True
original_meta (bool, optional) – whether to also retrieve the proprietary metadata as structured annotations in the OME output, by default False
memoize (bool or int, optional) – threshold (in milliseconds) for memoizing the reader. If the the time required to call reader.setId() is larger than this number, the initialized reader (including all reader wrappers) will be cached in a memo file, reducing time to load the file on future reads. By default, this results in a hidden .bfmemo file in the same directory as the file. The BIOFORMATS_MEMO_DIR environment can be used to change the memo file directory. Set memoize to greater than 0 to turn on memoization. by default it’s off. https://downloads.openmicroscopy.org/bio-formats/latest/api/loci/formats/Memoizer.html
options (Dict[str, bool], optional) – A mapping of option-name -> bool specifying additional reader-specific options. see: https://docs.openmicroscopy.org/bio-formats/latest/formats/options.html For example: to turn off chunkmap table reading for ND2 files, use options={“nativend2.chunkmap”: False}
dask_tiles (bool, optional) – Whether to chunk the bioformats dask array by tiles to easily read sub-regions with numpy-like array indexing Defaults to false and images are read by entire planes
tile_size (Optional[Tuple[int, int]]) – Tuple that sets the tile size of y and x axis, respectively By default, it will use optimal values computed by bioformats itself

close() → None[source]: Close file.

property closed: bool: Whether the underlying file is currently open

property core_meta: CoreMeta

property filename: str: Return name of file handle.

property ome_metadata: OME: Return OME object parsed by ome_types.

property ome_xml: str: return OME XML string.

open() → None[source]: Open file.

set_series(series: int = 0) → None[source]

to_dask(series: Optional[int] = None) → ResourceBackedDaskArray[source]

Create dask array for the specified or current series.

Note: the order of the returned array will always be TCZYX[r], where [r] refers to an optional RGB dimension with size 3 or 4. If the image is RGB it will have ndim==6, otherwise ndim will be 5.

The returned object is a ResourceBackedDaskArray, which is a wrapper on a dask array that ensures the file is open when actually reading (computing) a chunk. It has all the methods and behavior of a dask array. See: https://github.com/tlambert03/resource-backed-dask-array

Return type: ResourceBackedDaskArray

to_numpy(series: Optional[int] = None) → ndarray[source]

Create numpy array for the specified or current series.

Note: the order of the returned array will always be TCZYX[r], where [r] refers to an optional RGB dimension with size 3 or 4. If the image is RGB it will have ndim==6, otherwise ndim will be 5.

Parameters: series (int, optional) – The series index to retrieve, by default None

class aicsimageio.readers.bioformats_reader.BioformatsReader(image: types.PathLike, *, original_meta: bool = False, memoize: Union[int, bool] = 0, options: Dict[str, bool] = {}, dask_tiles: bool = False, tile_size: Optional[Tuple[int, int]] = None, fs_kwargs: Dict[str, Any] = {})[source]

Bases: Reader

Read files using bioformats.

This reader requires bioformats_jar to be installed in the environment, and requires the java executable to be available on the path (or via the JAVA_HOME environment variable), along with the mvn executable.

To install java and maven with conda, run conda install -c conda-forge scyjava. You may need to deactivate/reactivate your environment after installing. If you are still getting a JVMNotFoundException, try setting JAVA_HOME as follows:

# mac and linux: export JAVA_HOME=$CONDA_PREFIX

# windows: set JAVA_HOME=%CONDA_PREFIX%Library

Parameters

image (Path or str) – path to file
original_meta (bool, optional) – whether to also retrieve the proprietary metadata as structured annotations in the OME output, by default False
memoize (bool or int, optional) – threshold (in milliseconds) for memoizing the reader. If the the time required to call reader.setId() is larger than this number, the initialized reader (including all reader wrappers) will be cached in a memo file, reducing time to load the file on future reads. By default, this results in a hidden .bfmemo file in the same directory as the file. The BIOFORMATS_MEMO_DIR environment can be used to change the memo file directory. Set memoize to greater than 0 to turn on memoization. by default it’s off. https://downloads.openmicroscopy.org/bio-formats/latest/api/loci/formats/Memoizer.html
options (Dict[str, bool], optional) – A mapping of option-name -> bool specifying additional reader-specific options. see: https://docs.openmicroscopy.org/bio-formats/latest/formats/options.html For example: to turn off chunkmap table reading for ND2 files, use options={“nativend2.chunkmap”: False}
dask_tiles (bool, optional) – Whether to chunk the bioformats dask array by tiles to easily read sub-regions with numpy-like array indexing Defaults to false and iamges are read by entire planes
tile_size (Optional[Tuple[int, int]]) – Tuple that sets the tile size of y and x axis, respectively By default, it will use optimal values computed by bioformats itself
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Raises

exceptions.UnsupportedFileFormatError – If the file is not supported by bioformats.

static bioformats_version() → str[source]: The version of the bioformats_package.jar being used.

property ome_metadata: OME: Return OME object parsed by ome_types.

property physical_pixel_sizes: types.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 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))

class aicsimageio.readers.bioformats_reader.CoreMeta(shape: Tuple[int, int, int, int, int, int], dtype: np.dtype, series_count: int, is_rgb: bool, is_interleaved: bool, dimension_order: str, resolution_count: int)[source]

Bases: NamedTuple

NamedTuple with core bioformats metadata. (not OME meta)

Create new instance of CoreMeta(shape, dtype, series_count, is_rgb, is_interleaved, dimension_order, resolution_count)

dimension_order: str: Alias for field number 5

dtype: dtype: Alias for field number 1

is_interleaved: bool: Alias for field number 4

is_rgb: bool: Alias for field number 3

resolution_count: int: Alias for field number 6

series_count: int: Alias for field number 2

shape: Tuple[int, int, int, int, int, int]: Alias for field number 0

aicsimageio.readers.czi_reader module

class aicsimageio.readers.czi_reader.CziReader(image: Union[str, Path], chunk_dims: Union[str, List[str]] = ['Z', 'Y', 'X', 'S'], include_subblock_metadata: bool = False, fs_kwargs: Dict[str, Any] = {})[source]

Bases: Reader

Wraps the aicspylibczi API to provide the same aicsimageio Reader API but for volumetric Zeiss CZI images.

Parameters

image (types.PathLike) – Path to image file to construct Reader for.
chunk_dims (Union[str, List[str]]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: DimensionNames.SpatialY, DimensionNames.SpatialX, and DimensionNames.Samples, will always be added to the list if not present during dask array construction.
include_subblock_metadata (bool) – Whether to append metadata from the subblocks to the rest of the embeded metadata.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Notes

To use this reader, install with: pip install aicspylibczi>=3.1.1.

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.

Notes

Defaults T and C dimensions to 0 if present as dimensions in image to avoid reading in massive image stack for large files.

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”).
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.

property mapped_dims: str

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 scenes: Tuple[str, ...]

scenes with no name (None) will be renamed to “filename-<scene index>” to prevent ambiguity. Similarly, scenes with same names are automatically appended with occurrence number to distinguish between the two.

Returns:: Tuple[str, …]: Scene names/id

Type: Note

aicsimageio.readers.default_reader module

class aicsimageio.readers.default_reader.DefaultReader(image: Union[str, Path], dim_order: Optional[str] = None, channel_names: Optional[List[str]] = None, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: Reader

A catch all for image file reading that defaults to using imageio implementations.

Parameters

image (types.PathLike) – Path to image file to construct Reader for.
dim_order (Optional[str]) – Optional string of dimension short names for the image to use instead of guess. Must provide the same number of dimensions as read. Default: None (guess)
channel_names (Optional[List[str]]) – Optional list of channel names. Must provide the same number of channels as the read channel dimension. Default: None (generate standard names)
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Notes

To use this reader, install with: pip install aicsimageio[base-imageio].

FFMPEG_FORMATS = ['mov', 'avi', 'mpg', 'mpeg', 'mp4', 'mkv', 'wmv', 'ogg']

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

aicsimageio.readers.dv_reader module

class aicsimageio.readers.dv_reader.DVReader(image: Union[str, Path], fs_kwargs: Dict[str, Any] = {})[source]

Bases: Reader

Read DV/Deltavision files.

This reader requires mrc to be installed in the environment.

Parameters

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

Raises

exceptions.UnsupportedFileFormatError – If the file is not a supported dv file.

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

aicsimageio.readers.lif_reader module

class aicsimageio.readers.lif_reader.LifReader(image: Union[str, Path], chunk_dims: Union[str, List[str]] = ['Z', 'Y', 'X', 'S'], fs_kwargs: Dict[str, Any] = {}, is_x_flipped: bool = False, is_y_flipped: bool = False, is_x_and_y_swapped: bool = True)[source]

Bases: Reader

Wraps the readlif API to provide the same aicsimageio Reader API but for volumetric LIF images.

Parameters

image (types.PathLike) – Path to image file to construct Reader for.
chunk_dims (Union[str, List[str]]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, Dimensions.SpatialX, and DimensionNames.Samples, will always be added to the list if not present during dask array construction.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Notes

To use this reader, install with: pip install readlif>=0.6.4.

readlif is licensed under GPLv3 and is not included in this package.

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. Not equivalent to readlif’s notion of mosaic_position.

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.
IndexError – No matching mosaic tile index found.

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”).

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 – This reader does not support indexing tiles by dimensions other than M

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

aicsimageio.readers.nd2_reader module

class aicsimageio.readers.nd2_reader.ND2Reader(image: Union[str, Path], fs_kwargs: Dict[str, Any] = {})[source]

Bases: Reader

Read NIS-Elements files using the Nikon nd2 SDK.

This reader requires nd2 to be installed in the environment.

Parameters

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

Raises

exceptions.UnsupportedFileFormatError – If the file is not supported by ND2.

property ome_metadata: OME

Return OME metadata.

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

aicsimageio.readers.ome_tiff_reader module

class aicsimageio.readers.ome_tiff_reader.OmeTiffReader(image: Union[str, Path], chunk_dims: Union[str, List[str]] = ['Z', 'Y', 'X', 'S'], clean_metadata: bool = True, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: TiffReader

Wraps the tifffile and ome-types APIs to provide the same aicsimageio Reader API but for volumetric OME-TIFF images. :Parameters: * image (types.PathLike) – Path to image file to construct Reader for.

chunk_dims (List[str]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, Dimensions.SpatialX, and DimensionNames.Samples, will always be added to the list if not present during dask array construction.

clean_metadata (bool) – Should the OME XML metadata found in the file be cleaned for known AICSImageIO 3.x and earlier created errors. Default: True (Clean the metadata for known errors)

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

Notes

If the OME metadata in your file isn’t OME schema compilant or does not validate this will fail to read your file and raise an exception. If the OME metadata in your file doesn’t use the latest OME schema (2016-06), this reader will make a request to the referenced remote OME schema to validate.

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

aicsimageio.readers.ome_zarr_reader module

class aicsimageio.readers.ome_zarr_reader.OmeZarrReader(image: Union[str, Path], fs_kwargs: Dict[str, Any] = {})[source]

Bases: Reader

Wraps the ome-zarr-py API to provide the same aicsimageio Reader API but for OmeZarr images.

Parameters

image (types.PathLike) – Path to image file to construct Reader for.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

property channel_names: Optional[List[str]]

Returns: channel_names – Using available metadata, the list of strings representing channel names. If no channel dimension present in the data, returns None.
Return type: List[str]

property physical_pixel_sizes: PhysicalPixelSizes: Return the physical pixel sizes of the image.

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

aicsimageio.readers.reader module

class aicsimageio.readers.reader.Reader(image: Any, **kwargs: Any)[source]

Bases: ImageContainer, ABC

A small class to build standardized image reader objects that deal with the raw image and metadata.

Parameters

image (Any) – Some type of object to read and follow the Reader specification.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Notes

It is up to the implementer of the Reader to decide which types they would like to accept (certain readers may not support buffers for example).

property channel_names: Optional[List[str]]

Returns: channel_names – Using available metadata, the list of strings representing channel names. If no channel dimension present in the data, returns None.
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 the native dimension ordering.
Return type: da.Array

property data: ndarray

Returns: data – The image as a numpy array with native dimension ordering.
Return type: np.ndarray

property dims: Dimensions

Returns: dims – Object with the paired dimension names and their sizes.
Return type: 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: The natural image dimension order.
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 = Reader("s_1_t_1_c_10_z_20.ome.tiff")
... c1 = img.get_image_dask_data("ZYX", C=1)

List of index selection

>>> img = Reader("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 = Reader("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 = Reader("s_1_t_1_c_10_z_20.ome.tiff")
... first_three = img.get_image_dask_data("CZYX", C=range(3))

Slice selection

>>> img = Reader("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: The natural image dimension order.
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 = Reader("s_1_t_1_c_10_z_20.ome.tiff")
... c1 = img.get_image_data("ZYX", C=1)

List of index selection

>>> img = Reader("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 = Reader("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 = Reader("s_1_t_1_c_10_z_20.ome.tiff")
... first_three = img.get_image_dask_data("CZYX", C=range(3))

Slice selection

>>> img = Reader("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.
IndexError – No matching mosaic tile index found.

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”).
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.

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.

classmethod is_supported_image(image: Union[str, Path, ndarray, Array, DataArray, List[Union[ndarray, Array, DataArray]], List[Union[str, Path]]], fs_kwargs: Dict[str, Any] = {}, **kwargs: Any) → bool[source]

Asserts that the provided image like object is supported by the current Reader.

Parameters

image (types.ImageLike) – The filepath or array to validate as a supported type.
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}
kwargs (Any) – Any kwargs used for reading and validation of the file.

Returns

supported – Boolean indicated if the provided data is or is not supported by the current Reader.

Return type

bool

Raises

TypeError – Invalid type provided to image parameter.

property metadata: Any

Returns

metadata – The metadata for the formats supported by the inhereting Reader.

If the inheriting Reader supports processing the metadata into a more useful format / Python object, this will return the result.

For both the unprocessed and processed metadata from the file, use xarray_dask_data.attrs which will contain a dictionary with keys: unprocessed and processed that you can then select.

Return type

Any

property mosaic_dask_data: Array

Returns: dask_data – The stitched together mosaic image as a dask array.
Return type: da.Array
Raises: InvalidDimensionOrderingError – No MosaicTile dimension available to reader.

Notes

Each reader can implement mosaic tile stitching differently but it is common that each tile is a dask array chunk.

property mosaic_data: ndarray

Returns: data – The stitched together mosaic image as a numpy array.
Return type: np.ndarray
Raises: InvalidDimensionOrderingError – No MosaicTile dimension available to reader.

Notes

Very large images should use mosaic_dask_data to avoid seg-faults.

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 mosaic_xarray_dask_data: DataArray

Returns: xarray_dask_data – The delayed mosaic image and metadata as an annotated data array.
Return type: xr.DataArray
Raises: InvalidDimensionOrderingError – No MosaicTile dimension available to reader.

Notes

Each reader can implement mosaic tile stitching differently but it is common that each tile is a dask array chunk.

property mosaic_xarray_data: DataArray

Returns: xarray_dask_data – The in-memory mosaic image and metadata as an annotated data array.
Return type: xr.DataArray
Raises: InvalidDimensionOrderingError – No MosaicTile dimension available to reader.

Notes

Very large images should use mosaic_xarray_dask_data to avoid seg-faults.

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.

abstract 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

property xarray_data: DataArray

Returns: xarray_data – The fully read image and metadata as an annotated data array.
Return type: xr.DataArray

aicsimageio.readers.tiff_glob_reader module

class aicsimageio.readers.tiff_glob_reader.TiffGlobReader(glob_in: Union[str, Path, Iterable[Union[str, Path]]], indexer: Optional[Union[DataFrame, Callable]] = None, scene_glob_character: str = 'S', chunk_dims: Union[str, List[str]] = ['Z', 'Y', 'X', 'S'], dim_order: Optional[Union[List[str], str]] = None, channel_names: Optional[Union[List[str], List[List[str]]]] = None, single_file_shape: Optional[Tuple] = None, single_file_dims: Sequence[str] = ('Y', 'X'), fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: Reader

Wraps the tifffile imread API to provide the same aicsimageio Reader API but for multifile tiff datasets (and other tifffile supported) images.

Parameters

glob_in (Union[PathLike, Iterable[PathLike]]) – Glob string that identifies all files to be loaded or an iterable of paths to the files as returned by glob.
indexer (Union[Callable, pandas.DataFrame]) – If callable, should consume each filename and return a pd.Series with series index corresponding to the dimensions and values corresponding to the array index of that image file within the larger array. Default: None (Look for 4 numbers in the file name and use them as S, T, C, and Z indices.)
scene_glob_character (str) – Character to represent different scenes. Default: “S”
chunk_dims (Union[str, List[str]]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, Dimensions.SpatialX, and DimensionNames.Samples, will always be added to the list if not present during dask array construction.
dim_order (Optional[Union[List[str], str]]) – A string of dimensions to be applied to all array(s) or a list of string dimension names to be mapped onto the list of arrays provided to image. I.E. “TYX”. Default: None (guess dimensions for single array or multiple arrays)
channel_names (Optional[Union[List[str], List[List[str]]]]) – A list of string channel names to be applied to all array(s) or a list of lists of string channel names to be mapped onto the list of arrays provided to image. Default: None (create OME channel IDs for names for single or multiple arrays)
single_file_shape (Optional[Tuple]) – Expected shape for a single file of the set. If not provided, will attempt to determine the shape from the first file found in the glob. Default : None
single_file_dims (Optional[Tuple]) – Dimensions that correspond to the data dimensions of a single file in the glob. Default : (‘Y’, ‘X’)
fs_kwargs (Dict[str, Any]) – Any specific keyword arguments to pass down to the fsspec created filesystem. Default: {}

Examples

# Given files with names like “Position001_t002_c03_z04.tif”

reader = TiffGlobReader(“path/to/data/*.tif”)

# We can use this to read single image tiffs generated by MicroManager # Micromanager creates directories for each position so we need to recursively glob # for the images files and pass the list to TiffGlobReader. Note that all images are # named according to img_channel000_position001_time000000003_z004.tif”

import glob files = glob.glob(“path/to/data/**/*.tif”, recursive=True)

# since the numbers in Micromanager files are not in STCZ order we # need to use a different indexer than default. For convenience # when working MicroManager generated files you can use the provided # TiffGlobReader.MicroManagerIndexer

mm_reader = TiffGlobReader(files, indexer=TiffGlobReader.MicroManagerIndexer)

# as an example of making a custom indexer you can manually create # the MicroManagerIndexer like so:

import pandas as pd from pathlib import Path import re def mm_indexer(path_to_img):

inds = re.findall(r”d+”, Path(path_to_img).name) series = pd.Series(inds, index=[‘C’, ‘S’, ‘T’, ‘Z’]).astype(int) return series

mm_reader = TiffGlobReader(files, indexer=mm_indexer)

static MicroManagerIndexer(path_to_img: Union[str, Path]) → Series[source]

An indexer function to transform Micromanager MDA tiff filenames to indices. To use:

reader = TiffGlobReader(files, indexer=TiffGlobReader.MicroManagerIndexer)

Expects images to have names of the form:: img_channel_[0-9]+_position[0-9]+_time[0-9]+_z[0-9]+.tif[f]

Parameters: path_to_img ([str, Path]) – The path to an image.
Return type: pd.Series

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

aicsimageio.readers.tiff_reader module

class aicsimageio.readers.tiff_reader.TiffReader(image: Union[str, Path], chunk_dims: Union[str, List[str]] = ['Z', 'Y', 'X', 'S'], dim_order: Optional[Union[List[str], str]] = None, channel_names: Optional[Union[List[str], List[List[str]]]] = None, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]

Bases: Reader

Wraps the tifffile API to provide the same aicsimageio Reader API but for volumetric Tiff (and other tifffile supported) images. :Parameters: * image (types.PathLike) – Path to image file to construct Reader for.

chunk_dims (Union[str, List[str]]) – Which dimensions to create chunks for. Default: DEFAULT_CHUNK_DIMS Note: Dimensions.SpatialY, Dimensions.SpatialX, and DimensionNames.Samples, will always be added to the list if not present during dask array construction.

dim_order (Optional[Union[List[str], str]]) – A string of dimensions to be applied to all array(s) or a list of string dimension names to be mapped onto the list of arrays provided to image. I.E. “TYX”. Default: None (guess dimensions for single array or multiple arrays)

channel_names (Optional[Union[List[str], List[List[str]]]]) – A list of string channel names to be applied to all array(s) or a list of lists of string channel names to be mapped onto the list of arrays provided to image. Default: None (create OME channel IDs for names for single or multiple arrays)

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

property physical_pixel_sizes: PhysicalPixelSizes: Return the physical pixel sizes of the image.

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

aicsimageio.readers package

Subpackages

Submodules

aicsimageio.readers.array_like_reader module

aicsimageio.readers.bfio_reader module

aicsimageio.readers.bioformats_reader module

aicsimageio.readers.czi_reader module

aicsimageio.readers.default_reader module

aicsimageio.readers.dv_reader module

aicsimageio.readers.lif_reader module

aicsimageio.readers.nd2_reader module

aicsimageio.readers.ome_tiff_reader module

aicsimageio.readers.ome_zarr_reader module

aicsimageio.readers.reader module

aicsimageio.readers.tiff_glob_reader module

aicsimageio.readers.tiff_reader module

Module contents