HCS API Documentation

Open a Plate

ngio.open_ome_zarr_plate

open_ome_zarr_plate(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    parallel_safe: bool = True,
) -> OmeZarrPlate

Open an OME-Zarr plate.

Parameters:

• store (StoreOrGroup) –

  The Zarr store or group that stores the plate.

• cache (bool, default: False ) –

  Whether to use a cache for the zarr group metadata.

• mode (AccessModeLiteral, default: 'r+' ) –

  The access mode for the image. Defaults to "r+".

• parallel_safe (bool, default: True ) –

  Whether the group handler is parallel safe.

Source code in ngio/hcs/_plate.py

def open_ome_zarr_plate(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    parallel_safe: bool = True,
) -> OmeZarrPlate:
    """Open an OME-Zarr plate.

    Args:
        store (StoreOrGroup): The Zarr store or group that stores the plate.
        cache (bool): Whether to use a cache for the zarr group metadata.
        mode (AccessModeLiteral): The
            access mode for the image. Defaults to "r+".
        parallel_safe (bool): Whether the group handler is parallel safe.
    """
    group_handler = ZarrGroupHandler(
        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
    )
    return OmeZarrPlate(group_handler)

ngio.OmeZarrPlate Class Reference

ngio.OmeZarrPlate

OmeZarrPlate(
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
)

A class to handle the Plate Collection in an OME-Zarr file.

Initialize the LabelGroupHandler.

Parameters:

• group_handler (ZarrGroupHandler) –

  The Zarr group handler that contains the Plate.

• table_container (TablesContainer | None, default: None ) –

  The tables container that contains plate level tables.

Source code in ngio/hcs/_plate.py

def __init__(
    self,
    group_handler: ZarrGroupHandler,
    table_container: TablesContainer | None = None,
) -> None:
    """Initialize the LabelGroupHandler.

    Args:
        group_handler: The Zarr group handler that contains the Plate.
        table_container: The tables container that contains plate level tables.
    """
    self._group_handler = group_handler
    self._meta_handler = find_plate_meta_handler(group_handler)
    self._tables_container = table_container

meta_handler property

meta_handler

Return the metadata handler.

meta property

meta

Return the metadata.

columns property

columns: list[str]

Return the number of columns in the plate.

rows property

rows: list[str]

Return the number of rows in the plate.

acquisitions_names property

acquisitions_names: list[str | None]

Return the acquisitions in the plate.

acquisition_ids property

acquisition_ids: list[int]

Return the acquisitions ids in the plate.

tables_container property

tables_container: TablesContainer

Return the tables container.

wells_paths

wells_paths() -> list[str]

Return the wells paths in the plate.

Source code in ngio/hcs/_plate.py

def wells_paths(self) -> list[str]:
    """Return the wells paths in the plate."""
    return self.meta.wells_paths

images_paths_async async

images_paths_async(
    acquisition: int | None = None,
) -> list[str]

Return the images paths in the plate asynchronously.

If acquisition is None, return all images paths in the plate. Else, return the images paths in the plate for the given acquisition.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

async def images_paths_async(self, acquisition: int | None = None) -> list[str]:
    """Return the images paths in the plate asynchronously.

    If acquisition is None, return all images paths in the plate.
    Else, return the images paths in the plate for the given acquisition.

    Args:
        acquisition (int | None): The acquisition id to filter the images.
    """
    wells = await self.get_wells_async()
    paths = []
    for well_path, well in wells.items():
        for img_path in well.paths(acquisition):
            paths.append(f"{well_path}/{img_path}")
    return paths

images_paths

images_paths(acquisition: int | None = None) -> list[str]

Return the images paths in the plate.

If acquisition is None, return all images paths in the plate. Else, return the images paths in the plate for the given acquisition.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

def images_paths(self, acquisition: int | None = None) -> list[str]:
    """Return the images paths in the plate.

    If acquisition is None, return all images paths in the plate.
    Else, return the images paths in the plate for the given acquisition.

    Args:
        acquisition (int | None): The acquisition id to filter the images.
    """
    wells = self.get_wells()
    images = []
    for well_path, well in wells.items():
        for img_path in well.paths(acquisition):
            images.append(f"{well_path}/{img_path}")
    return images

well_images_paths

well_images_paths(
    row: str,
    column: int | str,
    acquisition: int | None = None,
) -> list[str]

Return the images paths in a well.

If acquisition is None, return all images paths in the well. Else, return the images paths in the well for the given acquisition.

Parameters:

• row (str) –

  The row of the well.

• column (int | str) –

  The column of the well.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

def well_images_paths(
    self, row: str, column: int | str, acquisition: int | None = None
) -> list[str]:
    """Return the images paths in a well.

    If acquisition is None, return all images paths in the well.
    Else, return the images paths in the well for the given acquisition.

    Args:
        row (str): The row of the well.
        column (int | str): The column of the well.
        acquisition (int | None): The acquisition id to filter the images.
    """
    images = []
    well = self.get_well(row=row, column=column)
    for path in well.paths(acquisition):
        images.append(self._image_path(row=row, column=column, path=path))
    return images

get_image_acquisition_id

get_image_acquisition_id(
    row: str, column: int | str, image_path: str
) -> int | None

