bioio.BioImage

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)

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

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

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	Returns:
current_resolution_level	Returns:
current_scene	Returns:
current_scene_index	Returns:
dask_data	Returns:
data	Returns:
dims	Returns:
dtype	Returns:
metadata	Returns:
mosaic_tile_dims	Returns:
ome_metadata	Returns:
physical_pixel_sizes	Returns:
reader	Returns:
resolution_level_dims	Returns:
resolution_levels	Returns:
scenes	Returns:
shape	Returns:
xarray_dask_data	Returns:
xarray_data	Returns: