mantispy.io.read_plate

mantispy.io.read_plate(path, plate=None, *, batch=None, layout=None, wells=None, plane=None, profile='normalized_feature_select_negcon_batch', plate_format=384, lazy=True)

Read one plate of images, segmentations and measurements into a SpatialData object.

Two layouts are read, told apart by what sits under path unless layout says which it is.

A Cell Painting Gallery source (layout="gallery", needs batch and plate) gives fields of view as Images, the CellProfiler Nuclei, Cells and Cytoplasm segmentations as Labels, the wells as Shapes, and the wells and cells Tables. The gallery publishes one-pixel outlines, not masks, so the Labels are reconstructed and only unambiguous objects survive. Element names carry the plate barcode, so two plates concatenate without renaming.

A CellProfiler export (layout="cellprofiler") is a folder from the ExportForSpatialData module and is read from the manifest in its table’s uns, so nothing is reconstructed and a folder that was moved still reads.

Where a source recorded stage coordinates and a pixel size, every element sits in three coordinate systems, {plate}_{well}_s{site}, {plate}_{well} and {plate}. Where it did not, each field sits in its own frame. See the tutorial for what each layout publishes and what is dropped.

Parameters:

path Path | str

A Cell Painting Gallery source directory, or an export root or one of its plate folders.

plate str | None (default: None)

Plate barcode. Required for a gallery source; for an export root it picks one of the plate folders, and may be left out when the root holds one.

batch str | None (default: None)

Batch name, the directory below images/ and workspace/analysis/. Gallery sources only.

layout Literal['gallery', 'cellprofiler'] | None (default: None)

Which layout path holds, detected from path when left out.

wells Sequence[str] | None (default: None)

Wells to read images and labels for. Defaults to every well whose images are present under path, so a partial download reads back as itself. The well table always covers the whole plate. Gallery sources only.

plane int | None (default: None)

Which Metadata_PlaneID to read where a source imaged a z stack. Required in that case: no plane is preferable to another, and picking one silently would hide the rest. Gallery sources only.

profile str | Path | None (default: 'normalized_feature_select_negcon_batch')

Variant of the well-level profile, read as workspace/profiles/{batch}/{plate}/{plate}_{profile}.csv.gz. Sources that publish the profile under another name, {plate}.parquet among them, take a Path instead. Pass None to leave out the well table and the well shapes. Gallery sources only.

plate_format int (default: 384)

Number of wells on the plate, used to place the wells on their nominal grid. Gallery sources only.

lazy bool (default: True)

Read arrays through dask instead of loading them into memory. Exports only.

Return type:

SpatialData

Returns:

The plate. A table or element group is left out when nothing it would hold was read.

Raises:

• ValueError – The layout cannot be told from path, an argument does not apply to the layout that was read, the plate mixes pixel sizes, load_data.csv names its images in an unknown way, or an image does not sit in the gallery layout.

• FileNotFoundError – load_data.csv, the requested profile, or the named plate folder is missing.

Examples

Read one plate of a gallery source, images and all:

>>> import mantispy as mt
>>> sdata = mt.io.read_plate(
...     "cpg0000-jump-pilot/source_4",
...     "BR00116991",
...     batch="2020_11_04_CPJUMP1",
... )

Read one well of a plate a source published without a profile of the usual name:

>>> sdata = mt.io.read_plate(
...     "cpg0016-jump/source_1",
...     "UL001641",
...     batch="Batch1_20221004",
...     wells=["A01"],
...     profile=Path("UL001641.parquet"),
...     plate_format=1536,
... )

Read a plate straight out of a pipeline run:

>>> sdata = mt.io.read_plate("run_export/Plate1")