mantispy.io.read_profiles#

mantispy.io.read_profiles(paths, metadata_prefixes=('Image_Metadata_', 'Metadata_', 'metadata_', 'meta_'), metadata_columns=(), index_columns=None, channels=None, sentinels=None, keep_non_features=False, objects=('Cells', 'Cytoplasm', 'Nuclei'), on_column_mismatch='raise', path_columns=None, platemap=None, primary_object='Cells', strict_one_to_one=True, resolution=None, grouped_by=None)[source]#

Read profiles into an AnnData of observations by features.

What paths points at decides how it is read:

  • one or more CSV, TSV or parquet files, stacked row-wise;

  • a directory an ExportToSpreadsheet run wrote, one row per primary_object with every other object joined onto it through the Parent_ column that links the two, and the MeasureImageQuality columns of Image.csv kept in uns["mantispy"]["image_table"];

  • a directory of parquet parts, as CytoTable writes them.

Numeric columns that parse as CellProfiler features become X. Text and Metadata_ columns become obs, with every metadata prefix normalized to Metadata_. Numeric columns that follow no CellProfiler naming (a learned embedding, a proprietary feature table) are kept as features with feature_kind="embedding". Numeric columns that parse as non-features (object numbers, parent links, centroids) are dropped and logged, because published profile tables often carry dozens of them and they mean nothing at well level.

Parameters:
paths str | Path | Sequence[str | Path]

A file or a directory, or several files to stack.

metadata_prefixes Sequence[str] (default: ('Image_Metadata_', 'Metadata_', 'metadata_', 'meta_'))

Prefixes marking metadata columns. The matching prefix is normalized to Metadata_.

metadata_columns Sequence[str] (default: ())

Columns to treat as metadata even though they are numeric and unprefixed.

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

obs columns, named as they are after the prefix is normalized, joined with : into the observation index. Without them the index is the row number.

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

Channel vocabulary passed to the feature-name parser. Read from the FileName_ columns of an export directory, and inferred from the feature names otherwise.

sentinels float | Collection[float] | None (default: None)

Values in the feature matrix that stand for missing, replaced with NaN.

keep_non_features bool (default: False)

Keep the numeric columns that do not parse as features in obs instead.

objects Sequence[str] | None (default: ('Cells', 'Cytoplasm', 'Nuclei'))

Which CellProfiler objects count as features, and for an export directory which object tables are read. The default is the three compartments, matching pycytominer.infer_cp_features. None keeps every object, including the whole-field Image measurements.

on_column_mismatch Literal['raise', 'intersect'] (default: 'raise')

"raise", or "intersect" to keep the shared columns in the first file’s order. Batches with disjoint feature sets do occur.

path_columns Mapping[str, int] | None (default: None)

Metadata read from the path: maps a column name to how many directories up to take the name of, counting the directory holding a file, or a directory that was given, as 1.

platemap str | Path | DataFrame | None (default: None)

A table, or a path to one, with a Metadata_Well column and optionally Metadata_Plate, left-joined onto obs.

primary_object str (default: 'Cells')

For an export directory, the object one row of the result is.

strict_one_to_one bool (default: True)

For an export directory, raise when another object does not match the primary object exactly once. False keeps the first match.

resolution str | None (default: None)

Resolution to record, "object" for a directory and "well" for files when omitted. The 1.0 names "cell" and "perturbation" are read as "object" and "aggregate".

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

For "aggregate" resolution, the obs columns that define one row; required there.

Return type:

AnnData

Returns:

An AnnData at the recorded resolution, with the parsed feature annotation in var, the metadata in obs with pycytominer’s per-well counts copied to Metadata_CellCount and Metadata_SiteCount, and the schema stamp, the resolution, the channel vocabulary, this call’s parameters and, from an export directory, the per-image quality table under uns["mantispy"].

Raises:

  • ValueError – No paths were given, on_column_mismatch is not one of the two accepted values, a directory was given together with other paths, the files disagree on columns while on_column_mismatch is "raise", a file holds a header and no rows, no column parses as a feature on objects, index_columns do not identify observations uniquely, the platemap repeats a well, or an export object cannot be linked one to one.

  • FileNotFoundError – A directory holds neither an Image.csv nor parquet parts, or has no table for primary_object.

  • KeyError – A name in metadata_columns or index_columns is not in the data.

Examples

>>> import mantispy as mt
>>> wells = mt.io.read_profiles("BR00116991_augmented.csv.gz", sentinels=-999)
>>> cells = mt.io.read_profiles("analysis/", platemap="platemap.csv")