# ngio

> ngio (next generation file format IO) is a Python library for bioimage analysis on
> OME-Zarr data. It provides an object-based API for opening and manipulating OME-Zarr
> images, labels, tables, regions of interest (ROIs) and high-content screening (HCS)
> plates. It supports OME-Zarr v0.4 and v0.5 over Zarr v2 and v3 storage, and is developed
> at the BioVisionCenter, University of Zurich, under the BSD-3-Clause licence.

Install with `pip install ngio` or `mamba install -c conda-forge ngio`. The central object
is the OME-Zarr container, obtained with `open_ome_zarr_container(store)`; from it you
reach images and labels (`get_image`, `get_label`), tables (`get_table`), masked images
(`get_masked_image`) and, for plates, `open_ome_zarr_plate`. The worked examples in the
guides and tutorials are executed when the site is built, so the outputs shown are real.

## Getting started

- [Quickstart](https://biovisioncenter.github.io/ngio/stable/getting_started/0_quickstart/): Installation and opening your first OME-Zarr container.
- [OME-Zarr containers](https://biovisioncenter.github.io/ngio/stable/getting_started/1_ome_zarr_containers/): The container object, metadata inspection and modification, deriving and creating images, and remote stores.
- [Images and labels](https://biovisioncenter.github.io/ngio/stable/getting_started/2_images/): Selecting resolution levels by path or pixel size, reading as numpy or dask, slicing, writing with set_array and consolidate, and working with labels.
- [Tables](https://biovisioncenter.github.io/ngio/stable/getting_started/3_tables/): Listing and loading ROI, masking ROI and feature tables, and creating new tables in memory or on disk.
- [Masked images and labels](https://biovisioncenter.github.io/ngio/stable/getting_started/4_masked_images/): Label-indexed access to image regions, zoom_factor, and masked read/write operations.
- [HCS plates](https://biovisioncenter.github.io/ngio/stable/getting_started/5_hcs/): Plate structure, rows, columns and acquisitions, retrieving images, and creating plates.
- [Iterators](https://biovisioncenter.github.io/ngio/stable/getting_started/6_iterators/): The four iterators for building scalable processing pipelines.
- [Configuration](https://biovisioncenter.github.io/ngio/stable/getting_started/7_configuration/): The ngio config file and the io_retry policy.

## Tutorials

- [Create an OME-Zarr image](https://biovisioncenter.github.io/ngio/stable/tutorials/create_ome_zarr/): Convert a numpy array to OME-Zarr and add a ROI table.
- [Image processing](https://biovisioncenter.github.io/ngio/stable/tutorials/image_processing/): Gaussian blur applied eagerly, lazily with dask, and via an iterator.
- [Image segmentation](https://biovisioncenter.github.io/ngio/stable/tutorials/image_segmentation/): Otsu segmentation per field of view, and masked segmentation.
- [Feature extraction](https://biovisioncenter.github.io/ngio/stable/tutorials/feature_extraction/): regionprops features written back as a feature table.
- [HCS exploration](https://biovisioncenter.github.io/ngio/stable/tutorials/hcs_exploration/): Aggregating tables across a plate and creating an empty plate.

## Table specifications

- [Overview](https://biovisioncenter.github.io/ngio/stable/table_specs/overview/): The table architecture — backends, in-memory objects and type specs — and the on-disk group layout.
- [Table backends](https://biovisioncenter.github.io/ngio/stable/table_specs/backend/): The anndata, parquet, csv and json backends and their metadata.
- [ROI table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/roi_table/): Required and optional columns for ROI tables.
- [Masking ROI table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/masking_roi_table/): ROI tables indexed by label id.
- [Feature table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/feature_table/): Measurement tables indexed by label id.
- [Condition table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/condition_table/): Experimental condition metadata.
- [Generic table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/generic_table/): Untyped fallback tables.
- [Add a custom table](https://biovisioncenter.github.io/ngio/stable/table_specs/table_types/custom_table/): Why generic tables are the extension point today.

## API reference

- [OmeZarrContainer](https://biovisioncenter.github.io/ngio/stable/api/ome_zarr_container/): open_ome_zarr_container, create_empty_ome_zarr, create_ome_zarr_from_array.
- [Images](https://biovisioncenter.github.io/ngio/stable/api/images/): Image and Label objects and their accessors.
- [HCS](https://biovisioncenter.github.io/ngio/stable/api/hcs/): open_ome_zarr_plate, OmeZarrPlate, open_ome_zarr_well, OmeZarrWell, create_empty_plate, create_empty_well.
- [Tables](https://biovisioncenter.github.io/ngio/stable/api/tables/): Table classes, the tables container and backends.
- [Iterators](https://biovisioncenter.github.io/ngio/stable/api/iterators/): ImageProcessingIterator, SegmentationIterator, MaskedSegmentationIterator, FeatureExtractorIterator — from ngio.iterators.
- [ngio top-level API](https://biovisioncenter.github.io/ngio/stable/api/ngio/ngio/): Roi, PixelSize, Dimensions, NgioConfig and other core types.

## Optional

- [Changelog](https://biovisioncenter.github.io/ngio/stable/changelog/): Release history.
- [Contributing](https://biovisioncenter.github.io/ngio/stable/contributing/): Development setup, tests and PR workflow.
- [Code of Conduct](https://biovisioncenter.github.io/ngio/stable/code_of_conduct/): Contributor Covenant v2.1.
