Metadata-Version: 2.4
Name: iohub
Version: 0.3.3
Summary: N-dimensional bioimaging data I/O with OME metadata in Python
Project-URL: Homepage, https://github.com/czbiohub-sf/iohub
Project-URL: Issue, https://github.com/czbiohub-sf/iohub/issues
Project-URL: Documentation, https://czbiohub-sf.github.io/iohub
Project-URL: Source, https://github.com/czbiohub-sf/iohub
Author-email: Biohub and iohub contributors <iohub@czbiohub.org>
License: BSD 3-Clause License
        
        Copyright (c) 2022, Chan Zuckerberg Biohub
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.12
Requires-Dist: blosc2
Requires-Dist: dask[array]
Requires-Dist: natsort>=8.4.0
Requires-Dist: ndtiff>=2.2.1
Requires-Dist: pandas>=2
Requires-Dist: pillow>=9.4.0
Requires-Dist: pydantic-extra-types>=2.9.0
Requires-Dist: pydantic>=2.8.2
Requires-Dist: rich
Requires-Dist: tifffile>=2025.5.21
Requires-Dist: tqdm
Requires-Dist: xarray>=2024.1.1
Requires-Dist: zarr>=3.1.6
Requires-Dist: zarrs>=0.2.3
Provides-Extra: tensorstore
Requires-Dist: tensorstore>=0.1.64; extra == 'tensorstore'
Description-Content-Type: text/markdown

# iohub

|              |                                                                                                                                                                             |
| :----------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|  **Status**  | [![Docs][badge-docs]][link-docs] [![Tests][badge-tests]][link-tests]                                                                                                        |
| **Package**  | [![PyPI][badge-pypi]][link-pypi] [![Python][badge-python]][link-pypi]                                                                                                       |
|   **Meta**   | [![SPEC 0][badge-spec0]][link-spec0] [![Hatch][badge-hatch]][link-hatch] [![uv][badge-uv]][link-uv] [![Ruff][badge-ruff]][link-ruff] [![prek][badge-prek]][link-prek] [![License][badge-license]][link-license]  |
|   **Cite**   | [![DOI][badge-doi]][link-doi]                                                                                                                                               |

[badge-docs]: https://github.com/czbiohub-sf/iohub/actions/workflows/docs.yml/badge.svg
[badge-tests]: https://github.com/czbiohub-sf/iohub/actions/workflows/test.yml/badge.svg
[badge-pypi]: https://img.shields.io/pypi/v/iohub.svg
[badge-python]: https://img.shields.io/pypi/pyversions/iohub
[badge-hatch]: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg
[badge-uv]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json
[badge-spec0]: https://img.shields.io/badge/SPEC-0-green?labelColor=%23004811&color=%235CA038
[link-spec0]: https://scientific-python.org/specs/spec-0000/
[badge-ruff]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
[badge-prek]: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json
[badge-license]: https://img.shields.io/badge/License-BSD--3--Clause-blue.svg
[badge-doi]: https://zenodo.org/badge/DOI/10.5281/zenodo.15022067.svg

[link-docs]: https://czbiohub-sf.github.io/iohub
[link-tests]: https://github.com/czbiohub-sf/iohub/actions/workflows/test.yml
[link-pypi]: https://pypi.org/project/iohub
[link-hatch]: https://github.com/pypa/hatch
[link-uv]: https://github.com/astral-sh/uv
[link-ruff]: https://github.com/astral-sh/ruff
[link-prek]: https://github.com/j178/prek
[link-license]: https://opensource.org/licenses/BSD-3-Clause
[link-doi]: https://doi.org/10.5281/zenodo.15022067

N-dimensional bioimaging produces data and metadata in various formats,
and iohub aims to become a unified Python interface to the most common formats
used at the Biohub and in the broader imaging community.

## Supported formats

### Read

- OME-Zarr ([OME-NGFF v0.5](https://ngff.openmicroscopy.org/0.5/), OME-NGFF v0.4)
- Micro-Manager TIFF sequence, OME-TIFF (MMStack), and NDTiff datasets
- Custom data formats generated by Biohub microscopes
  - Supported: Falcon (PTI), Dorado (ClearControl), Dragonfly (OpenCell OME-TIFF), Mantis (NDTiff)
  - WIP: DaXi

### Write

- OME-Zarr ([OME-NGFF v0.5](https://ngff.openmicroscopy.org/0.5/))

## Quick start

### Installation

Install iohub from PyPI:

```sh
pip install iohub
```

With optional TensorStore support:

```sh
pip install "iohub[tensorstore]"
```

Or install the latest development version:

```sh
pip install git+https://github.com/czbiohub-sf/iohub.git
```

> For development setup, see the [contributing guide](CONTRIBUTING.md#setting-up-development-environment).

### Command-line interface

To check if iohub works for a dataset:

```sh
iohub info /path/to/data/
```

The CLI can show a summary of the dataset,
point to relevant Python calls,
and convert other data formats to the latest OME-Zarr.
See the full CLI help message by typing `iohub` or `iohub [command] --help` in the terminal.

### Working with OME-Zarr

Load and modify an [example OME-Zarr](https://zenodo.org/record/7274533#.Y-q9uOzMJqv) dataset:

```py
import numpy as np
from iohub import open_ome_zarr

with open_ome_zarr(
    "20200812-CardiomyocyteDifferentiation14-Cycle1.zarr",
    mode="r",
    layout="auto",
) as dataset:
    dataset.print_tree()  # prints the hierarchy of the zarr store
    channel_names = dataset.channel_names
    print(channel_names)
    img_array = dataset[
        "B/03/0/0"
    ]  # lazy Zarr array for the raw image in the first position
    raw_data = img_array.numpy()  # loads a CZYX 4D array into RAM
    print(raw_data.mean())  # does some analysis

with open_ome_zarr(
    "max_intensity_projection.zarr",
    mode="w-",
    layout="hcs",
    channel_names=channel_names,
) as dataset:
    new_fov = dataset.create_position(
        "B", "03", "0"
    )  # creates fov with the same path
    new_fov["0"] = raw_data.max(axis=1).reshape(
        (1, 1, 1, *raw_data.shape[2:])
    )  # max projection along Z axis and prepend dims to 5D
    dataset.print_tree()  # checks that new data has been written
```

For more about API usage, refer to the [documentation](https://czbiohub-sf.github.io/iohub/)
and the [example scripts](https://github.com/czbiohub-sf/iohub/tree/main/docs/examples).

### Reading Micro-Manager TIFF data

Read a directory containing a TIFF dataset:

```py
from iohub import read_images

reader = read_images("/path/to/data/")
print(reader)
```

## Why iohub?

This project is inspired by the existing Python libraries for bioimaging data I/O,
including [ome-zarr-py](https://github.com/ome/ome-zarr-py), [tifffile](https://github.com/cgohlke/tifffile) and [aicsimageio](https://github.com/AllenCellModeling/aicsimageio).
They support some of the most widely adopted and/or promising formats in microscopy,
such as OME-Zarr and OME-TIFF.

iohub bridges the gaps among them with the following features:

- Efficient reading of data in various TIFF-based formats produced by the Micro-Manager/Pycro-Manager acquisition stack.
- Efficient and customizable conversion of data and metadata from TIFF to OME-Zarr.
- Pythonic and atomic access of OME-Zarr data with parallelized analysis in mind.
- OME-Zarr metadata is automatically constructed and updated for writing,
and verified against the specification when reading.
- Adherence to the latest OME-NGFF specification (v0.5) whenever possible.