Get the acquisition id of an image in a well.

Parameters:

• row (str) –

  The row of the well.

• column (int | str) –

  The column of the well.

• image_path (str) –

  The path of the image.

Returns:

• int | None –

  int | None: The acquisition id of the image.

Source code in ngio/hcs/_plate.py

def get_image_acquisition_id(
    self, row: str, column: int | str, image_path: str
) -> int | None:
    """Get the acquisition id of an image in a well.

    Args:
        row (str): The row of the well.
        column (int | str): The column of the well.
        image_path (str): The path of the image.

    Returns:
        int | None: The acquisition id of the image.
    """
    well = self.get_well(row=row, column=column)
    return well.get_image_acquisition_id(image_path=image_path)

get_well

get_well(row: str, column: int | str) -> OmeZarrWell

Get a well from the plate.

Parameters:

• row (str) –

  The row of the well.

• column (int | str) –

  The column of the well.

Returns:

• OmeZarrWell ( OmeZarrWell ) –

  The well.

Source code in ngio/hcs/_plate.py

def get_well(self, row: str, column: int | str) -> OmeZarrWell:
    """Get a well from the plate.

    Args:
        row (str): The row of the well.
        column (int | str): The column of the well.

    Returns:
        OmeZarrWell: The well.
    """
    well_path = self._well_path(row=row, column=column)
    group_handler = self._group_handler.derive_handler(well_path)
    return OmeZarrWell(group_handler)

get_wells_async async

get_wells_async() -> dict[str, OmeZarrWell]

Get all wells in the plate asynchronously.

This method processes wells in parallel for improved performance when working with a large number of wells.

Returns:

• dict[str, OmeZarrWell] –

  dict[str, OmeZarrWell]: A dictionary of wells, where the key is the well path and the value is the well object.

Source code in ngio/hcs/_plate.py

async def get_wells_async(self) -> dict[str, OmeZarrWell]:
    """Get all wells in the plate asynchronously.

    This method processes wells in parallel for improved performance
    when working with a large number of wells.

    Returns:
        dict[str, OmeZarrWell]: A dictionary of wells, where the key is the well
            path and the value is the well object.
    """
    wells = self._group_handler.get_from_cache("wells")
    if wells is not None:
        assert isinstance(wells, dict)
        return wells

    def process_well(well_path):
        group_handler = self._group_handler.derive_handler(well_path)
        well = OmeZarrWell(group_handler)
        return well_path, well

    wells, tasks = {}, []
    for well_path in self.wells_paths():
        task = asyncio.to_thread(process_well, well_path)
        tasks.append(task)

    results = await asyncio.gather(*tasks)
    for well_path, well in results:
        wells[well_path] = well

    self._group_handler.add_to_cache("wells", wells)
    return wells

get_wells

get_wells() -> dict[str, OmeZarrWell]

Get all wells in the plate.

Returns:

• dict[str, OmeZarrWell] –

  dict[str, OmeZarrWell]: A dictionary of wells, where the key is the well path and the value is the well object.

Source code in ngio/hcs/_plate.py

def get_wells(self) -> dict[str, OmeZarrWell]:
    """Get all wells in the plate.

    Returns:
        dict[str, OmeZarrWell]: A dictionary of wells, where the key is the well
            path and the value is the well object.
    """
    wells = self._group_handler.get_from_cache("wells")
    if wells is not None:
        assert isinstance(wells, dict)
        return wells

    def process_well(well_path):
        group_handler = self._group_handler.derive_handler(well_path)
        well = OmeZarrWell(group_handler)
        return well_path, well

    wells = {}
    for well_path in self.wells_paths():
        _, well = process_well(well_path)
        wells[well_path] = well

    self._group_handler.add_to_cache("wells", wells)
    return wells

get_images_async async

get_images_async(
    acquisition: int | None = None,
) -> dict[str, OmeZarrContainer]

Get all images in the plate asynchronously.

This method processes images in parallel for improved performance when working with a large number of images.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Returns:

• dict[str, OmeZarrContainer] –

  dict[str, OmeZarrContainer]: A dictionary of images, where the key is the image path and the value is the image object.

Source code in ngio/hcs/_plate.py

async def get_images_async(
    self, acquisition: int | None = None
) -> dict[str, OmeZarrContainer]:
    """Get all images in the plate asynchronously.

    This method processes images in parallel for improved performance
    when working with a large number of images.

    Args:
        acquisition: The acquisition id to filter the images.

    Returns:
        dict[str, OmeZarrContainer]: A dictionary of images, where the key is the
            image path and the value is the image object.
    """
    images = self._group_handler.get_from_cache("images")
    if images is not None:
        assert isinstance(images, dict)
        return images

    paths = await self.images_paths_async(acquisition=acquisition)

    def process_image(image_path):
        """Process a single image and return the image path and image object."""
        img_group_handler = self._group_handler.derive_handler(image_path)
        image = OmeZarrContainer(img_group_handler)
        return image_path, image

    images, tasks = {}, []
    for image_path in paths:
        task = asyncio.to_thread(process_image, image_path)
        tasks.append(task)

    results = await asyncio.gather(*tasks)

    for image_path, image in results:
        images[image_path] = image

    self._group_handler.add_to_cache("images", images)
    return images

