bioio-devs/bioio-ome-zarr

A BioIO reader plugin for reading Zarr files in the OME format.

bioio-ome-zarr

A BioIO reader plugin for reading OME ZARR images using ome-zarr

---

Documentation

See the full documentation on our GitHub pages site - the generic 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

Installation

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

Example Usage (see full documentation for more examples)

Install bioio-ome-zarr alongside bioio:

pip install bioio bioio-ome-zarr

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_ome_zarr

img = BioImage("my_file.zarr", reader=bioio_ome_zarr.Reader)
img.data

Reading from AWS S3

To read from private S3 buckets, credentials must be configured. Public buckets can be accessed without credentials.

from bioio import BioImage
path = "https://allencell.s3.amazonaws.com/aics/nuc-morph-dataset/hipsc_fov_nuclei_timelapse_dataset/hipsc_fov_nuclei_timelapse_data_used_for_analysis/baseline_colonies_fov_timelapse_dataset/20200323_09_small/raw.ome.zarr"
image = BioImage(path)
print(image.get_image_dask_data())

If using an s3:// path to access a public S3 bucket, the BioImage constructor must be given a dictionary with anon: True in the fs_kwargs argument.

from bioio import BioImage
path = "s3://allencell/aics/nuc-morph-dataset/hipsc_fov_nuclei_timelapse_dataset/hipsc_fov_nuclei_timelapse_data_used_for_analysis/baseline_colonies_fov_timelapse_dataset/20200323_09_small/raw.ome.zarr"
image = BioImage(path, fs_kwargs=dict(anon=True))
print(image.get_image_dask_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.

bioio-ome-zarr's Issues

Add resolution level support

Add this feature from the base repo
bioio-devs/bioio-base#10

Add function to check resolution levels and their shapes

See conversation here. Add a function like this

    def list_zarr_levels_and_dims(file_path:str):
        reader = BioImage(file_path, reader=bioio_ome_zarr.Reader)
        levels = reader.resolution_levels
        print(f"Found ZAR file with {len(levels)} resolution levels.")
        for lvl in levels:
            reader.set_resolution_level(lvl)
            print(f"\tLevel {lvl} shape: {reader.shape}")
        return

Bug: Z size off by one

Describe the Bug

Bio-Io reports that the size in the Z dimension is one less than the true number of Z levels. Tested on a ZARR with Z folder names from 0 to 108 (inclusive), so there should be 109 levels available.

Reproduction

from bioio import BioImage
path = "https://allencell.s3.amazonaws.com/aics/nuc_morph_data/data_for_analysis/baseline_colonies/20200323_09_small/seg.ome.zarr"
img = BioImage(path)
assert img.shape[2] == 109

I checked (with a bash script) that every timepoint of that example ZARR has 109 folders for the Z dimension.

Environment

Python 3.9.18
bioio 1.0.2
bioio-base 1.0.1
bioio-ome-zarr 1.0.1

Test data not available to the public

The test data for test_reader.py is not publicly available, so users outside our organization cannot run the tests.

I also don't have authorization.

PR from a fork fails CI

I opened a PR and hoped that even though I don't have permissions to download the test data, maybe the CI job would be able to run the tests for me. Instead, the github action also had an authentication issue.

Run aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::978220035532:role/bioio_github
    role-session-name: bioio-lif-5a500dfce0a2661d3141369df3de968efc769829
    aws-region: us-west-2
    audience: sts.amazonaws.com
  env:
    BUCKET_NAME: bioio-dev-test-resources
    AWS_REGION: us-west-2
It looks like you might be trying to authenticate with OIDC. Did you mean to set the `id-token` permission? If you are not trying to authenticate with OIDC and the action is working successfully, you can ignore this message.
Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers

Create OME ZARR plug-in

Add unit test for multiple resolution levels

A previous bug with setting resolution level made this unit test a necessity. We need a test that loops over all resolution levels and at least makes sure the shapes are as expected.

Read from S3 with s3fs

Describe the Bug

Following the s3fs example in the docs I should be able to read a ZARR from S3. Instead, I get an UnsupportedFileFormatError

Reproduction

Minimal example

from bioio import BioImage
import s3fs

s3 = s3fs.S3FileSystem(anon=True)
path = "s3://allencell/aics/nuc_morph_data/data_for_analysis/baseline_colonies/20200323_09_small/raw.ome.zarr"
image = BioImage(path)

Additional example with some clues.

# %%
from bioio import BioImage
import bioio_base as biob
from ome_zarr.io import parse_url
from ome_zarr.reader import Reader as ZarrReader
import s3fs

s3 = s3fs.S3FileSystem(anon=True)

path = "s3://allencell/aics/nuc_morph_data/data_for_analysis/baseline_colonies/20200323_09_small/raw.ome.zarr"

# %% Alternate version
image = BioImage(path, fs_kwargs=dict(anon=True))  # raises UnsupportedFileFormatError

# %% Related issue
BioImage.determine_plugin(path)  # raises UnsupportedFileFormatError

# %% More clues
reader = ZarrReader(parse_url(path))  # No error, returns a ZarrReader

(abstract_fs, modified_path) = biob.io.pathlike_to_fs(
    path, enforce_exists=True, fs_kwargs={}
)
path2 = "allencell/aics/nuc_morph_data/data_for_analysis/baseline_colonies/20200323_09_small/raw.ome.zarr"
assert modified_path == path2

ZarrReader(parse_url(path2, mode="r"))  # raises AttributeError: 'NoneType' object has no attribute 'exists'

Environment

• OS Version: Ubuntu 18.04
• bioio-ome-zarr 1.0.0
• bioio 1.0.1
• bioio-base 1.0.0
• s3fs 2023.6.0