bioio package¶

Subpackages¶

bioio.writers package

Submodules¶

bioio.array_like_reader module¶

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: PhysicalPixelSizes: Using available metadata, the floats representing physical pixel sizes for dimensions Z, Y, and X.

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: Tuple[str, …]: A tuple of valid scene ids in the file.

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 bioio.array_like_reader.ArrayLikeReaderMetadata[source]¶

Bases: ReaderMetadata

static get_reader() → Reader[source]¶

static get_supported_extensions() → List[str][source]¶

bioio.bio_image module¶

class bioio.bio_image.BioImage(image: str | Path | ndarray | Array | DataArray | List[ndarray | Array | DataArray] | List[str | Path], reader: Type[Reader] | None = None, reconstruct_mosaic: bool = True, use_plugin_cache: bool = False, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]¶

Bases: ImageContainer

BioImage 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: biob.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.
use_plugin_cache: bool default False: Boolean for setting whether to use a plugin of the installed caches rather than checking for installed plugins on each BioImage instance init. If True, will use the cache of installed plugins discovered last BioImage init.
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.

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.

Examples

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

>>> img = BioImage("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 = BioImage("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 = BioImage(data)

Initialize an image from S3 with s3fs.

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

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

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

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

>>> img = BioImage("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 = BioImage("malformed_metadata.ome.tiff", reader=readers.TiffReader)

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

>>> img = BioImage("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 = BioImage("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 = BioImage("unsupported_mosaic.ext")
... img.dims  # <Dimensions [M: 100, T: 1, C: 2, Z: 1, Y: 400, X: 400]>

property channel_names: List[str]¶

Returns:

channel_names: List[str]: Using available metadata, the list of strings representing channel names.

property current_resolution_level: int¶

Returns:

current_resolution_level: int: The currently selected resolution level.

property current_scene: str¶

Returns:

scene: str: The current operating scene.

property current_scene_index: int¶

Returns:

scene_index: int: The current operating scene index in the file.

property dask_data: Array¶

Returns:

dask_data: da.Array: The image as a dask array with standard dimension ordering.

Notes

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

property data: ndarray¶

Returns:

data: np.ndarray: The image as a numpy array with standard dimension ordering.

Notes

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

static determine_plugin(image: str | Path | ndarray | Array | DataArray | List[ndarray | Array | DataArray] | List[str | Path], fs_kwargs: Dict[str, Any] = {}, use_plugin_cache: bool = False, **kwargs: Any) → PluginEntry[source]¶

Determine the appropriate plugin to read a given image.

This function identifies the most suitable plugin to read the provided image based on its type or file extension. It leverages the installed plugins for bioio, each of which supports a subset of image formats. If a suitable plugin is found, it is returned; otherwise, an error is raised.

Parameters:

imagebiob.types.ImageLike: The image to be read. This can be a file path (str or Path) or an array-like object (e.g., numpy array).
fs_kwargsDict[str, Any], optional: Additional keyword arguments to be passed to the file system handler.
use_plugin_cachebool, optional: Whether to use a cached version of the plugin mapping, by default False.
**kwargsAny: Additional keyword arguments for plugin-specific configurations.

Returns:

PluginEntry: A PluginEntry NamedTuple which is a wrapper of release information and reader references for an individual plugin.

Raises:

exceptions.UnsupportedFileFormatError: Raised if no suitable reader plugin can be found for the provided image.

Notes

This function performs the following steps: 1. Fetches an updated mapping of available plugins,

optionally using a cached version.

If the image is a file path (str or Path), it checks for a matching plugin based on the file extension.
If the image is an array-like object, it attempts to use the built-in ArrayLikeReader.
If no suitable plugin is found, raises an UnsupportedFileFormatError.

Examples

To determine the appropriate plugin for a given image file:

>>> image_path = "example_image.tif"
>>> plugin = determine_plugin(image_path)
>>> print(plugin)

To determine the appropriate plugin for an array-like image:

>>> import numpy as np
>>> image_array = np.random.random((5, 5, 5))
>>> plugin = determine_plugin(image_array)
>>> print(plugin)

property dims: Dimensions¶

Returns:

dims: dimensions.Dimensions: Object with the paired dimension names and their sizes.

property dtype: dtype¶

Returns:

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

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

bioio_base.transforms.generate_stack: Underlying function for generating various scene stacks.

get_image_dask_data(dimension_order_out: str | None = 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: da.Array: The image data with the specified dimension ordering.

Notes

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

See bioio_base.transforms.reshape_data for more details.

Examples

Specific index selection

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

List of index selection

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

Slice selection

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

get_image_data(dimension_order_out: str | None = 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: np.ndarray: The image data with the specified dimension ordering.

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 bioio_base.transforms.reshape_data for more details.

Examples

Specific index selection

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

List of index selection

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

Slice selection

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

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[Tuple[int, int]]: List of the Y and X coordinate for the tile positions.

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

bioio_base.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

bioio_base.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

bioio_base.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: Any: 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.

property mosaic_tile_dims: Dimensions | None¶

Returns:

tile_dims: Optional[Dimensions]: The dimensions for each tile in the mosaic image. If the image is not a mosaic image, returns None.

property ome_metadata: OME¶

Returns:

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

Raises:

NotImplementedError: No metadata transformer available.

property physical_pixel_sizes: PhysicalPixelSizes¶

Returns:

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

Notes

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

property reader: Reader¶

Returns:

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

property resolution_level_dims: Dict[int, Tuple[int, ...]]¶

Returns:

resolution_level_dims: Dict[int, Tuple[int, …]]: resolution level dictionary of shapes.

property resolution_levels: Tuple[int, ...]¶

Returns:

resolution_levels: Tuple[int, …]: A tuple of valid resolution levels in the file.

save(uri: str | Path, select_scenes: List[str] | Tuple[str, ...] | None = None) → None[source]¶

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

Parameters:

uri: biob.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 bioio.writers.OmeTiffWriter for more in-depth specification and the bioio.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: Tuple[str, …]: A tuple of valid scene ids in the file.

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_resolution_level(resolution_level: int) → None[source]¶

Set the operating resolution level.

Parameters:

resolution_level: int: The selected resolution level to set as current.

Raises:

IndexError: The provided level is not found in the available list of resolution levels.

set_scene(scene_id: 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[int, …]: Tuple of the image array’s dimensions.

property xarray_dask_data: DataArray¶

Returns:

xarray_dask_data: xr.DataArray: The delayed image and metadata as an annotated data array.

Notes

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

property xarray_data: DataArray¶

Returns:

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

Notes

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

Read image as a numpy array.

Parameters:

image: biob.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 BioImage and Reader subclass.

Returns:

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

Read image as a delayed dask array.

Parameters:

image: biob.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 BioImage and Reader subclass.

Returns:

data: da.core.Array: The image read, scene selected, and returned as an BioIO standard shaped delayed dask array.

Read image as an in-memory xarray DataArray.

Parameters:

image: biob.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 BioImage and Reader subclass.

Returns:

data: xr.DataArray: The image read, scene selected, and returned as an BioIO standard shaped in-memory DataArray.

Read image as a delayed xarray DataArray.

Parameters:

image: biob.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 BioImage and Reader subclass.

Returns:

data: xr.DataArray: The image read, scene selected, and returned as an BioIO standard shaped delayed xarray DataArray.

bioio.ome_utils module¶

bioio.ome_utils.dtype_to_ome_type(npdtype: dtype) → PixelType[source]¶

Convert numpy dtype to OME PixelType

Parameters:

npdtype: numpy.dtype: A numpy datatype.

Returns:

ome_type: PixelType: One of the supported OME Pixels types

Raises:

ValueError: No matching pixel type for provided numpy type.

bioio.ome_utils.generate_ome_channel_id(image_id: str, channel_id: str | int) → str[source]¶

Naively generates the standard OME channel ID using a provided ID.

Parameters:

image_id: str: An image id to pull the image specific index from. See: generate_ome_image_id for more details.
channel_id: Union[str, int]: A string or int representing the ID for a channel. In the context of the usage of this function, this is usually used with the index of the channel.

Returns:

ome_channel_id: str: The OME standard for channel IDs.

Notes

ImageIds are usually: “Image:0”, “Image:1”, or “Image:N”, ChannelIds are usually the combination of image index + channel index – “Channel:0:0” for the first channel of the first image for example.

bioio.ome_utils.generate_ome_image_id(image_id: str | int) → str[source]¶

Naively generates the standard OME image ID using a provided ID.

Parameters:

image_id: Union[str, int]: A string or int representing the ID for an image. In the context of the usage of this function, this is usually used with the index of the scene / image.

Returns:

ome_image_id: str: The OME standard for image IDs.

bioio.ome_utils.ome_to_numpy_dtype(ome_type: PixelType) → dtype[source]¶

Convert OME PixelType to numpy dtype

Parameters:

ome_type: PixelType: One of the supported OME Pixels types

Returns:

npdtype: numpy.dtype: A numpy datatype.

Raises:

ValueError: No matching numpy type for the provided pixel type.

bioio.plugins module¶

class bioio.plugins.PluginEntry(entrypoint, metadata, timestamp)[source]¶

Bases: NamedTuple

Create new instance of PluginEntry(entrypoint, metadata, timestamp)

entrypoint: EntryPoint¶: Alias for field number 0

metadata: ReaderMetadata¶: Alias for field number 1

timestamp: float¶: Alias for field number 2

class bioio.plugins.PluginSupport(supported: bool, error: str | None)[source]¶

Bases: object

Dataclass for reporting a plugins support for a specific image.

error: str | None¶

supported: bool¶

Check if the provided image is compatible with the specified reader class.

Parameters:

imageImageLike: The image to be checked. It can be a PathLike, ArrayLike, MetaArrayLike, a list of MetaArrayLike, or a list of PathLike.
reader_classReader: The reader class to be checked against.
Returns
——-
bool: Returns True if the image is compatible with the reader class, False otherwise.

bioio.plugins.dump_plugins() → None[source]¶: Report information about plugins currently installed

bioio.plugins.get_array_like_plugin() → PluginEntry[source]¶: Create and return a PluginEntry for ArrayLikeReader.

bioio.plugins.get_dependency_version_range_for_distribution(distribution_name: str, dependency_name: str) → Tuple[str | None, str | None][source]¶: Retrieves the minimum and maximum versions of the dependency as specified by the given distribution. None as the minimum or maximum represents no minimum or maximum (respectively)

bioio.plugins.get_plugins(use_cache: bool) → Dict[str, List[PluginEntry]][source]¶: Gather a mapping from support file extensions to plugins installed that support said extension

bioio.plugins.insert_sorted_by_timestamp(list: List[PluginEntry], item: PluginEntry) → None[source]¶: Insert into list of PluginEntrys sorted by their timestamps (install dates)

bioio.plugins.plugin_feasibility_report(image: str | Path | ndarray | Array | DataArray | List[ndarray | Array | DataArray] | List[str | Path], fs_kwargs: Dict[str, Any] = {}, use_plugin_cache: bool = False, **kwargs: Any) → Dict[str, PluginSupport][source]¶: Generate a feasibility report for each plugin, determining if it can handle the specified image.

Module contents¶

Top-level package for bioio.

class bioio.BioImage(image: str | Path | ndarray | Array | DataArray | List[ndarray | Array | DataArray] | List[str | Path], reader: Type[Reader] | None = None, reconstruct_mosaic: bool = True, use_plugin_cache: bool = False, fs_kwargs: Dict[str, Any] = {}, **kwargs: Any)[source]¶

Bases: ImageContainer

Parameters:

image: biob.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.
use_plugin_cache: bool default False: Boolean for setting whether to use a plugin of the installed caches rather than checking for installed plugins on each BioImage instance init. If True, will use the cache of installed plugins discovered last BioImage init.
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.

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.

Examples

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

>>> img = BioImage("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 = BioImage("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 = BioImage(data)

Initialize an image from S3 with s3fs.

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

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

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

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

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

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

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

>>> img = BioImage("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 = BioImage("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 = BioImage("unsupported_mosaic.ext")
... img.dims  # <Dimensions [M: 100, T: 1, C: 2, Z: 1, Y: 400, X: 400]>

property channel_names: List[str]¶

Returns:

channel_names: List[str]: Using available metadata, the list of strings representing channel names.

property current_resolution_level: int¶

Returns:

current_resolution_level: int: The currently selected resolution level.

property current_scene: str¶

Returns:

scene: str: The current operating scene.

property current_scene_index: int¶

Returns:

scene_index: int: The current operating scene index in the file.

property dask_data: Array¶

Returns:

dask_data: da.Array: The image as a dask array with standard dimension ordering.

Notes

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

property data: ndarray¶

Returns:

data: np.ndarray: The image as a numpy array with standard dimension ordering.

Notes

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

Determine the appropriate plugin to read a given image.

Parameters:

imagebiob.types.ImageLike: The image to be read. This can be a file path (str or Path) or an array-like object (e.g., numpy array).
fs_kwargsDict[str, Any], optional: Additional keyword arguments to be passed to the file system handler.
use_plugin_cachebool, optional: Whether to use a cached version of the plugin mapping, by default False.
**kwargsAny: Additional keyword arguments for plugin-specific configurations.

Returns:

PluginEntry: A PluginEntry NamedTuple which is a wrapper of release information and reader references for an individual plugin.

Raises:

exceptions.UnsupportedFileFormatError: Raised if no suitable reader plugin can be found for the provided image.

Notes

This function performs the following steps: 1. Fetches an updated mapping of available plugins,

optionally using a cached version.

If the image is a file path (str or Path), it checks for a matching plugin based on the file extension.
If the image is an array-like object, it attempts to use the built-in ArrayLikeReader.
If no suitable plugin is found, raises an UnsupportedFileFormatError.

Examples

To determine the appropriate plugin for a given image file:

>>> image_path = "example_image.tif"
>>> plugin = determine_plugin(image_path)
>>> print(plugin)

To determine the appropriate plugin for an array-like image:

>>> import numpy as np
>>> image_array = np.random.random((5, 5, 5))
>>> plugin = determine_plugin(image_array)
>>> print(plugin)

property dims: Dimensions¶

Returns:

dims: dimensions.Dimensions: Object with the paired dimension names and their sizes.

property dtype: dtype¶

Returns:

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

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

bioio_base.transforms.generate_stack: Underlying function for generating various scene stacks.

get_image_dask_data(dimension_order_out: str | None = 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: da.Array: The image data with the specified dimension ordering.

Notes

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

See bioio_base.transforms.reshape_data for more details.

Examples

Specific index selection

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

List of index selection

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

Slice selection

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

get_image_data(dimension_order_out: str | None = 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: np.ndarray: The image data with the specified dimension ordering.

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 bioio_base.transforms.reshape_data for more details.

Examples

Specific index selection

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

List of index selection

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

Slice selection

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

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[Tuple[int, int]]: List of the Y and X coordinate for the tile positions.

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

bioio_base.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

bioio_base.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

bioio_base.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: Any: 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.

property mosaic_tile_dims: Dimensions | None¶

Returns:

tile_dims: Optional[Dimensions]: The dimensions for each tile in the mosaic image. If the image is not a mosaic image, returns None.

property ome_metadata: OME¶

Returns:

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

Raises:

NotImplementedError: No metadata transformer available.

property physical_pixel_sizes: PhysicalPixelSizes¶

Returns:

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

Notes

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

property reader: Reader¶

Returns:

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

property resolution_level_dims: Dict[int, Tuple[int, ...]]¶

Returns:

resolution_level_dims: Dict[int, Tuple[int, …]]: resolution level dictionary of shapes.

property resolution_levels: Tuple[int, ...]¶

Returns:

resolution_levels: Tuple[int, …]: A tuple of valid resolution levels in the file.

save(uri: str | Path, select_scenes: List[str] | Tuple[str, ...] | None = None) → None[source]¶

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

Parameters:

uri: biob.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 bioio.writers.OmeTiffWriter for more in-depth specification and the bioio.writers module as a whole for list of all available file writers.

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

Returns:

scenes: Tuple[str, …]: A tuple of valid scene ids in the file.

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_resolution_level(resolution_level: int) → None[source]¶

Set the operating resolution level.

Parameters:

resolution_level: int: The selected resolution level to set as current.

Raises:

IndexError: The provided level is not found in the available list of resolution levels.

set_scene(scene_id: 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[int, …]: Tuple of the image array’s dimensions.

property xarray_dask_data: DataArray¶

Returns:

xarray_dask_data: xr.DataArray: The delayed image and metadata as an annotated data array.

Notes

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

property xarray_data: DataArray¶

Returns:

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

Notes

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

bioio.plugin_feasibility_report(image: str | Path | ndarray | Array | DataArray | List[ndarray | Array | DataArray] | List[str | Path], fs_kwargs: Dict[str, Any] = {}, use_plugin_cache: bool = False, **kwargs: Any) → Dict[str, PluginSupport][source]¶: Generate a feasibility report for each plugin, determining if it can handle the specified image.