Repository navigation
v2 fix 1 (per-well): directional UMI collapsing per (well, barcode) - #18
Merged
Merged
Conversation
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
- 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
pairplex/umi.py:collapse_umis_directional(umis, counts=None) -> {raw: representative}.a -> bwhen Hamming(a, b) == 1 andcount(a) >= 2*count(b) - 1(count = reads per raw UMI).ACGTN, so 40 per 10-mer). Cost is linear in distinct UMIs; a 3,000-molecule barcode takes milliseconds.N:Ncounts 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.umi_raw, andumibecomes the representative.umisis the corrected count, and a newumis_rawcolumn (afterumis) holds the count before collapsing.min_cluster_umisfilters on corrected counts.run(..., umi_collapse="directional" | "none", legacy=False), CLI--umi-collapse,--legacy.legacy=Trueforces"none"."none"is exactly the v2-base code path, with noumis_rawcolumn.umi_collapse_effective.Why in
process_dropletrather thanrun()partition_dfis by construction exactly one (well, barcode) group, which is the scope the spec asks for.min_cluster_readspartition filter never produce metadata, so skipping them loses nothing.parsed/<well>.parquetstill 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)a -> b -> c(c is 2 substitutions from a, absorbed through b), and a chain broken by the count rule;process_droplet:min_cluster_umis=2now 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)
run()collectsprocess_dropletfutures withas_completed, so the row order ofmetadata/*.csv,consensus/*.fastaandannotated/*changes from run to run.legacy=Trueumis, newumis_raw)umisin 9.1% of contigs.Benchmark
Acceptance run:
A1pw-directional-v1(default) vsv2-base: OVERALL PASSLineage retention: PASS on all 4 real sets.
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.
umis. Without the inflated counts from error copies, there is less evidence per well, and pairs at confidence ≥0.9 fall:Informational:
A1pw-directional-mcu2-v1({"min_cluster_umis": 2}) vsv2-base: OVERALL FAIL (not the acceptance run)Lineage retention: REVIEW on all 4 real sets.
min_cluster_umis=2is too aggressive to use as a default. The default staysmin_cluster_umis=1.Open points
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.{"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