get_images

get_images(
    acquisition: int | None = None,
) -> dict[str, OmeZarrContainer]

Get all images in the plate.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

def get_images(self, acquisition: int | None = None) -> dict[str, OmeZarrContainer]:
    """Get all images in the plate.

    Args:
        acquisition: The acquisition id to filter the images.
    """
    images = self._group_handler.get_from_cache("images")
    if images is not None:
        assert isinstance(images, dict)
        return images
    paths = self.images_paths(acquisition=acquisition)

    def process_image(image_path):
        """Process a single image and return the image path and image object."""
        img_group_handler = self._group_handler.derive_handler(image_path)
        image = OmeZarrContainer(img_group_handler)
        return image_path, image

    images = {}
    for image_path in paths:
        _, image = process_image(image_path)
        images[image_path] = image

    self._group_handler.add_to_cache("images", images)
    return images

get_image

get_image(
    row: str, column: int | str, image_path: str
) -> OmeZarrContainer

Get an image from the plate.

Parameters:

• row (str) –

  The row of the well.

• column (int | str) –

  The column of the well.

• image_path (str) –

  The path of the image.

Returns:

• OmeZarrContainer ( OmeZarrContainer ) –

  The image.

Source code in ngio/hcs/_plate.py

def get_image(
    self, row: str, column: int | str, image_path: str
) -> OmeZarrContainer:
    """Get an image from the plate.

    Args:
        row (str): The row of the well.
        column (int | str): The column of the well.
        image_path (str): The path of the image.

    Returns:
        OmeZarrContainer: The image.
    """
    image_path = self._image_path(row=row, column=column, path=image_path)
    group_handler = self._group_handler.derive_handler(image_path)
    return OmeZarrContainer(group_handler)

get_image_store

get_image_store(
    row: str, column: int | str, image_path: str
) -> StoreOrGroup

Get the image store from the plate.

Parameters:

• row (str) –

  The row of the well.

• column (int | str) –

  The column of the well.

• image_path (str) –

  The path of the image.

Source code in ngio/hcs/_plate.py

def get_image_store(
    self, row: str, column: int | str, image_path: str
) -> StoreOrGroup:
    """Get the image store from the plate.

    Args:
        row (str): The row of the well.
        column (int | str): The column of the well.
        image_path (str): The path of the image.
    """
    well = self.get_well(row=row, column=column)
    return well.get_image_store(image_path=image_path)

get_well_images

get_well_images(
    row: str,
    column: str | int,
    acquisition: int | None = None,
) -> dict[str, OmeZarrContainer]

Get all images in a well.

Parameters:

• row (str) –

  The row of the well.

• column (str | int) –

  The column of the well.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

def get_well_images(
    self, row: str, column: str | int, acquisition: int | None = None
) -> dict[str, OmeZarrContainer]:
    """Get all images in a well.

    Args:
        row: The row of the well.
        column: The column of the well.
        acquisition: The acquisition id to filter the images.
    """
    images = {}
    for image_paths in self.well_images_paths(
        row=row, column=column, acquisition=acquisition
    ):
        group_handler = self._group_handler.derive_handler(image_paths)
        images[image_paths] = OmeZarrContainer(group_handler)
    return images

atomic_add_image

atomic_add_image(
    row: str,
    column: int | str,
    image_path: str,
    acquisition_id: int | None = None,
    acquisition_name: str | None = None,
) -> str

Parallel safe version of add_image.

Source code in ngio/hcs/_plate.py

def atomic_add_image(
    self,
    row: str,
    column: int | str,
    image_path: str,
    acquisition_id: int | None = None,
    acquisition_name: str | None = None,
) -> str:
    """Parallel safe version of add_image."""
    if image_path is None:
        raise ValueError(
            "Image path cannot be None for atomic add_image. "
            "If your intent is to add a well, use add_well instead."
        )
    path = self._add_image(
        row=row,
        column=column,
        image_path=image_path,
        acquisition_id=acquisition_id,
        acquisition_name=acquisition_name,
        atomic=True,
    )
    return path

add_image

add_image(
    row: str,
    column: int | str,
    image_path: str,
    acquisition_id: int | None = None,
    acquisition_name: str | None = None,
) -> str

Add an image to an ome-zarr plate.

Source code in ngio/hcs/_plate.py

def add_image(
    self,
    row: str,
    column: int | str,
    image_path: str,
    acquisition_id: int | None = None,
    acquisition_name: str | None = None,
) -> str:
    """Add an image to an ome-zarr plate."""
    if image_path is None:
        raise ValueError(
            "Image path cannot be None for atomic add_image. "
            "If your intent is to add a well, use add_well instead."
        )
    path = self._add_image(
        row=row,
        column=column,
        image_path=image_path,
        acquisition_id=acquisition_id,
        acquisition_name=acquisition_name,
        atomic=False,
    )
    return path

add_well

add_well(row: str, column: int | str) -> OmeZarrWell

Add a well to an ome-zarr plate.

Source code in ngio/hcs/_plate.py

def add_well(
    self,
    row: str,
    column: int | str,
) -> OmeZarrWell:
    """Add a well to an ome-zarr plate."""
    _ = self._add_image(
        row=row,
        column=column,
        image_path=None,
        acquisition_id=None,
        acquisition_name=None,
        atomic=False,
    )
    return self.get_well(row=row, column=column)

