ngff_zarr.hcs

High Content Screening (HCS) support for OME-Zarr NGFF.

This module provides functions for reading and writing HCS plate data according to the NGFF specification.

Memory Management: The HCS implementation includes bounded caching to prevent memory issues when working with large plates:

- Wells are cached in HCSPlate with configurable limit (default: 500)
- Images are cached in HCSWell with configurable limit (default: 100)
- LRU (Least Recently Used) eviction policy prevents unbounded growth
- Cache sizes can be configured via ngff_zarr.config or function parameters

Module Contents

Classes

LRUCache	Least Recently Used (LRU) cache with size limit for HCS image caching.
HCSPlate	High Content Screening plate representation.
HCSWell	High Content Screening well representation.
HCSPlateWriter	Context manager for writing HCS plates with deferred .ozx zipping.

Functions

from_hcs_zarr	Read an HCS plate from an OME-Zarr NGFF store.
to_hcs_zarr	Write an HCS plate to an OME-Zarr NGFF store.
write_hcs_well_image	Write a single field of view (image) to a well in an HCS plate structure.

API

class ngff_zarr.hcs.LRUCache(max_size: int = 100)

Least Recently Used (LRU) cache with size limit for HCS image caching.

This prevents unbounded memory growth when accessing many images from large plates.

Initialization

get(key)

set(key, value)

__contains__(key)

__getitem__(key)

Support dict-like access.

__setitem__(key, value)

Support dict-like assignment.

clear()

Clear all cached items.

class ngff_zarr.hcs.HCSPlate(

store,

plate_metadata: ngff_zarr.v04.zarr_metadata.Plate,

well_cache_size: Optional[int] = None,

image_cache_size: Optional[int] = None,

)

High Content Screening plate representation.

This class holds the plate metadata and provides access to wells and their associated images.

Initialization

property name: Optional[str]

property rows: List[ngff_zarr.v04.zarr_metadata.PlateRow]

property columns: List[ngff_zarr.v04.zarr_metadata.PlateColumn]

property wells: List[ngff_zarr.v04.zarr_metadata.PlateWell]

property acquisitions: Optional[List[ngff_zarr.v04.zarr_metadata.PlateAcquisition]]

property field_count: Optional[int]

get_well(

row_name: str,

column_name: str,

) → Optional[ngff_zarr.hcs.HCSWell]

Get a well by row and column name.

get_well_by_indices(

row_index: int,

column_index: int,

) → Optional[ngff_zarr.hcs.HCSWell]

Get a well by row and column indices.

class ngff_zarr.hcs.HCSWell(

store,

well_path: str,

well_metadata: ngff_zarr.v04.zarr_metadata.PlateWell,

well_group_metadata: ngff_zarr.v04.zarr_metadata.Well,

image_cache_size: Optional[int] = None,

)

High Content Screening well representation.

Contains multiple fields of view (images) for a single well.

Initialization

classmethod from_store(

store,

well_path: str,

well_metadata: ngff_zarr.v04.zarr_metadata.PlateWell,

image_cache_size: Optional[int] = None,

) → ngff_zarr.hcs.HCSWell

Load a well from a zarr store.

property row_index: int

property column_index: int

property images: List[ngff_zarr.v04.zarr_metadata.WellImage]

get_image(

field_index: int = 0,

) → Optional[ngff_zarr.multiscales.Multiscales]

Get a field of view (image) by index.

get_image_by_acquisition(

acquisition_id: int,

field_index: int = 0,

) → Optional[ngff_zarr.multiscales.Multiscales]

Get a field of view by acquisition ID and field index.

ngff_zarr.hcs.from_hcs_zarr(

store,

validate: bool = False,

well_cache_size: Optional[int] = None,

image_cache_size: Optional[int] = None,

) → ngff_zarr.hcs.HCSPlate

Read an HCS plate from an OME-Zarr NGFF store.

Parameters

store Store or path to directory in file system. Can be a .ozx file. validate : bool If True, validate the NGFF metadata against the schema. well_cache_size : int, optional Maximum number of wells to cache. If None, uses config default. image_cache_size : int, optional Maximum number of images to cache per well. If None, uses config default.

Returns

plate : HCSPlate The loaded HCS plate with wells and images.

ngff_zarr.hcs.to_hcs_zarr(plate: ngff_zarr.hcs.HCSPlate, store) → None

Write an HCS plate to an OME-Zarr NGFF store.

Parameters

plate : HCSPlate The HCS plate to write. store Store or path to directory in file system.

class ngff_zarr.hcs.HCSPlateWriter(

store,

plate_metadata: ngff_zarr.v04.zarr_metadata.Plate,

version: str = '0.5',

overwrite: bool = True,

)

Context manager for writing HCS plates with deferred .ozx zipping.

This class enables efficient writing of multiple well images by:

• Deferring .ozx file creation until all wells are written

• Supporting parallel writes to the same plate

• Avoiding repeated zipping operations for each well

For .ozx files, this approach writes to a temporary zarr store and only creates the final .ozx ZIP archive when exiting the context manager. For regular .ome.zarr directories, it writes directly to the target.

Parameters

store : str or Path Target store path. Can be .ozx, .ome.zarr, or .zarr extension. plate_metadata : Plate Plate-level metadata containing rows, columns, wells, and other plate information. version : str, optional OME-Zarr specification version (default: “0.5”). Note: .ozx format requires version 0.5. overwrite : bool, optional If True, overwrite existing store (default: True).

