MitoSim

A forward simulator of mitotic figures in histological sections, built to answer one question:

For each "atypical mitotic figure" category in the guidelines, what fraction of cells showing it were actually abnormal — and what fraction is just an artifact of cutting a thin 2D section through a 3D event?

A section is a 3-4 µm slab through a 10-15 µm three-dimensional mitosis, caught at one instant. Several categories pathologists score may be sectioning artifacts rather than true chromosome segregation errors — but this can't be settled from real images alone, because real images have no ground truth. MitoSim inverts the problem: generate mitoses whose true state is known by construction (normal, or abnormal by a specific named mechanism), section and image them exactly like a microtome and scanner would, and score the result. See Plan.md for the full design brief this was built from.

What's implemented

Area	Where	Status
Chromosome/spindle geometry, sectioning, voxeliser	mitosim/geometry/, mitosim/render/section.py, mitosim/render/voxelize.py	done, validated (V1-V3)
Five mitotic phases, three karyotypes (human/dog/cat)	mitosim/phases/, mitosim/geometry/karyotype.py	done
Abnormality mechanisms + confounders	mitosim/abnormal/	done
Beer-Lambert optical forward model (PSF, HE colour, noise)	mitosim/render/optics.py	done
Rule-based morphological scorer	mitosim/score/classify.py	done, but a known-weak baseline — see caveat below
Population experiment harness (E1-E6 + V6)	mitosim/experiments/	done
Labelled image-dataset export (for training a real classifier)	mitosim/score/export.py	done
Interactive 3D/sectioning explorer	webapp/	done (local only)
Morphometric calibration against real patches (V4), pathologist face-validity (V5)	mitosim/calibrate/	not done — needs real patches and expert time this environment doesn't have
Pathologist-panel export, E7/E8 human/model-in-the-loop harness	—	not done

Install

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

or, for editable development install with test/webapp extras:

.venv/bin/pip install -e ".[dev,webapp]"

Requires Python ≥3.10. Core dependencies are just numpy, scipy, and matplotlib — deliberately dependency-light so it runs on a laptop.

Run the tests

.venv/bin/pytest

113 tests, covering the analytic regression checks (V1-V3), phase/ abnormality/optics unit tests, the containment and classifier regression suites, and the population harness — including a couple of tests that pin down genuinely surprising simulator behaviour (see tests/test_m5_harness.py's docstring on trailing-arm bridging).

Run an experiment

.venv/bin/python -m mitosim.experiments.ppv          # E1: PPV table + confusion matrix
.venv/bin/python -m mitosim.experiments.v6_population_check
.venv/bin/python -m mitosim.experiments.ring          # E2
.venv/bin/python -m mitosim.experiments.asymmetry     # E3
.venv/bin/python -m mitosim.experiments.lagging       # E4
.venv/bin/python -m mitosim.experiments.multipolarity # E5
.venv/bin/python -m mitosim.experiments.recovery      # E6

Each writes results/<name>/summary.json (+ population.csv where applicable) — gitignored, regenerate on demand.

Export a labelled image dataset

For training or evaluating a real (e.g. deep-learning) classifier against simulated ground truth, instead of relying on the rule-based scorer:

.venv/bin/python -m mitosim.score.export --n 2000 --out results/dataset --workers 8

Renders each cell through the full Beer-Lambert optical model and writes 128×128px HE-like patches plus a manifest.csv of ground-truth labels (mechanism, phase, tilt, offset, thickness, train/val/test split). See the module docstring in mitosim/score/export.py for the full schema and rationale.

Interactive explorer

A local Flask app for building 3D intuition about sectioning — orbit a real simulated cell (any phase, or any injected abnormality), drag the slicing plane through it, and see both an instant approximate preview and a real optics-pipeline render side by side.

.venv/bin/pip install -e ".[webapp]"
.venv/bin/python webapp/server.py

Then open http://127.0.0.1:5050. See webapp/README.md for what's on the page and its endpoints.

Documentation

• Plan.md — the original implementation plan and design rationale (read-only reference; not updated as the code evolves).
• docs/conventions.md — coordinate frame and units conventions used throughout.
• docs/validation.md — V1-V4 validation results.

Caveat

Every optical constant (extinction coefficients, background nucleus density, noise level) and every classifier threshold in this codebase is an undated placeholder pending calibration against real patches (V4), which this environment doesn't have. What this simulator produces is what sectioning geometry can produce from known-correct 3D ground truth — not yet what real tissue does present. Treat any number it produces as a first-pass simulator estimate, not a validated clinical claim.