Skip to content

Quickstart

Ngio is a Python package that provides a simple and intuitive API for reading and writing data to and from OME-Zarr. This guide will walk you through the basics of using ngio to read and write data.

Installation

ngio can be installed from PyPI, conda-forge, or from source.

  • ngio requires Python >=3.11

The recommended way to install ngio is from PyPI using pip:

pip install ngio

Alternatively, you can install ngio using mamba:

mamba install -c conda-forge ngio

or conda:

conda install -c conda-forge ngio

  1. Clone the repository: 

    git clone https://github.com/fractal-analytics-platform/ngio.git
cd ngio

  2. Install the package: 

    pip install .

Troubleshooting

Please report installation problems by opening an issue on our GitHub repository.

Setup some test data

Let's start by downloading a sample OME-Zarr dataset to work with.

from pathlib import Path
from ngio.utils import download_ome_zarr_dataset

# Download a sample dataset
download_dir = Path("./data")
hcs_path = download_ome_zarr_dataset("CardiomyocyteSmallMip", download_dir=download_dir)
image_path = hcs_path / "B" / "03" / "0"

Open an OME-Zarr image

Let's start by opening an OME-Zarr file and inspecting its contents.

>>> from ngio import open_ome_zarr_container
>>> ome_zarr_container = open_ome_zarr_container(image_path)
>>> ome_zarr_container
OmeZarrContainer(levels=5, #labels=4, #tables=7)

What is the OME-Zarr container?

The OME-Zarr Container is the core of ngio and the entry point to working with OME-Zarr images. It provides high-level access to the image metadata, images, labels, and tables.

What is the OME-Zarr container not?

The OME-Zarr Container object does not allow the user to interact with the image data directly. For that, we need to use the Image, Label, and Table objects.

Next steps

To learn how to work with the OME-Zarr Container object, but also with the image, label, and table data, check out the following guides:

  • OME-Zarr Container: An overview on how to use the OME-Zarr Container object and how to create new images and labels.
  • Images/Labels: To know more on how to work with image data.
  • Tables: To know more on how to work with table data, and how you can combine tables with image data.
  • Masked Images/Labels: To know more on how to work with masked image data.
  • HCS Plates: To know more on how to work with HCS plate data.

Also, checkout our jupyer notebook tutorials for more examples: