Skip to content

Readers

Read multi-FOV datasets

read_images 

read_images(
    path: StrOrBytesPath, data_type: Literal["ometiff", "ndtiff", "omezarr", "nd2"] | None = None
) -> BaseFOVMapping | Plate | Position | TiledPosition

Read image arrays and metadata from a Micro-Manager dataset.

Supported formats are Micro-Manager-acquired TIFF datasets (multi-page OME-TIFF, NDTIFF), and converted OME-Zarr (v0.4/v0.5 HCS layout).

Parameters:

  • path (StrOrBytesPath) –

    File path, directory path to ome-tiff series, or Zarr root path

  • data_type (Literal['ometiff', 'ndtiff', 'omezarr'], default: None ) –

    Dataset format, by default None

Returns:

MMStack OME-TIFF

MMStack 

MMStack(data_path: StrOrBytesPath)

Bases: MicroManagerFOVMapping

Micro-Manager multi-file OME-TIFF (MMStack) reader.

Parameters:

  • data_path (StrOrBytesPath) –

    Path to the directory containing OME-TIFF files or the path to the first OME-TIFF file in the series

root property 

root: Path

Root directory of the dataset.

micromanager_summary property 

micromanager_summary: dict | None

Micro-manager summary metadata.

hcs_position_labels property 

hcs_position_labels

Parse plate position labels generated by the HCS position generator

and split them into (row, column, FOV) components.

This method supports multiple label formats commonly produced by micromanager. The returned values are a 3-part tuple with the following interpretation: - row: usually a letter (e.g. 'A'), or '0' if not explicitly given - column: the well column number or site index - fov: the field-of-view index, typically zero-padded

Supported label formats and their outputs:

================ ======================== Format Output ================ ======================== "A1-Site_0" ('A', '1', '0') "1-Pos000_000" ('0', '1', '000000') "2-Pos000_001" ('0', '2', '000001') "1-Pos001" ('0', '1', '001000') "Pos-5-000_005" ('0', '5', '000005') ================ ========================

Returns:

  • list[tuple[str, str, str]] –

    A list of (row, column, fov) tuples corresponding to parsed label components in a uniform format.

Raises:

  • ValueError –

    If stage position metadata is missing or labels are not found.

close 

close() -> None

Close file handles

read_image_metadata 

read_image_metadata(p: int, t: int, c: int, z: int) -> dict | None

Read image plane metadata from the OME-TIFF file.

frame_locations 

frame_locations() -> Iterator[FrameLocation]

Yield the on-disk location of every stored frame, when the format allows byte-range reads.

Readers whose frames are contiguous and uncompressed override this so a converter can copy pixels without going through the array interface. The default declines.

Raises:

  • NotImplementedError –

    When this reader (or this particular dataset) has no byte-range representation.

MMOmeTiffFOV 

MMOmeTiffFOV(parent: MMStack, key: str)

Bases: MicroManagerFOV

frame_metadata 

frame_metadata(t: int, c: int, z: int) -> dict | None

Read image plane metadata from the OME-TIFF file.

channel_index 

channel_index(key: str) -> int

Return index of given channel.

NDTiff

NDTiffDataset 

NDTiffDataset(data_path: Path | str)

Bases: MicroManagerFOVMapping

Reader for ND-TIFF datasets acquired with Micro/Pycro-Manager,

effectively a wrapper of the ndtiff.Dataset class.

str_position_axis property 

str_position_axis: bool

Position axis is string-valued

str_channel_axis property 

str_channel_axis: bool

Channel axis is string-valued

root property 

root: Path

Root directory of the dataset.

micromanager_summary property 

micromanager_summary: dict | None

Micro-manager summary metadata.

hcs_position_labels property 

hcs_position_labels

Parse plate position labels generated by the HCS position generator

and split them into (row, column, FOV) components.

This method supports multiple label formats commonly produced by micromanager. The returned values are a 3-part tuple with the following interpretation: - row: usually a letter (e.g. 'A'), or '0' if not explicitly given - column: the well column number or site index - fov: the field-of-view index, typically zero-padded

Supported label formats and their outputs:

================ ======================== Format Output ================ ======================== "A1-Site_0" ('A', '1', '0') "1-Pos000_000" ('0', '1', '000000') "2-Pos000_001" ('0', '2', '000001') "1-Pos001" ('0', '1', '001000') "Pos-5-000_005" ('0', '5', '000005') ================ ========================

Returns:

  • list[tuple[str, str, str]] –

    A list of (row, column, fov) tuples corresponding to parsed label components in a uniform format.

Raises:

  • ValueError –

    If stage position metadata is missing or labels are not found.

get_image_metadata 

get_image_metadata(p: int | str, t: int, c: int | str, z: int) -> dict | None

Return image plane metadata at the requested PTCZ coordinates