Examples

Writing multiple wells efficiently to .ozx format:

import ngff_zarr as nz from ngff_zarr.hcs import HCSPlateWriter from ngff_zarr.v04.zarr_metadata import Plate, PlateColumn, PlateRow, PlateWell

Create plate metadata

plate_metadata = nz.Plate( … columns=[nz.PlateColumn(name=”1”), nz.PlateColumn(name=”2”)], … rows=[nz.PlateRow(name=”A”), nz.PlateRow(name=”B”)], … wells=[ … nz.PlateWell(path=”A/1”, rowIndex=0, columnIndex=0), … nz.PlateWell(path=”A/2”, rowIndex=0, columnIndex=1), … ], … version=”0.5”, … )

Use context manager to write multiple wells

with HCSPlateWriter(“my_plate.ozx”, plate_metadata) as writer: … for well_data in acquisition_data: … writer.write_well_image( … multiscales=well_data.image, … row_name=well_data.row, … column_name=well_data.col, … field_index=well_data.field, … )

.ozx file is created when exiting the context

Parallel writing example:

from concurrent.futures import ThreadPoolExecutor

def write_well(writer, well_data): … writer.write_well_image( … multiscales=well_data.image, … row_name=well_data.row, … column_name=well_data.col, … field_index=well_data.field, … )

with HCSPlateWriter(“plate.ozx”, plate_metadata) as writer: … with ThreadPoolExecutor(max_workers=4) as executor: … executor.map(lambda wd: write_well(writer, wd), well_data_list)

Initialization

__enter__()

Initialize the plate structure and return the writer.

__exit__(exc_type, exc_val, exc_tb)

Finalize the plate by creating .ozx if needed and cleaning up.

write_well_image(

multiscales: ngff_zarr.multiscales.Multiscales,

row_name: str,

column_name: str,

field_index: int = 0,

acquisition_id: int = 0,

well_metadata: Optional[ngff_zarr.v04.zarr_metadata.Well] = None,

**kwargs,

) → None

Write a single field of view (image) to a well.

Parameters

multiscales : Multiscales Multiscales OME-NGFF image pixel data and metadata for the field of view. row_name : str Name of the row (e.g., “A”, “B”, “C”). column_name : str Name of the column (e.g., “1”, “2”, “3”). field_index : int, optional Index of the field of view within the well (default: 0). acquisition_id : int, optional Acquisition ID for time series or multi-condition experiments (default: 0). well_metadata : Well, optional Well-level metadata. If None, will be created automatically. **kwargs Additional arguments passed to to_ngff_zarr.

ngff_zarr.hcs.write_hcs_well_image(

store,

multiscales: ngff_zarr.multiscales.Multiscales,

plate_metadata: ngff_zarr.v04.zarr_metadata.Plate,

row_name: str,

column_name: str,

field_index: int = 0,

acquisition_id: int = 0,

well_metadata: Optional[ngff_zarr.v04.zarr_metadata.Well] = None,

version: str = '0.4',

**kwargs,

) → None

Write a single field of view (image) to a well in an HCS plate structure.

This function writes individual well images as they are acquired in HCS workflows. The plate structure should be created first using to_hcs_zarr(), then individual field images can be written using this function.

Parameters

store : StoreLike Store or path to directory in file system where the HCS plate will be written. multiscales : Multiscales Multiscales OME-NGFF image pixel data and metadata for the field of view. plate_metadata : Plate Plate-level metadata containing rows, columns, wells, and other plate information. row_name : str Name of the row (e.g., “A”, “B”, “C”). column_name : str Name of the column (e.g., “1”, “2”, “3”). field_index : int, optional Index of the field of view within the well (default: 0). acquisition_id : int, optional Acquisition ID for time series or multi-condition experiments (default: 0). well_metadata : Well, optional Well-level metadata. If None, will be created automatically. version : str, optional OME-Zarr specification version (default: “0.4”). **kwargs Additional arguments passed to to_ngff_zarr.

Examples

import ngff_zarr as nz from ngff_zarr.v04.zarr_metadata import Plate, PlateColumn, PlateRow, PlateWell

Create plate metadata

columns = [nz.PlateColumn(name=”1”), nz.PlateColumn(name=”2”)] rows = [nz.PlateRow(name=”A”), nz.PlateRow(name=”B”)] wells = [ … nz.PlateWell(path=”A/1”, rowIndex=0, columnIndex=0), … nz.PlateWell(path=”A/2”, rowIndex=0, columnIndex=1), … nz.PlateWell(path=”B/1”, rowIndex=1, columnIndex=0), … nz.PlateWell(path=”B/2”, rowIndex=1, columnIndex=1), … ] plate_metadata = nz.Plate( … columns=columns, … rows=rows, … wells=wells, … name=”My Screening Plate”, … field_count=2 … )

First, create the plate structure

hcs_plate = nz.HCSPlate(metadata=plate_metadata) nz.to_hcs_zarr(hcs_plate, “my_plate.ome.zarr”)

Then write individual field images as they are acquired

nz.write_hcs_well_image( … store=”my_plate.ome.zarr”, … multiscales=field_image, # Your Multiscales image … plate_metadata=plate_metadata, … row_name=”A”, … column_name=”1”, … field_index=0 … )

Notes

For writing multiple wells to .ozx format efficiently, or for parallel writing, use the HCSPlateWriter context manager instead of calling this function directly. The context manager defers .ozx file creation until all wells are written.