add_column

add_column(column: int | str) -> OmeZarrPlate

Add a column to an ome-zarr plate.

Source code in ngio/hcs/_plate.py

def add_column(
    self,
    column: int | str,
) -> "OmeZarrPlate":
    """Add a column to an ome-zarr plate."""
    meta, _ = self.meta.add_column(column)
    self.meta_handler.write_meta(meta)
    self.meta_handler._group_handler.clean_cache()
    return self

add_row

add_row(row: str) -> OmeZarrPlate

Add a row to an ome-zarr plate.

Source code in ngio/hcs/_plate.py

def add_row(
    self,
    row: str,
) -> "OmeZarrPlate":
    """Add a row to an ome-zarr plate."""
    meta, _ = self.meta.add_row(row)
    self.meta_handler.write_meta(meta)
    self.meta_handler._group_handler.clean_cache()
    return self

add_acquisition

add_acquisition(
    acquisition_id: int, acquisition_name: str
) -> OmeZarrPlate

Add an acquisition to an ome-zarr plate.

Be aware that this is not a parallel safe operation.

Parameters:

• acquisition_id (int) –

  The acquisition id.

• acquisition_name (str) –

  The acquisition name.

Source code in ngio/hcs/_plate.py

def add_acquisition(
    self,
    acquisition_id: int,
    acquisition_name: str,
) -> "OmeZarrPlate":
    """Add an acquisition to an ome-zarr plate.

    Be aware that this is not a parallel safe operation.

    Args:
        acquisition_id (int): The acquisition id.
        acquisition_name (str): The acquisition name.
    """
    meta = self.meta.add_acquisition(
        acquisition_id=acquisition_id, acquisition_name=acquisition_name
    )
    self.meta_handler.write_meta(meta)
    self.meta_handler._group_handler.clean_cache()
    return self

atomic_remove_image

atomic_remove_image(
    row: str, column: int | str, image_path: str
)

Parallel safe version of remove_image.

Source code in ngio/hcs/_plate.py

def atomic_remove_image(
    self,
    row: str,
    column: int | str,
    image_path: str,
):
    """Parallel safe version of remove_image."""
    return self._remove_image(
        row=row,
        column=column,
        image_path=image_path,
        atomic=True,
    )

remove_image

remove_image(row: str, column: int | str, image_path: str)

Remove an image from an ome-zarr plate.

Source code in ngio/hcs/_plate.py

def remove_image(
    self,
    row: str,
    column: int | str,
    image_path: str,
):
    """Remove an image from an ome-zarr plate."""
    return self._remove_image(
        row=row,
        column=column,
        image_path=image_path,
        atomic=False,
    )

derive_plate

derive_plate(
    store: StoreOrGroup,
    plate_name: str | None = None,
    version: NgffVersions = "0.4",
    keep_acquisitions: bool = False,
    cache: bool = False,
    overwrite: bool = False,
    parallel_safe: bool = True,
) -> OmeZarrPlate

Derive a new OME-Zarr plate from an existing one.

Parameters:

• store (StoreOrGroup) –

  The Zarr store or group that stores the plate.

• plate_name (str | None, default: None ) –

  The name of the new plate.

• version (NgffVersion, default: '0.4' ) –

  The version of the new plate.

• keep_acquisitions (bool, default: False ) –

  Whether to keep the acquisitions in the new plate.

• cache (bool, default: False ) –

  Whether to use a cache for the zarr group metadata.

• overwrite (bool, default: False ) –

  Whether to overwrite the existing plate.

• parallel_safe (bool, default: True ) –

  Whether the group handler is parallel safe.

Source code in ngio/hcs/_plate.py

def derive_plate(
    self,
    store: StoreOrGroup,
    plate_name: str | None = None,
    version: NgffVersions = "0.4",
    keep_acquisitions: bool = False,
    cache: bool = False,
    overwrite: bool = False,
    parallel_safe: bool = True,
) -> "OmeZarrPlate":
    """Derive a new OME-Zarr plate from an existing one.

    Args:
        store (StoreOrGroup): The Zarr store or group that stores the plate.
        plate_name (str | None): The name of the new plate.
        version (NgffVersion): The version of the new plate.
        keep_acquisitions (bool): Whether to keep the acquisitions in the new plate.
        cache (bool): Whether to use a cache for the zarr group metadata.
        overwrite (bool): Whether to overwrite the existing plate.
        parallel_safe (bool): Whether the group handler is parallel safe.
    """
    return derive_ome_zarr_plate(
        ome_zarr_plate=self,
        store=store,
        plate_name=plate_name,
        version=version,
        keep_acquisitions=keep_acquisitions,
        cache=cache,
        overwrite=overwrite,
        parallel_safe=parallel_safe,
    )

list_tables

list_tables(
    filter_types: TypedTable | str | None = None,
) -> list[str]

List all tables in the image.

Source code in ngio/hcs/_plate.py

def list_tables(self, filter_types: TypedTable | str | None = None) -> list[str]:
    """List all tables in the image."""
    return self.tables_container.list(filter_types=filter_types)

list_roi_tables

