bioio-czi

A BioIO reader plugin for reading CZIs using aicspylibczi (default) or pylibczirw (deprecated).

Documentation

See the bioio documentation on our GitHub pages site - the general use and installation instructions there will work for this package.

Information about the base reader this package relies on can be found in the bioio-base repository here.

This plugin attempts to follow the latest specification for the CZI file format from Carl Zeiss Microscopy (currently v1.2).

Installation

Install bioio-czi alongside bioio:

pip install bioio bioio-czi

Stable Release: pip install bioio-czi
Development Head: pip install git+https://github.com/bioio-devs/bioio-czi.git

pylibczirw vs. aicspylibczi

bioio-czi can operate in aicspylibczi mode (the default) or pylibczirw mode.

Deprecated: pylibczirw mode (use_aicspylibczi=False) is deprecated and will be removed in the next major release, along with the use_aicspylibczi parameter. aicspylibczi mode now covers everything pylibczirw mode did, including remote reads. Using use_aicspylibczi=False emits a DeprecationWarning.

The primary difference is that pylibczirw cannot access individual tiles or subblock metadata from a tiled CZI. To use pylibczirw, add the use_aicspylibczi=False parameter when creating a reader. For example: from bioio import BioImage; img = BioImage(..., use_aicspylibczi=False).

*Elapsed time metadata include the following. These are derived from individual subblock metadata.

• BioImage(...).time_interval
• BioImage(...).standard_metadata.timelapse_interval
• BioImage(...).standard_metadata.total_time_duration

**The underlying pylibczirw reader only exposes per-scene X and Y dimensions. Files that do not have consistent dimensions per scene may be read incorrectly in pylibczirw mode.

Example Usage (see full documentation for more examples)

Basic usage

from bioio import BioImage

path = (
    "https://allencell.s3.amazonaws.com/aics/hipsc_12x_overview_image_dataset/"
    "stitchedwelloverviewimagepath/05080558_3500003720_10X_20191220_D3.czi"
)

img = BioImage(path)
print(img.shape)  # (1, 1, 1, 5684, 5925)

Both modes read http/https URLs through libCZI's curl stream, which fetches only the byte ranges a read needs; the server must support range requests. In aicspylibczi mode the stitched mosaic is chunked one tile per chunk, so a window into mosaic_dask_data reads only the tiles beneath it.

In aicspylibczi mode, stream_options configures the curl stream, for example BioImage(url, stream_options={"timeout": 60, "xoauth2_bearer": token}) for an authenticated endpoint. See the aicspylibczi README for the full list.

Individual tiles

img = BioImage(
    "S=2_4x2_T=2=Z=3_CH=2.czi",
    reconstruct_mosaic=False,
    include_subblock_metadata=True,
)
print(img.dims)  # <Dimensions [M: 8, T: 2, C: 2, Z: 3, Y: 256, X: 256]>
subblocks = img.metadata.findall("./Subblocks/Subblock")
print(len(subblocks))  # 192
print(img.get_image_data("TCZYX", M=3).shape)  # (2, 2, 3, 256, 256)

The M dimension is used to select a specific tile.

To read the metadata of just the subblocks you need, rather than all of them up front, use get_subblock_metadata with the same dimension arguments:

subblocks = img.reader.get_subblock_metadata(T=0, M=3)
print(len(subblocks.findall("Subblock")))  # 6

Stitched mosaic

img = BioImage("S=2_4x2_T=2=Z=3_CH=2.czi")
print(img.dims)  # <Dimensions [T: 2, C: 2, Z: 3, Y: 487, X: 947]>

All 8 tiles are stitched together. Where tiles overlap, the pixel value is the pixel value from the tile with the highest M-index.

Explicit Reader

This example shows a simple use case for just accessing the pixel data of the image by explicitly passing this Reader into the BioImage. Passing the Reader into the BioImage instance is optional as bioio will automatically detect installed plug-ins and auto-select the most recently installed plug-in that supports the file passed in.

from bioio import BioImage
import bioio_czi

img = BioImage("my_file.czi", reader=bioio_czi.Reader)
img.data

Issues

Click here to view all open issues in bioio-devs organization at once or check this repository's issue tab.

Development

See CONTRIBUTING.md for information related to developing the code.