bioio-czi

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

---

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 pylibczirw mode (the default) or aicspylibczi mode.

Feature	pylibczirw mode	aicspylibczi mode
Read CZIs from the internet	✅	❌
Read single tile from tiled CZI	❌	✅
Read single tile's metadata from tiled CZI	❌	✅
Read elapsed time metadata*	❌	✅
Handle CZIs with different dimensions per scene**	❌	✅
Read stitched mosaic of a tiled CZI	✅	✅

The primary difference is that pylibczirw supports reading CZIs over the internet but cannot access individual tiles from a tiled CZI. To use aicspylibczi, add the use_aicspylibczi=True parameter when creating a reader. For example: from bioio import BioImage; img = BioImage(..., use_aicspylibczi=True).

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

Note: accessing files from the internet is not available in aicspylibczi mode.

Individual tiles with aicspylibczi

img = BioImage(
    "S=2_4x2_T=2=Z=3_CH=2.czi",
    reconstruct_mosaic=False,
    include_subblock_metadata=True,
    use_aicspylibczi=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.

Stitched mosaic with pylibczirw

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.