list_roi_tables() -> list[str]

List all ROI tables in the image.

Source code in ngio/hcs/_plate.py

def list_roi_tables(self) -> list[str]:
    """List all ROI tables in the image."""
    masking_roi = self.tables_container.list(
        filter_types="masking_roi_table",
    )
    roi = self.tables_container.list(
        filter_types="roi_table",
    )
    return masking_roi + roi

get_roi_table

get_roi_table(name: str) -> RoiTable

Get a ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/hcs/_plate.py

def get_roi_table(self, name: str) -> RoiTable:
    """Get a ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, RoiTable):
        raise NgioValueError(f"Table {name} is not a ROI table. Got {type(table)}")
    return table

get_masking_roi_table

get_masking_roi_table(name: str) -> MaskingRoiTable

Get a masking ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/hcs/_plate.py

def get_masking_roi_table(self, name: str) -> MaskingRoiTable:
    """Get a masking ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, MaskingRoiTable):
        raise NgioValueError(
            f"Table {name} is not a masking ROI table. Got {type(table)}"
        )
    return table

get_feature_table

get_feature_table(name: str) -> FeatureTable

Get a feature table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/hcs/_plate.py

def get_feature_table(self, name: str) -> FeatureTable:
    """Get a feature table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, FeatureTable):
        raise NgioValueError(
            f"Table {name} is not a feature table. Got {type(table)}"
        )
    return table

get_generic_roi_table

get_generic_roi_table(name: str) -> GenericRoiTable

Get a generic ROI table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/hcs/_plate.py

def get_generic_roi_table(self, name: str) -> GenericRoiTable:
    """Get a generic ROI table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, GenericRoiTable):
        raise NgioValueError(
            f"Table {name} is not a generic ROI table. Got {type(table)}"
        )
    return table

get_condition_table

get_condition_table(name: str) -> ConditionTable

Get a condition table from the image.

Parameters:

• name (str) –

  The name of the table.

Source code in ngio/hcs/_plate.py

def get_condition_table(self, name: str) -> ConditionTable:
    """Get a condition table from the image.

    Args:
        name (str): The name of the table.
    """
    table = self.tables_container.get(name=name, strict=True)
    if not isinstance(table, ConditionTable):
        raise NgioValueError(
            f"Table {name} is not a condition table. Got {type(table)}"
        )
    return table

get_table

get_table(
    name: str, check_type: TypedTable | None = None
) -> Table

Get a table from the image.

Parameters:

• name (str) –

  The name of the table.

• check_type (TypedTable | None, default: None ) –

  Deprecated. Please use 'get_table_as' instead, or one of the type specific get_*table() methods.

Source code in ngio/hcs/_plate.py

def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
    """Get a table from the image.

    Args:
        name (str): The name of the table.
        check_type (TypedTable | None): Deprecated. Please use
            'get_table_as' instead, or one of the type specific
            get_*table() methods.

    """
    if check_type is not None:
        warnings.warn(
            "The 'check_type' argument is deprecated, and will be removed in "
            "ngio=0.3. Use 'get_table_as' instead or one of the "
            "type specific get_*table() methods.",
            DeprecationWarning,
            stacklevel=2,
        )
    return self.tables_container.get(name=name, strict=False)

get_table_as

get_table_as(
    name: str,
    table_cls: type[TableType],
    backend: TableBackend | None = None,
) -> TableType

Get a table from the image as a specific type.

Parameters:

• name (str) –

  The name of the table.

• table_cls (type[TableType]) –

  The type of the table.

• backend (TableBackend | None, default: None ) –

  The backend to use. If None, the default backend is used.

Source code in ngio/hcs/_plate.py

def get_table_as(
    self,
    name: str,
    table_cls: type[TableType],
    backend: TableBackend | None = None,
) -> TableType:
    """Get a table from the image as a specific type.

    Args:
        name (str): The name of the table.
        table_cls (type[TableType]): The type of the table.
        backend (TableBackend | None): The backend to use. If None,
            the default backend is used.
    """
    return self.tables_container.get_as(
        name=name,
        table_cls=table_cls,
        backend=backend,
    )

add_table

add_table(
    name: str,
    table: Table,
    backend: TableBackend = DefaultTableBackend,
    overwrite: bool = False,
) -> None

Add a table to the image.

Source code in ngio/hcs/_plate.py

def add_table(
    self,
    name: str,
    table: Table,
    backend: TableBackend = DefaultTableBackend,
    overwrite: bool = False,
) -> None:
    """Add a table to the image."""
    self.tables_container.add(
        name=name, table=table, backend=backend, overwrite=overwrite
    )

list_image_tables

list_image_tables(
    acquisition: int | None = None,
    filter_types: str | None = None,
    mode: Literal["common", "all"] = "common",
) -> list[str]

List all image tables in the image.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• filter_types (str | None, default: None ) –

  The type of tables to filter. If None, return all tables. Defaults to None.

• mode (Literal['common', 'all'], default: 'common' ) –

  The mode to use for listing the tables. If 'common', return only common tables between all images. If 'all', return all tables. Defaults to 'common'.

Source code in ngio/hcs/_plate.py

