kcells finds the individual cells in microscopy images with the Cellpose cyto3 deep-learning model, describes every cell with a user-selected set of features, clusters all cells (from one or several images) into K groups, and ranks every cell by how unusual it is. Each cell is outlined on the original image in the colour of its cluster, and the most unusual cells are marked with their rank.
You should adapt and run the following command:
docker run --rm --user "$(id -u):$(id -g)" -v "/your/data/dir/input_folder:/app/input:ro" -v "/your/data/dir/results_folder:/app/output" pegi3s/kcells --input /app/input --output-dir /app/output --cellpose-diameter celldia --border-cells bcells --cluster-method cmethod --k nk --features feat --n-unusual nunusual
In this command, you should replace:
/your/data/dir (twice) with the path to the working directory that contains your folder with the input images. Results are written in the working folder too.celldia by the typical cell diameter in pixels for Cellpose. If you leave as auto it will be estimated from the pictures.bcells by include or exclude. This will include or exclude the incomplete cells at the image borders.cmethod by the clustering method (either ward (hierarchical; lets a small, distinct group form its own cluster), kmeans, or gmm (Gaussian mixture; clusters may differ in spread))nk by the number of cell clustersfeat by the features to consider (valid features are a comma-separated combination of shape, color, texture, gradient, density, chromatin, or all, for instance texture,gradient,chromatin)nunusual by the number of most unusual cells to mark on the images.results/
├── annotated/<image>.png # original image; every clustered cell outlined in
│ # its cluster colour; the most unusual cells marked
│ # with their rank (1 = most unusual); cells not
│ # clustered (edge / no nucleus / irregular) in thin grey
├── cells.csv # one row per cell: image, cell id, status
│ # (clustered / edge / no nucleus / irregular),
│ # cluster, unusualness, unusual rank, centroid,
│ # cell and nucleus area, fragments, edge flag,
│ # cell-likeness, every feature
└── summary.txt # cells per cluster per image, the most distinctive
# features of each cluster, and the most unusual
# cells with the features that make them unusual
Cluster numbers are arbitrary: cluster 0 in one run is unrelated to cluster 0 in another run.
Terms used below:
OD = −log(pixel brightness / brightness of an unstained area). 0 means no stain; the darker the pixel, the higher its OD.cells.csv (each prefixed with
the group name, e.g. shape.nuc_circularity).shape: geometry of the nucleus and the cell (18 features)Eight shape measurements are made on the nucleus (columns nuc_…) and the
same eight on the whole cell outline (columns cell_…):
rel_log_area): area divided by the median area of
the image's nuclei (or cells), as a logarithm. 0 = typical size;
positive = larger, negative = smaller.circularity): 4π × area / perimeter². 1 for a
perfect circle, lower for irregular or ragged outlines.solidity): area divided by the area of its convex hull
(the smallest outline without inward dents). 1 for any convex shape
(circle, ellipse, rectangle), lower for notched or lobed shapes.eccentricity): of the ellipse with the same spread
as the shape. 0 = circle, close to 1 = very stretched.elongation): length divided by width of the smallest
rotated rectangle enclosing the shape, as a logarithm. 0 = as long as
wide.extent): area divided by the area of the horizontal/vertical
bounding box. Lower for diagonal or irregular shapes.hu1, hu2): two standard numbers
describing how the area is distributed around its centre, independent of
position, size and rotation. Hu moment 1 is smallest for a disc and grows
as the shape becomes elongated or irregular; Hu moment 2 is 0 for a disc
or square and grows as the shape becomes elongated. They are stored as
−log10(value), so a larger moment gives a smaller number (and a
perfect disc gives a very large hu2).Plus two features about the content of the cell:
nucleus_to_cell_area): nucleus area divided
by cell area.log_n_fragments): separate stained
pieces in the cell, as log(1 + number). One for an interphase nucleus,
several for the chromosomes of a dividing cell.color: raw colour (8 features)Colours are measured in the CIE-Lab colour space, which separates brightness from colour: L* = lightness (0 black to 100 white), a* = green (negative) to red/magenta (positive), b* = blue (negative) to yellow (positive).
nuc_L, nuc_a, nuc_b).nuc_L_std): standard deviation of L*
inside the nucleus.cyto_L, cyto_a, cyto_b).nuc_cyto_deltaE): the distance
between their mean colours in Lab space (known as ΔE; about 2 is the
smallest difference a person notices).These depend directly on the stain, the illumination and the camera's white balance.
texture: chromatin pattern inside the nucleus (7 features)Measured on the stain image, inside the nucleus only.
Four features compare each pixel with the pixels 1 and 2 pixels away, in four directions (averaged), after reducing the stain image to 16 grey levels (a "grey-level co-occurrence matrix", GLCM):
glcm_contrast): how different neighbouring pixels are.
High for coarse, high-contrast chromatin.glcm_homogeneity): how similar neighbouring pixels
are. High for smooth chromatin.glcm_energy): how few distinct neighbour combinations occur.
High for uniform areas or simple, repetitive patterns.glcm_correlation): how predictable a pixel is from its
neighbour. High when the pattern is made of large blobs rather than fine
grain.Three features look at the 8 pixels immediately around each pixel and classify the local pattern ("local binary patterns", LBP):
lbp_entropy): how varied the local patterns are,
as an entropy. High for complex, granular texture.lbp_flat): share of pixels whose neighbours are
all darker or all lighter than (or equal to) them: flat areas and isolated
spots.lbp_edge): share of pixels with about half their
neighbours lighter and half darker: pixels on an edge between light and
dark, such as the border of a chromosome.gradient: local edges and their directions (6 features)The gradient at a pixel is how fast the stain image changes there (its strength) and in which direction. Measured after slight smoothing.
nuc_grad_mean).nuc_grad_std): standard
deviation.nuc_orient_coherence): 0 when the edges in the
nucleus point in all directions, 1 when they all point the same way.
High when chromosomes are aligned (e.g. metaphase, anaphase).nuc_orient_entropy): how evenly the edge
directions are spread over 8 direction classes (weighted by edge
strength), from 0 (one direction) to 1 (all directions equally). Low when
chromosomes are aligned.cell_grad_mean).nuc_border_sharpness): mean edge
strength along the outline of the nucleus. High for a crisp border, low
for a blurred one.density: how much stain the nucleus holds (6 features)Based on optical density (OD, see above).
nuc_mean_od).nuc_p90_od): the 90th percentile, i.e. the
value that 10% of the nucleus pixels exceed. Reflects the darkest parts.nuc_od_std): standard deviation.nuc_rel_log_integrated_od):
the sum of OD over all nucleus pixels, divided by that of the median cell
of the image, as a logarithm. 0 = typical; log 2 ≈ 0.69 = twice as much
stain. With a stain that binds DNA in proportion to its amount (e.g.
Feulgen), this approximates relative DNA content.cyto_mean_od).nuc_cyto_od_ratio): mean OD of the
nucleus divided by mean OD of the cytoplasm.chromatin: condensation and fragmentation (7 features)Condensed chromatin is the darkest part of the nucleus: inside the nucleus, pixels with OD above a threshold chosen automatically from that nucleus's own OD values (Otsu's method, which splits the values into a darker and a lighter group). It forms one or more separate pieces; in a dividing cell these are the chromosomes.
condensed_fraction): area of condensed chromatin
divided by nucleus area.log_n_pieces): as log(1 + number).largest_piece_fraction): area of the
largest piece divided by the total condensed area. 1 = a single piece;
low = many pieces of similar size.piece_spread): the average distance of
condensed pixels from their common centre (root-mean-square), divided by
the square root of the nucleus area so that it does not depend on nucleus
size.condensed_solidity): condensed
area divided by the area of the convex hull around all pieces. Low when
the pieces are scattered with gaps between them.condensed_contrast): mean OD of the condensed chromatin
divided by mean OD of the rest of the nucleus.condensed_rel_od): mean OD of the condensed
chromatin divided by that of the median cell of the image.Dividing cells typically have many pieces, each a small share of the total, spread out, with high contrast.
If a nucleus has no condensed chromatin, its values are set to: fraction 0, number of pieces 0, largest share 1, spread 0, compactness 1, contrast 1, and relative darkness = its whole-nucleus mean OD relative to the median cell.
texture, gradient and color are sensitive to how the image was taken
(sharpening, focus, resolution, stain, white balance). When images were
taken differently, these groups also separate the images, not only the
cells.
Cell outlines. Cellpose 3,
a generalist cyto3 model, run on the grayscale image on the CPU. It is a
neural network trained on many thousands of hand-outlined cells, so it
closes faint walls and ignores nuclear rims and spindle fibres. The cell
diameter is set with --cellpose-diameter (pixels, or auto to estimate
it per image).
About 5–60 s per image on a CPU, depending on image size.
Stain density. The image is converted to optical density
(OD = −log(I/I₀), I₀ = the image's own bright level), i.e. the amount
of stain per pixel.
Stained content per cell. Inside each cell, the nucleus (or the chromosomes) is separated from the cytoplasm by Otsu's threshold on that cell's own OD values. A cell counts as nucleated only if both:
Empty cells, gaps between cells, out-of-focus nuclei and slivers of a neighbour's nucleus at the image edge are therefore not clustered. A nucleated cell whose outline is not cell-like (solidity < 0.8, i.e. notched or ring-shaped; very elongated outlines, longer than 4:1, also count as less cell-like) is reported as irregular and not clustered.
Condensed chromatin. Inside each stained part, a second, stricter Otsu threshold keeps only the densest chromatin, e.g. the individual chromosomes of a dividing cell without the faint haze between them.
Features for every nucleated cell, from the groups chosen with
--features (see Definitions above).
Clustering and unusualness. Features are standardised, and every selected group gets the same total weight (each feature is divided by √(number of features in its group)). Then:
--cluster-method: Ward, K-Means or Gaussian mixture);--n-unusual most
unusual cells are marked on the images.Output. Every original image with each cell outlined in its cluster colour and the most unusual cells numbered, a per-cell CSV, and a summary.
Content type
Image
Digest
sha256:1b0da8984…
Size
648.5 MB
Last updated
6 days ago
docker pull pegi3s/kcells