cell-morphology-analysis

A small, tested toolkit for turning segmented cell images into morphology features and then sorting those cells by phenotype. The same kind of readout shows up in high content screening: you start from masks, you measure shape and brightness per cell, and you score how healthy each cell looks.

Everything runs on CPU. The test data is synthetic, built from disks and ellipses whose true area, perimeter, and eccentricity are known in closed form, so the feature extractor can be checked against ground truth rather than against itself.

What it does

1. Synthetic cells (src/synthetic.py). Build binary masks and matching intensity images for disks and ellipses, or compose several cells into one labelled field. Because the geometry is exact, these double as a test oracle.

2. Feature extraction (src/features.py). For every labelled cell, pull out area, perimeter, eccentricity, equivalent diameter, solidity, extent, and isoperimetric circularity, plus intensity statistics (mean, standard deviation, min, max, integrated signal). Shape work leans on scikit-image region properties; the derived ratios are computed directly.

3. Phenotype analysis (src/phenotype.py).

   • PhenotypeClassifier standardises the features and fits a random forest to separate phenotypes from labelled examples.
   • cluster_phenotypes groups cells with KMeans when no labels are available.
   • viability_score blends brightness, roundness, size, and shape regularity into a single number in [0, 1], a stand in for the per cell health call a screen would report.

Layout

src/        synthetic data, feature extraction, phenotype models
tests/      pytest checks on geometry and phenotype behaviour

Install

python -m pip install -r requirements.txt

Run the tests

python -m pytest tests/ -q

The geometry tests assert that the measured disk area lands within one percent of pi r squared, the ellipse area within one percent of pi a b, and the recovered eccentricity within 0.02 of the analytic value. The perimeter of a rasterised circle carries a few percent bias from the discrete grid, so that check uses a wider band. The phenotype tests build two visibly different populations (large bright round cells versus small dim elongated cells) and require the classifier to clear chance on a held out split, the clustering to recover the two groups, and the viability score to rank a healthy cell above a stressed one while staying inside [0, 1].

A quick look

import numpy as np
from src.synthetic import make_cell_field
from src.features import extract_features
from src.phenotype import viability_score

label_img, intensity_img = make_cell_field(
    [{"kind": "disk", "radius": 22, "center": (40, 40), "mean_intensity": 0.8}],
)
row = extract_features(label_img, intensity_img)[0]
print(row["area"], row["circularity"], viability_score(row))

Notes

The classifier and the clustering both standardise features first, which matters because area and intensity live on very different scales. Region perimeter uses the four connectivity Crofton estimator from scikit-image, the same one behind its region properties, so the perimeter column and the circularity column stay consistent with each other.