def list_image_tables(
    self,
    acquisition: int | None = None,
    filter_types: str | None = None,
    mode: Literal["common", "all"] = "common",
) -> list[str]:
    """List all image tables in the image.

    Args:
        acquisition (int | None): The acquisition id to filter the images.
        filter_types (str | None): The type of tables to filter. If None,
            return all tables. Defaults to None.
        mode (Literal["common", "all"]): The mode to use for listing the tables.
            If 'common', return only common tables between all images.
            If 'all', return all tables. Defaults to 'common'.
    """
    images = self.get_images(acquisition=acquisition)
    return list_image_tables(
        images=images.values(),
        filter_types=filter_types,
        mode=mode,
    )

list_image_tables_async async

list_image_tables_async(
    acquisition: int | None = None,
    filter_types: str | None = None,
    mode: Literal["common", "all"] = "common",
) -> list[str]

List all image tables in the image asynchronously.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• filter_types (str | None, default: None ) –

  The type of tables to filter. If None, return all tables. Defaults to None.

• mode (Literal['common', 'all'], default: 'common' ) –

  The mode to use for listing the tables. If 'common', return only common tables between all images. If 'all', return all tables. Defaults to 'common'.

Source code in ngio/hcs/_plate.py

async def list_image_tables_async(
    self,
    acquisition: int | None = None,
    filter_types: str | None = None,
    mode: Literal["common", "all"] = "common",
) -> list[str]:
    """List all image tables in the image asynchronously.

    Args:
        acquisition (int | None): The acquisition id to filter the images.
        filter_types (str | None): The type of tables to filter. If None,
            return all tables. Defaults to None.
        mode (Literal["common", "all"]): The mode to use for listing the tables.
            If 'common', return only common tables between all images.
            If 'all', return all tables. Defaults to 'common'.
    """
    images = await self.get_images_async(acquisition=acquisition)
    return await list_image_tables_async(
        images=images.values(),
        filter_types=filter_types,
        mode=mode,
    )

concatenate_image_tables

concatenate_image_tables(
    name: str,
    acquisition: int | None = None,
    strict: bool = True,
    index_key: str | None = None,
    mode: Literal["eager", "lazy"] = "eager",
) -> Table

Concatenate tables from all images in the plate.

Parameters:

• name (str) –

  The name of the table to concatenate.

• index_key (str | None, default: None ) –

  The key to use for the index of the concatenated table.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• strict (bool, default: True ) –

  If True, raise an error if the table is not found in the image.

• index_key (str | None, default: None ) –

  If a string is provided, a new index column will be created new_index_pattern = {row}{column}{path_in_well}_{label}

• mode (Literal['eager', 'lazy'], default: 'eager' ) –

  The mode to use for concatenation. Can be 'eager' or 'lazy'. if 'eager', the table will be loaded into memory. if 'lazy', the table will be loaded as a lazy frame.

Source code in ngio/hcs/_plate.py

def concatenate_image_tables(
    self,
    name: str,
    acquisition: int | None = None,
    strict: bool = True,
    index_key: str | None = None,
    mode: Literal["eager", "lazy"] = "eager",
) -> Table:
    """Concatenate tables from all images in the plate.

    Args:
        name: The name of the table to concatenate.
        index_key: The key to use for the index of the concatenated table.
        acquisition: The acquisition id to filter the images.
        strict: If True, raise an error if the table is not found in the image.
        index_key: If a string is provided, a new index column will be created
            new_index_pattern = {row}_{column}_{path_in_well}_{label}
        mode: The mode to use for concatenation. Can be 'eager' or 'lazy'.
            if 'eager', the table will be loaded into memory.
            if 'lazy', the table will be loaded as a lazy frame.
    """
    images = self.get_images(acquisition=acquisition)
    extras = _build_extras(images.keys())
    return concatenate_image_tables(
        images=images.values(),
        extras=extras,
        name=name,
        index_key=index_key,
        strict=strict,
        mode=mode,
    )

concatenate_image_tables_as

