Skip to content

v2 fix 1 (per-well): directional UMI collapsing per (well, barcode) - #18

Merged
bnemoz merged 2 commits into
mainfrom
v2/umi-collapse-perwell
Nov 18, 2026
Merged

bnemoz merged 2 commits into
mainfrom
v2/umi-collapse-perwell

Conversation

@bnemoz

@bnemoz bnemoz commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

What

Fix 1, UMI error correction, per-well scope: UMIs are collapsed within each (well, droplet barcode), before any UMI counting, using the UMI-tools directional adjacency method.

  • New pairplex/umi.py:collapse_umis_directional(umis, counts=None) -> {raw: representative}.
    • Directed edge a -> b when Hamming(a, b) == 1 and count(a) >= 2*count(b) - 1 (count = reads per raw UMI).
    • UMIs are visited in descending count (ties broken by UMI string, so results are deterministic). Absorption is transitive along directed edges, first come first served, as in UMI-tools.
    • Uses neighbour generation (single substitutions over ACGTN, so 40 per 10-mer). Cost is linear in distinct UMIs; a 3,000-molecule barcode takes milliseconds.
    • UMIs with N: N counts as a mismatch. An N-containing UMI never absorbs anything, because it is Hamming-1 from up to four real UMIs and so is no evidence for any one of them. It can be absorbed by an N-free UMI at Hamming 1 that satisfies the count rule. If no such parent exists, it stays its own UMI. UMIs of unequal length (short reads) are never compared.
  • process_droplet(..., umi_collapse="directional") collapses the partition before clustering.
    • Each read keeps its raw UMI in umi_raw, and umi becomes the representative.
    • Metadata: umis is the corrected count, and a new umis_raw column (after umis) holds the count before collapsing.
    • min_cluster_umis filters on corrected counts.
  • run(..., umi_collapse="directional" | "none", legacy=False), CLI --umi-collapse, --legacy.
    • legacy=True forces "none".
    • "none" is exactly the v2-base code path, with no umis_raw column.
    • The effective value is written to the run log as umi_collapse_effective.

Why in process_droplet rather than run()

  • partition_df is by construction exactly one (well, barcode) group, which is the scope the spec asks for.
  • Doing the work there runs it in the existing process pool, in parallel across barcodes, with no extra serial pass over the whole well in the parent.
  • Barcodes dropped earlier by the min_cluster_reads partition filter never produce metadata, so skipping them loses nothing.
  • Trade-off: parsed/<well>.parquet still holds the raw UMIs only. That file is the raw parse, and the corrected UMI can be recomputed from it.

Tests (pairplex/tests/test_umi.py, 56 passed with the existing suite)

  • Classic cases:
    • singleton and empty input;
    • the count-rule boundary (5 vs 3 absorbs, 5 vs 4 does not);
    • Hamming 2 is not absorbed;
    • a chain a -> b -> c (c is 2 substitutions from a, absorbed through b), and a chain broken by the count rule;
    • ties (1/1 merge deterministically, 3/3 do not);
    • a UMI-tools-paper-style network;
    • a node reachable from two roots goes to the first one.
  • N handling and unequal lengths.
  • The three API forms agree.
  • 20 random networks match an O(n²) reference written the UMI-tools way (full adjacency list plus BFS components).
  • Speed on a 3,000-molecule barcode.
  • Integration through process_droplet:
    • corrected and raw counts;
    • min_cluster_umis=2 now rejects a 1-molecule light chain that had 3 raw UMIs;
    • "none" gives the v2-base column layout.
  • run(legacy=True, umi_collapse="directional") uses "none", and an invalid value raises.

