blotquant

Western blot quantification is one of the most common measurements in molecular biology and one of the least reproducible: hand-drawn regions, silent saturation, undocumented normalization. Most tools give you a number; almost none tell you whether you should trust it.

A Python CLI, with an HTTP API alongside it, that detects lanes and bands, subtracts background, normalizes against loading controls — and treats quality control as a first-class output. Saturated or unverifiable bands are flagged and still reported, annotated rather than quietly dropped, and their exclusion from a normalization ratio is explicit and recorded with its reason. Every result document carries provenance: image hash, config digest, software version, and whether each lane was found by the pipeline or supplied by the caller.

Development is gated on a seeded synthetic gold set of 40 images with per-band ground truth, split 30 dev and 10 held-out test. On the dev split, band detection measures F1 0.851 at IoU ≥ 0.5, and intensity recovery is 7.05% mean / 4.60% median absolute error on bands carrying no ground-truth QC flag. The headline error over all matched bands is higher, 17.39%, because saturated bands and unresolved doublets are included rather than dropped — both are reported separately and neither is hidden. The test split has never been scored or tuned on, and nothing has been measured on a real blot. 690 tests run in CI, which also re-measures every recorded figure and re-verifies the digest of every frozen document, so a number that goes stale fails the build.

The cross-check against Fiji/ImageJ is pre-registered and its inputs are assembled: 19 CC-BY blot crops from 13 published figures, each committed with its sha256, DOI and licence so the comparison runs on byte-identical files. Agreement thresholds were fixed before any measurement, so interpretation cannot be fitted to the outcome — Spearman r_s ≥ 0.9 is agreement, 0.7 to 0.9 is partial agreement with every discrepant blot individually explained, and below 0.7 the method is not corroborated and that result is published as stated. The comparison runs on normalized ratios rather than absolute intensities, because ImageJ's aperture convention differs and an absolute comparison would measure the conventions instead of the methods. The first real-data run then measured nothing: all 19 crops are three-channel PNGs and the loader quantifies single-channel images only, so it refused all 19 rather than picking a channel the pre-registration forbids choosing. That refusal is the correct behaviour and the honest result — no lane, band or QC flag has ever been produced from a real blot.

The engineering process is part of the point. Each phase runs as an agentic loop in Claude Code: an implementer subagent writes, a reviewer subagent audits the full diff in a fresh context, and a phase is not done until that reviewer returns zero required changes. Standing rules were not enough on their own — one phase ran eight review cycles in which the code converged after three and the written record did not converge at all, because a claim gets fixed where a reviewer happens to read it while its duplicates elsewhere survive. So the claims surface became mechanical: a stdlib-only checker extracts each asserted quantity everywhere it appears and fails CI when two sites disagree, without ever hardcoding the right answer. Decisions live in NOTES.md, known weaknesses in a debt register, and the pipeline may never import from the generator that makes its test data.

In active development. The CLI pipeline, QC, normalization and provenance are merged, as is the HTTP API with caller-supplied lane ROIs. Next: getting a real blot through the loader, then the ImageJ agreement run, and a three-state result status (pass, flagged, blocked) so an image the tool cannot honestly measure is refused with an explanation rather than quantified anyway.