concatenate_image_tables_as(
    name: str,
    table_cls: type[TableType],
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> TableType

Concatenate tables from all images in the plate as a specific type.

Parameters:

• name (str) –

  The name of the table to concatenate.

• table_cls (type[TableType]) –

  The type of the table to concatenate.

• index_key (str | None, default: None ) –

  The key to use for the index of the concatenated table.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• index_key (str | None, default: None ) –

  If a string is provided, a new index column will be created new_index_pattern = {row}{column}{path_in_well}_{label}

• strict (bool, default: True ) –

  If True, raise an error if the table is not found in the image.

• mode (Literal['eager', 'lazy'], default: 'eager' ) –

  The mode to use for concatenation. Can be 'eager' or 'lazy'. if 'eager', the table will be loaded into memory. if 'lazy', the table will be loaded as a lazy frame.

Source code in ngio/hcs/_plate.py

def concatenate_image_tables_as(
    self,
    name: str,
    table_cls: type[TableType],
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> TableType:
    """Concatenate tables from all images in the plate as a specific type.

    Args:
        name: The name of the table to concatenate.
        table_cls: The type of the table to concatenate.
        index_key: The key to use for the index of the concatenated table.
        acquisition: The acquisition id to filter the images.
        index_key: If a string is provided, a new index column will be created
            new_index_pattern = {row}_{column}_{path_in_well}_{label}
        strict: If True, raise an error if the table is not found in the image.
        mode: The mode to use for concatenation. Can be 'eager' or 'lazy'.
            if 'eager', the table will be loaded into memory.
            if 'lazy', the table will be loaded as a lazy frame.
    """
    images = self.get_images(acquisition=acquisition)
    extras = _build_extras(images.keys())
    return concatenate_image_tables_as(
        images=images.values(),
        extras=extras,
        name=name,
        table_cls=table_cls,
        index_key=index_key,
        strict=strict,
        mode=mode,
    )

concatenate_image_tables_async async

concatenate_image_tables_async(
    name: str,
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> Table

Concatenate tables from all images in the plate asynchronously.

Parameters:

• name (str) –

  The name of the table to concatenate.

• index_key (str | None, default: None ) –

  The key to use for the index of the concatenated table.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• index_key (str | None, default: None ) –

  If a string is provided, a new index column will be created new_index_pattern = {row}{column}{path_in_well}_{label}

• strict (bool, default: True ) –

  If True, raise an error if the table is not found in the image.

• mode (Literal['eager', 'lazy'], default: 'eager' ) –

  The mode to use for concatenation. Can be 'eager' or 'lazy'. if 'eager', the table will be loaded into memory. if 'lazy', the table will be loaded as a lazy frame.

Source code in ngio/hcs/_plate.py

async def concatenate_image_tables_async(
    self,
    name: str,
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> Table:
    """Concatenate tables from all images in the plate asynchronously.

    Args:
        name: The name of the table to concatenate.
        index_key: The key to use for the index of the concatenated table.
        acquisition: The acquisition id to filter the images.
        index_key: If a string is provided, a new index column will be created
            new_index_pattern = {row}_{column}_{path_in_well}_{label}
        strict: If True, raise an error if the table is not found in the image.
        mode: The mode to use for concatenation. Can be 'eager' or 'lazy'.
            if 'eager', the table will be loaded into memory.
            if 'lazy', the table will be loaded as a lazy frame.
    """
    images = await self.get_images_async(acquisition=acquisition)
    extras = _build_extras(images.keys())
    return await concatenate_image_tables_async(
        images=images.values(),
        extras=extras,
        name=name,
        index_key=index_key,
        strict=strict,
        mode=mode,
    )

concatenate_image_tables_as_async async

concatenate_image_tables_as_async(
    name: str,
    table_cls: type[TableType],
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> TableType

Concatenate tables from all images in the plate as a specific type.

Parameters:

• name (str) –

  The name of the table to concatenate.

• table_cls (type[TableType]) –

  The type of the table to concatenate.

• index_key (str | None, default: None ) –

  The key to use for the index of the concatenated table.

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

• index_key (str | None, default: None ) –

  If a string is provided, a new index column will be created new_index_pattern = {row}{column}{path_in_well}_{label}

• strict (bool, default: True ) –

  If True, raise an error if the table is not found in the image.

• mode (Literal['eager', 'lazy'], default: 'eager' ) –

  The mode to use for concatenation. Can be 'eager' or 'lazy'. if 'eager', the table will be loaded into memory. if 'lazy', the table will be loaded as a lazy frame.

Source code in ngio/hcs/_plate.py

async def concatenate_image_tables_as_async(
    self,
    name: str,
    table_cls: type[TableType],
    acquisition: int | None = None,
    index_key: str | None = None,
    strict: bool = True,
    mode: Literal["eager", "lazy"] = "eager",
) -> TableType:
    """Concatenate tables from all images in the plate as a specific type.

    Args:
        name: The name of the table to concatenate.
        table_cls: The type of the table to concatenate.
        index_key: The key to use for the index of the concatenated table.
        acquisition: The acquisition id to filter the images.
        index_key: If a string is provided, a new index column will be created
            new_index_pattern = {row}_{column}_{path_in_well}_{label}
        strict: If True, raise an error if the table is not found in the image.
        mode: The mode to use for concatenation. Can be 'eager' or 'lazy'.
            if 'eager', the table will be loaded into memory.
            if 'lazy', the table will be loaded as a lazy frame.
    """
    images = await self.get_images_async(acquisition=acquisition)
    extras = _build_extras(images.keys())
    return await concatenate_image_tables_as_async(
        images=images.values(),
        extras=extras,
        name=name,
        table_cls=table_cls,
        index_key=index_key,
        strict=strict,
        mode=mode,
    )

Open a Well

ngio.open_ome_zarr_well

open_ome_zarr_well(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    parallel_safe: bool = True,
) -> OmeZarrWell

Open an OME-Zarr well.

Parameters:

• store (StoreOrGroup) –

  The Zarr store or group that stores the plate.

• cache (bool, default: False ) –

  Whether to use a cache for the zarr group metadata.

• mode (AccessModeLiteral, default: 'r+' ) –

  The access mode for the image. Defaults to "r+".

• parallel_safe (bool, default: True ) –

  Whether the group handler is parallel safe.

Source code in ngio/hcs/_plate.py

def open_ome_zarr_well(
    store: StoreOrGroup,
    cache: bool = False,
    mode: AccessModeLiteral = "r+",
    parallel_safe: bool = True,
) -> OmeZarrWell:
    """Open an OME-Zarr well.

    Args:
        store (StoreOrGroup): The Zarr store or group that stores the plate.
        cache (bool): Whether to use a cache for the zarr group metadata.
        mode (AccessModeLiteral): The access mode for the image. Defaults to "r+".
        parallel_safe (bool): Whether the group handler is parallel safe.
    """
    group_handler = ZarrGroupHandler(
        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
    )
    return OmeZarrWell(group_handler)

ngio.OmeZarrWell Class Reference

ngio.OmeZarrWell

OmeZarrWell(group_handler: ZarrGroupHandler)

A class to handle the Well Collection in an OME-Zarr file.

Initialize the LabelGroupHandler.

Parameters:

• group_handler (ZarrGroupHandler) –

  The Zarr group handler that contains the Well.

Source code in ngio/hcs/_plate.py

def __init__(self, group_handler: ZarrGroupHandler) -> None:
    """Initialize the LabelGroupHandler.

    Args:
        group_handler: The Zarr group handler that contains the Well.
    """
    self._group_handler = group_handler
    self._meta_handler = find_well_meta_handler(group_handler)

meta_handler property

meta_handler

Return the metadata handler.

meta property

meta

Return the metadata.

acquisition_ids property

acquisition_ids: list[int]

Return the acquisitions ids in the well.

paths

paths(acquisition: int | None = None) -> list[str]

Return the images paths in the well.

If acquisition is None, return all images paths in the well. Else, return the images paths in the well for the given acquisition.

Parameters:

• acquisition (int | None, default: None ) –

  The acquisition id to filter the images.

Source code in ngio/hcs/_plate.py

def paths(self, acquisition: int | None = None) -> list[str]:
    """Return the images paths in the well.

    If acquisition is None, return all images paths in the well.
    Else, return the images paths in the well for the given acquisition.

    Args:
        acquisition (int | None): The acquisition id to filter the images.
    """
    return self.meta.paths(acquisition)

get_image_store

get_image_store(image_path: str) -> StoreOrGroup

Get the image store from the well.

Parameters:

• image_path (str) –

  The path of the image.

Source code in ngio/hcs/_plate.py

def get_image_store(self, image_path: str) -> StoreOrGroup:
    """Get the image store from the well.

    Args:
        image_path (str): The path of the image.
    """
    return self._group_handler.get_group(image_path, create_mode=True)

get_image_acquisition_id

get_image_acquisition_id(image_path: str) -> int | None

Get the acquisition id of an image in the well.

Parameters:

• image_path (str) –

  The path of the image.

Returns:

• int | None –

  int | None: The acquisition id of the image.

Source code in ngio/hcs/_plate.py

def get_image_acquisition_id(self, image_path: str) -> int | None:
    """Get the acquisition id of an image in the well.

    Args:
        image_path (str): The path of the image.

    Returns:
        int | None: The acquisition id of the image.
    """
    return self.meta.get_image_acquisition_id(image_path=image_path)

get_image

get_image(image_path: str) -> OmeZarrContainer

Get an image from the well.

Parameters:

• image_path (str) –

  The path of the image.

Returns:

• OmeZarrContainer ( OmeZarrContainer ) –

  The image.

Source code in ngio/hcs/_plate.py

def get_image(self, image_path: str) -> OmeZarrContainer:
    """Get an image from the well.

    Args:
        image_path (str): The path of the image.

    Returns:
        OmeZarrContainer: The image.
    """
    handler = self._group_handler.derive_handler(image_path)
    return OmeZarrContainer(handler)

atomic_add_image

atomic_add_image(
    image_path: str,
    acquisition_id: int | None = None,
    strict: bool = True,
) -> StoreOrGroup

Parallel safe version of add_image.

Source code in ngio/hcs/_plate.py

def atomic_add_image(
    self,
    image_path: str,
    acquisition_id: int | None = None,
    strict: bool = True,
) -> StoreOrGroup:
    """Parallel safe version of add_image."""
    return self._add_image(
        image_path=image_path,
        acquisition_id=acquisition_id,
        atomic=True,
        strict=strict,
    )

add_image

add_image(
    image_path: str,
    acquisition_id: int | None = None,
    strict: bool = True,
) -> StoreOrGroup

Add an image to an ome-zarr well.

Parameters:

• image_path (str) –

  The path of the image.

• acquisition_id (int | None, default: None ) –

  The acquisition id to filter the images.

• strict (bool, default: True ) –

  Whether to check if the acquisition id is already exists in the well. Defaults to True. If False this might lead to acquision in a well that does not exist at the plate level.

Source code in ngio/hcs/_plate.py

def add_image(
    self,
    image_path: str,
    acquisition_id: int | None = None,
    strict: bool = True,
) -> StoreOrGroup:
    """Add an image to an ome-zarr well.

    Args:
        image_path (str): The path of the image.
        acquisition_id (int | None): The acquisition id to filter the images.
        strict (bool): Whether to check if the acquisition id is already exists
            in the well. Defaults to True. If False this might lead to
            acquision in a well that does not exist at the plate level.
    """
    return self._add_image(
        image_path=image_path,
        acquisition_id=acquisition_id,
        atomic=False,
        strict=strict,
    )