mantispy.io.read_profiles

Contents

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)#

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 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, of which a JUMP profile has 1089 against 3634 per-cell ones.

  • 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, "cell" for a directory and "well" for files when omitted.

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")
Contents