solo: --soloCellFilter OrdMag, CellRanger's cell call (first item of #181, stacked on #180)

[BenjaminDEMAILLE]

Stacked on #179 → #178 → #176 → #175 → #174 → #173. Merge in that order. (Rebased off #180 after it was closed; nothing here depended on it.)

First item out of the GEX coverage map in #181, and the one that was fully specified with no ambiguity.

What CellRanger does, and what we did

STARsolo's CellRanger2.2 takes the 99th percentile of the top 3 000 barcodes by UMI count and calls everything holding at least a tenth of it. The 3 000 is a fixed guess at how many cells the run has.

CellRanger uses the same rule but searches for that number: it minimises (OrdMag(x) − x)² / x over x from 2 to about 45 000, where OrdMag(x) is the number of cells the rule calls when told to expect x of them. The loss is small where the rule predicts itself — feed it the right cell count and it gives that count back.

This adds --soloCellFilter OrdMag maxExpectedCells quantile ratio (default 45000 0.99 10), and makes EmptyDrops_CR use it for the initial cell set it guarantees before the Monte-Carlo rescue, which is the order CellRanger runs the two steps in. CellRanger2.2 is untouched and stays the default, so nothing changes for anyone not asking.

Two things the page does not specify

Both are decisions, so they are in the code and in DIVERGENCE.md §3.6 rather than left implicit:

• Every integer in range is evaluated, not a geometric grid refined by search. Each evaluation is a binary search over the sorted totals, so an exhaustive sweep of 45 000 candidates costs nothing measurable and finds the true minimum of the stated loss instead of a grid point near it.
• Ties go to the smaller x, so the result does not depend on iteration order.

What this measures, honestly

On the fixture it changes nothing. All three call 200 cells, and so does CellRanger 10.0.0:

method	cells called
CellRanger2.2 (default)	200
OrdMag	200
EmptyDrops_CR	200
CellRanger 10.0.0	200

That is not a null result dressed up as a win: the 20 000-read fixture has a clean 200-cell plateau over a flat ambient tail, and any of these rules gets it right. The fixed guess and the search part company on a graded distribution with no plateau, which is exactly the case real data presents and which the fixture does not have. That case is covered by the unit tests rather than by a measurement I cannot make on this data, and I would rather say so than imply the fixture demonstrates something it does not.

Building a fixture with a graded UMI distribution belongs with the fixture work in #172.

Verification

• ordmag_finds_the_self_consistent_cell_count — the loss is zero at the true cell count, and the cutoff is a tenth of the plateau
• ordmag_and_the_fixed_knee_disagree_on_a_graded_distribution — 10 000 barcodes falling geometrically: the search does not reproduce the fixed guess, and the count it calls is self-consistent with what it was solving for
• ordmag_beats_a_fixed_expected_cell_count_when_the_guess_is_wrong — 20 000 cells against a hardcoded 3 000; on a flat population they agree, which the test asserts rather than hides
• ordmag_handles_empty_and_tiny_inputs — empty slice, zero expected count, a single barcode, and the cutoff never dropping below 1

Gate: 576 lib + 26 integration tests, cargo clippy --all-targets -- -D warnings, cargo fmt --check, cargo +1.89 check --all-targets, all green.

Not in this PR

Making OrdMag and EmptyDrops_CR the defaults on 10x geometry is a two-line addition to CELLRANGER_DEFAULTS in #176. It is a further change to default output, so it belongs with the sign-off on #176 rather than smuggled in here; say the word and I will add it there.

[BenjaminDEMAILLE]

Measured on real human data, and it does not support this PR

I ran the comparison 10x's own PBMC 1k v3 dataset (20 M read pairs of the public pbmc_1k_v3, refdata-gex-GRCh38-2024-A on both sides, cellranger count 10.0.0 against this stack plus #165). The yeast fixture could not discriminate between cell-calling rules — every method returned 200 cells, as I said in the description. Human data does discriminate:

cell caller	cells called
CellRanger 10.0.0	1 178
rustar EmptyDrops_CR, without this PR (2.2 knee initial set)	1 178
rustar EmptyDrops_CR, with this PR (OrdMag initial set)	1 177
rustar CellRanger2.2	1 145
rustar OrdMag alone	1 133

Without this PR, EmptyDrops_CR reproduces CellRanger exactly. With it, it is one cell off. The change I argued for on the strength of 10x's documentation makes agreement marginally worse on the one real dataset I have.

I am not going to dress that up. Two readings are available and I cannot separate them with one dataset:

• One cell in 1 178 is noise, and the OrdMag search is still the more faithful implementation of what 10x describes.
• CellRanger's actual cell caller differs in some detail from the prose on its algorithm page, and the 2.2 knee happens to sit closer to it.

What is not available is the reading I implied when I opened this: that implementing the documented search gets us closer to CellRanger. It does not, here.

The unit tests still stand — the search does what 10x describes, ties are deterministic, and the degenerate cases are handled. CellRanger2.2 remains the default, so nothing changes for anyone not asking. But if you would rather not carry a change whose only demonstrated effect is one cell in the wrong direction, closing this is a reasonable call and I will not argue it.

If you want it kept, the thing that would settle it is a second dataset with a different cell-count regime. I would rather run that than defend this on the documentation alone.