mantispy brings Cell Painting and other image-based profiling data into the scverse ecosystem, from reading what a pipeline wrote through quality control, normalization and batch correction to evaluating what survived. It is for biologists and computational scientists who analyze Cell Painting or similar image-based screens in Python. mantispy is in alpha: the API may still change.

import mantispy as mt
import scanpy as sc

cells = mt.io.read_profiles("analysis/", platemap="platemap.csv")  # an ExportToSpreadsheet directory, or profile files
mt.pp.annotate_controls(cells)  # assumes the negative control is labeled "DMSO"; see negcon= for other names
mt.pp.image_qc(cells)  # which fields were out of focus
mt.pp.normalize(cells, by="Metadata_Plate", reference="negcon")  # robust MAD against the negative controls
wells = mt.tl.aggregate(cells)  # cells -> wells

mt.pp.feature_select(wells)  # flags features in var["selected"]
wells = mt.pp.subset_features(wells)  # keeps only those
sc.pp.pca(wells, n_comps=20)  # hit calling reads distances on a PCA, as the covariance of all features is singular
mt.tl.hit_calling(wells, use_rep="X_pca")  # which perturbations moved
mt.pl.hits(wells)

pp prepares, tl computes, pl plots, metrics evaluates a correction, io reads and writes, and ds downloads public screens. Everything operates on an AnnData, so scanpy's PCA, neighbors, UMAP and Leiden work on the same object. io.read_plate reads the images behind the profiles as SpatialData.

To start, From a CellProfiler run shows how to read a screen and Hits, effects and cell loss how to call hits on it. Neither needs your own data, and mt.ds.bbbc021() downloads a public screen.

Set mt.settings.verbosity = 2 when you first run your own screen. Several steps drop features or wells, and they log it at that level.

Please refer to the documentation, in particular the API documentation.

Installation

You need to have Python 3.12 or newer installed on your system. If you don't have Python installed, we recommend installing uv.

We recommend managing dependencies in project-specific virtual environments to avoid dependency conflicts. This is most convenient using package managers such as uv. Choose from the options below to install mantispy:

1. Install the latest release from PyPI. The current release is an alpha pre-release, so pip needs --pre:

   pip install --pre mantispy  # (or `uv add --prerelease allow mantispy`)

2. Install the latest development version:

   pip install git+https://github.com/scverse/mantispy.git  # (or `uv add`)

Reading images needs the spatial extra:

pip install 'mantispy[spatial]'

Release notes

See the changelog.

Contact

For questions and help requests, you can reach out in the scverse discourse. If you found a bug, please use the issue tracker.

License

mantispy is released under the BSD 3-Clause license.

Citation

A preprint describing mantispy is in preparation. Until then, cite the repository directly.