bioio.BioImage¶

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

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[

Union[: Type[biob.reader.Reader], Sequence[Type[biob.reader.Reader]],

]

]

Controls how BioImage selects the underlying Reader:

If a single Reader subclass is provided

(e.g. reader=TiffReader), that reader is used directly. Plugin discovery, extension matching, and default ordering are bypassed entirely.

If a sequence of Reader subclasses is provided

(e.g. reader=[TiffReader, OmeTiffReader]), the sequence is treated as an explicit try-order. BioImage attempts to construct each reader in order and uses the first one that successfully constructs.

If None (default), BioImage uses its default plugin discovery

and ordering logic based on the input image. For a detailed description of this behavior, see bioio.plugins.get_plugins.

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)

Initialize an image and override plugin selection order when multiple readers support the same extension.

>>> from bioio_tifffile import Reader as TiffReader
>>> from bioio_ome_tiff import Reader as OmeTiffReader
>>> img = BioImage(
...     "multi_plugin_file.ome.tiff",
...     reader=[TiffReader, OmeTiffReader],
... )
... # TiffReader will be tried before OmeTiffReader for this instance.

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

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

Methods

`__init__`(image[, reader, ...])
`determine_plugin`(image[, fs_kwargs, ...])	Determine the appropriate plugin to read a given image.
`get_dask_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_image_dask_data`([dimension_order_out])	Get specific dimension image data out of an image as a dask array.
`get_image_data`([dimension_order_out])	Read the image as a numpy array then return specific dimension image data.
`get_mosaic_tile_position`(mosaic_tile_index, ...)	Get the absolute position of the top left point for a single mosaic tile.
`get_mosaic_tile_positions`(**kwargs)	Get the absolute positions of the top left points for each mosaic tile matching the specified dimensions and current scene.
`get_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_xarray_dask_stack`(**kwargs)	Get all scenes stacked in to a single array.
`get_xarray_stack`(**kwargs)	Get all scenes stacked in to a single array.
`save`(uri[, select_scenes])	Saves the file data to OME-TIFF format with general naive best practices.
`set_resolution_level`(resolution_level)	Set the operating resolution level.
`set_scene`(scene_id)	Set the operating scene.

Attributes

`channel_names`
`current_resolution_level`
`current_scene`
`current_scene_index`
`dask_data`
`data`
`dimension_properties`
`dims`
`dtype`
`metadata`
`mosaic_tile_dims`
`ome_metadata`
`physical_pixel_sizes`
`reader`
`resolution_level_dims`
`resolution_levels`
`scale`
`scenes`
`shape`
`standard_metadata`	Return a set of standardized metadata.
`time_interval`
`xarray_dask_data`
`xarray_data`