Parameters:

  • p (int or str) –

    position index

  • t (int) –

    time index

  • c (int or str) –

    channel index

  • z (int) –

    slice/z index

Returns:

  • dict | None –

    Image plane metadata. None if not available.

frame_locations 

frame_locations() -> Iterator[FrameLocation]

Yield the on-disk location of every stored frame, from the already-parsed NDTiff index.

Enables copying pixels with plain byte-range reads instead of read_image. Indices follow the same axis ordering as :attr:xdata (rank within each sorted axis); the FOV key is the same string used by :meth:__getitem__.

Raises:

  • NotImplementedError –

    For datasets older than NDTiff v3, RGB or compressed frames, or frames whose shape/dtype differ from the dataset's; callers should fall back to array access.

NDTiffFOV 

NDTiffFOV(parent: NDTiffDataset, key: int)

Bases: MicroManagerFOV

channel_index 

channel_index(key: str) -> int

Return index of given channel.

ND2

ND2Dataset 

ND2Dataset(data_path: Path | str)

Bases: MicroManagerFOVMapping

Reader for Nikon ND2 datasets, wrapping nd2.ND2File.

Each ND2 stage position (P) is exposed as a separate FOV. Files without a position axis are read as a single FOV. Data are returned in canonical (T, C, Z, Y, X) order with native dtype preserved.

root property 

root: Path

Root directory of the dataset.

micromanager_summary property 

micromanager_summary: dict | None

Micro-manager summary metadata.

hcs_position_labels property 

hcs_position_labels

Parse plate position labels generated by the HCS position generator

and split them into (row, column, FOV) components.

This method supports multiple label formats commonly produced by micromanager. The returned values are a 3-part tuple with the following interpretation: - row: usually a letter (e.g. 'A'), or '0' if not explicitly given - column: the well column number or site index - fov: the field-of-view index, typically zero-padded

Supported label formats and their outputs:

================ ======================== Format Output ================ ======================== "A1-Site_0" ('A', '1', '0') "1-Pos000_000" ('0', '1', '000000') "2-Pos000_001" ('0', '2', '000001') "1-Pos001" ('0', '1', '001000') "Pos-5-000_005" ('0', '5', '000005') ================ ========================

Returns:

  • list[tuple[str, str, str]] –

    A list of (row, column, fov) tuples corresponding to parsed label components in a uniform format.

Raises:

  • ValueError –

    If stage position metadata is missing or labels are not found.

frame_locations 

frame_locations() -> Iterator[FrameLocation]

Yield the on-disk location of every stored frame, when the format allows byte-range reads.

Readers whose frames are contiguous and uncompressed override this so a converter can copy pixels without going through the array interface. The default declines.

Raises:

  • NotImplementedError –

    When this reader (or this particular dataset) has no byte-range representation.

ND2FOV 

ND2FOV(parent: ND2Dataset, key: str)

Bases: MicroManagerFOV

channel_index 

channel_index(key: str) -> int

Return index of given channel.

ClearControl

ClearControlFOV 

ClearControlFOV(data_path: StrOrBytesPath, missing_value: int | None = None, cache: bool = False)

Bases: BaseFOV

Reader class for Clear Control dataset

https://github.com/royerlab/opensimview.

It provides an array-like API for the Clear Control dataset thats loads the volumes lazily.

It assumes the channels and volumes have the same shape, when that is not the case the minimum value from each dimension is used.

Parameters:

  • data_path (StrOrBytesPath) –

    Clear Control dataset path.

  • missing_value (Optional[int], default: None ) –

    If provided this class won't raise an error when missing a volume and it will return an array with the provided value.

  • cache (bool, default: False ) –

    When true caches the last array using the first two indices as key.

shape property 

shape: tuple[int, int, int, int, int]

Reads Clear Control index data of every data and returns

the element-wise minimum shape.

channel_names property 

channel_names: list[str]

Return sorted channels name.

scale property 

scale: list[float]

Dataset temporal, channel and spacial scales.

zyx_scale property 

zyx_scale: tuple[float, float, float]

Helper function for FOV spatial scale (micrometer).

t_scale property 

t_scale: float

Helper function for FOV time scale (seconds).

__getitem__ 

__getitem__(key: ArrayIndex | tuple[ArrayIndex, ...]) -> np.ndarray

Lazily load array as indexed.

Parameters:

  • key (ArrayIndex | tuple[ArrayIndex, ...]) –

    An indexing key as in numpy, but a bit more limited.

Returns:

  • ndarray –

    Output array.

Raises:

  • NotImplementedError –

    Not all numpy array of indexing are implemented.

metadata 

metadata() -> dict[str, Any]

Summarizes Clear Control metadata into a dictionary.

channel_index 

channel_index(key: str) -> int

Return index of given channel.