Legacy equivalence (2-well SimPlex smoke)

  • v2-base is not byte-deterministic against itself.
    • run() collects process_droplet futures with as_completed, so the row order of metadata/*.csv, consensus/*.fasta and annotated/* changes from run to run.
    • Two v2-base runs differ bytewise on every file.
  • I therefore compared outputs with rows sorted:
comparison metadata consensus annotated (parquet + tsv)
v2-base vs v2-base bytes DIFF, canonical SAME bytes DIFF, canonical SAME bytes DIFF, canonical SAME
v2-base vs legacy=True bytes DIFF, canonical SAME bytes DIFF, canonical SAME bytes DIFF, canonical SAME
v2-base vs default canonical DIFF (umis, new umis_raw) canonical SAME canonical SAME
  • On these 2 wells, collapsing reduces summed UMIs from 2,072 to 1,880 (−9.3%) and lowers umis in 9.1% of contigs.
  • Contigs passing filters with ≥2 UMIs drop from 190 (raw) to 37 (corrected).

Benchmark

Acceptance run: A1pw-directional-v1 (default) vs v2-base: OVERALL PASS

[SAME] sim_cal / per_well
   precision            0.593 ->      0.593
   cell_recall          0.126 ->      0.126
   emitted               1413 ->       1413
[PASS] sim_cal / pooled
   precision            0.627 ->      0.634
   cell_recall          0.152 ->      0.153
   emitted               1585 ->       1586
   n_conf0.9               41 ->          8
   prec_conf0.9         0.878 ->      1.000
[SAME] sim_imp / per_well
   precision            0.865 ->      0.865
   cell_recall          0.199 ->      0.199
   emitted               1632 ->       1632
[PASS] sim_imp / pooled
   precision            0.967 ->      0.967
   cell_recall          0.871 ->      0.871
   emitted               6368 ->       6369
   n_conf0.9             4387 ->       4334
   prec_conf0.9         0.987 ->      0.987
runtime: 17386s -> 19799s (PASS, limit 1.5x)
real set verdict clonal purity delta
real_d02 / per_well PASS +0.0 pt
real_d02 / pooled PASS +0.1 pt
real_d07 / per_well PASS +0.0 pt
real_d07 / pooled PASS +0.2 pt

Lineage retention: PASS on all 4 real sets.

  • No lineages were lost.
  • Per-well: cells recovered 1.000, coherence unchanged (≤0.0004).
  • Pooled: cells recovered 0.94–0.97, with coherence up slightly (+0.002 to +0.006).

As expected, per-well pairing is unchanged at min_cluster_umis=1. The "PASS" on sim pooled rests on a +0.001 cell-recall change, so in practice this PR is neutral for pairing.

Side effect on pooled confidences.

  • Pooled pairing builds its home-well posterior from umis. Without the inflated counts from error copies, there is less evidence per well, and pairs at confidence ≥0.9 fall:
    • sim_cal: 41 → 8 (precision of those pairs 0.878 → 1.000);
    • sim_imp: 4387 → 4334;
    • both real sets: a large drop.
  • Raw counts made the old confidences overconfident (sim_cal precision at ≥0.9 was 0.878). The confidence model may need recalibrating for honest counts, which belongs to the pooled-pairing lane.

Informational: A1pw-directional-mcu2-v1 ({"min_cluster_umis": 2}) vs v2-base: OVERALL FAIL (not the acceptance run)

[FAIL] sim_cal / per_well
   precision            0.593 ->      1.000
   cell_recall          0.126 ->      0.003
   emitted               1413 ->         17
[FAIL] sim_cal / pooled
   precision            0.627 ->      1.000
   cell_recall          0.152 ->      0.003
   emitted               1585 ->         17
   n_conf0.9               41 ->         16
   prec_conf0.9         0.878 ->      1.000
[PASS] sim_imp / per_well
   precision            0.865 ->      0.994
   cell_recall          0.199 ->      0.397
   emitted               1632 ->       2820
[FAIL] sim_imp / pooled
   precision            0.967 ->      0.988
   cell_recall          0.871 ->      0.535
   emitted               6368 ->       3825
   n_conf0.9             4387 ->       3813
   prec_conf0.9         0.987 ->      0.988
runtime: 17386s -> 9184s (PASS, limit 1.5x)
real set verdict clonal purity delta
real_d02 / per_well PASS +39.0 pt
real_d02 / pooled PASS +10.8 pt
real_d07 / per_well PASS +31.1 pt
real_d07 / pooled PASS +16.5 pt

Lineage retention: REVIEW on all 4 real sets.

  • Only about 8–11% of the cells in baseline expanded clones (≥3, ≥5 and ≥10 cells) are recovered, and many lineages of ≥5 cells are lost entirely.
  • Light-chain coherence rises by +0.17 to +0.31.
  • The loss is the same across clone sizes, so the filter is removing nearly everything rather than picking out ambient pseudo-lineages. This fits most real chains having a single molecule per droplet barcode per well: once the error copies are collapsed, the 2-UMI filter removes them (not checked directly on the real data).
  • The higher purity mostly reflects the much smaller and more selective set of pairs, not better pairing.
  • On sim_cal (the measured regime), cell recall falls to 0.003. On sim_imp, per-well recall doubles but pooled recall falls by 34 points.
  • Verdict: with honest counts, min_cluster_umis=2 is too aggressive to use as a default. The default stays min_cluster_umis=1.
  • The lost-lineage list (clone identifiers and sizes) comes from real donor data. It is in the harness compare output and is left out of this public PR.

Open points

  • v2-base output row order is nondeterministic (as_completed). Sorting metadata/consensus by name would make outputs byte-reproducible, but it would also change the legacy bytes, so it belongs in a separate PR.
  • It would help to compare {"legacy": true, "min_cluster_umis": 2} with the mcu2 run above, to separate the effect of honest counts from the effect of the filter itself. That needs a sims-only run and was not done here.

🤖 Generated with Claude Code

bnemoz and others added 2 commits November 17, 2026 16:18
Adds pairplex/umi.py:collapse_umis_directional (UMI-tools directional adjacency,
neighbour generation, N-containing UMIs absorbed but never absorbing). process_droplet
collapses UMIs per droplet partition: umi_raw keeps the raw UMI, metadata umis is the
corrected count and umis_raw the raw count; min_cluster_umis filters on corrected counts.

run(umi_collapse='directional'|'none'), CLI --umi-collapse; run(legacy=True) / --legacy
forces 'none' (v2-base behaviour).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…x/barcode_prefer_exact alongside umi_collapse; legacy forces all)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bnemoz added a commit that referenced this pull request Nov 18, 2026
… all v2 options; abstar always gets an explicit mmseqs_threads)

Stacked on #18 (v2/umi-collapse-perwell): merge #18 first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bnemoz
bnemoz merged commit 2e05898 into main Nov 18, 2026
8 checks passed
bnemoz added a commit that referenced this pull request Nov 18, 2026
- one legacy flag forcing every v2 option (now also pairing='exact')
- qc chain-composition counts taken before the pairing rule; emitted_pairs from pair_well
- umis:0/1 keep #19's meaning (the contig's own UMI count); the ranking support summed over
  merged same-clonotype contigs moves to chain_umis:0/1 (also in pairs/pairs.parquet)

Stacked on #19 (which is stacked on #18): merge #18, then #19, then this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bnemoz added a commit that referenced this pull request Nov 18, 2026
legacy also forces pooling='per_well'; the per-well-only options (umi_collapse, pairing,
min_dominance, collapse_clonal, support_columns, qc) are documented as not applying in
cross-well mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant