Skip to content

fix(parser): prefer the read orientation with an exact barcode hit - #16

Merged
bnemoz merged 3 commits into
mainfrom
v2/barcode-orientation
Nov 17, 2026
Merged

bnemoz merged 3 commits into
mainfrom
v2/barcode-orientation

Conversation

@bnemoz

@bnemoz bnemoz commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Problem

parse_barcodes tries the forward read first, then its reverse complement, and keeps the first orientation whose 16-nt barcode corrects to the whitelist. A forward barcode that only matches after a Hamming-1 correction therefore wins over a reverse complement that is an exact whitelist hit. That assigns the read to the wrong droplet barcode and the wrong UMI, and it uses the wrong strand as the insert.

Fix

New orientation choice in parse_barcodes(prefer_exact=True) (helper _choose_orientation):

  1. If either orientation has an exact whitelist hit, use it. If both are exact, keep forward.
  2. Otherwise, use the first orientation that corrects with Hamming-1, forward then reverse complement. When both correct, forward is kept, as before.
  3. Reads with no hit are dropped, as before.

Counts per run are written to the run log under stats.barcode_orientation:

  • exact_fwd, exact_rc, corrected_fwd, corrected_rc;
  • both_exact and both_corrected (ties, forward kept);
  • switched: reads where an exact reverse-complement hit replaced the corrected forward barcode that v2-base used.

parse_barcodes(return_counts=True) returns (path, counts); by default it still returns only the path. Offsets, UMI and insert extraction are unchanged.

New run() arguments, documented in the docstring:

  • barcode_prefer_exact: bool = True (CLI --barcode_prefer_exact/--no-barcode_prefer_exact);
  • legacy: bool = False (CLI --legacy). legacy=True forces the v2-base choice.

pairplex correct-barcodes also calls parse_barcodes and gets the new default (no legacy flag there).

Tests

New file pairplex/tests/test_barcode_orientation.py, built on constructed reads and a 3-barcode whitelist:

  • exact reverse complement beats corrected forward (barcode and UMI come from the reverse complement; switched is counted);
  • prefer_exact=False reproduces the old choice;
  • exact forward beats corrected reverse complement;
  • both exact → forward kept, counted;
  • both corrected → forward kept, counted;
  • only the reverse complement corrects; no hit → dropped;
  • check_rc=False ignores the reverse complement;
  • reads with no orientation conflict parse identically in both modes;
  • run() default vs legacy=True vs barcode_prefer_exact=False.

Full suite: 28 passed.

Smoke run on 2 SimPlex wells with 2 workers: default and legacy=True both match v2-base exactly (metadata, annotated tables, consensus set). The run log shows exact_fwd=12580, both_exact=1 and no corrections. SimPlex barcodes in these wells contain no errors, so orientation conflicts cannot occur there. Expect SimPlex benchmark rows to be the same as baseline; real data is where this fix can matter.

Benchmark

Pending: D4-orient-exact-v1 (default) vs v2-base. Results will be added here.

🤖 Generated with Claude Code

bnemoz and others added 3 commits November 17, 2026 16:29
parse_barcodes took the first orientation (forward, then reverse
complement) whose barcode corrected to the whitelist, even when that was
a Hamming-1 correction and the other orientation was an exact hit. Now
an exact hit in either orientation wins; corrections are used only when
neither is exact. Ties (both exact / both corrected) keep the forward
orientation and are counted. Orientation counts go to the run log
(stats.barcode_orientation).

New run() options barcode_prefer_exact (CLI
--barcode_prefer_exact/--no-barcode_prefer_exact) and legacy (CLI
--legacy); legacy=True restores the v2-base choice exactly.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- legacy=True now forces both tso_g_max=None and barcode_prefer_exact=False
- parse_barcodes takes tso_g_max, prefer_exact and return_counts together
- fix a silent semantic conflict: the new exact-hit orientation path still used
  s[36:].lstrip("G"), which would have bypassed #15 for nearly every read; it now uses
  strip_tso_g(s[36:], tso_g_max). Added tests covering both orientation paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bnemoz

bnemoz commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Updated after #15 merged: merged main and combined the two fixes. legacy=True now forces both tso_g_max=None and barcode_prefer_exact=False, and parse_barcodes takes all three options. I also fixed a silent semantic conflict that git did not flag: this PR's new exact-hit orientation path still did s[36:].lstrip("G"), which would have bypassed #15's TSO fix for nearly every read. It now uses strip_tso_g, with tests for both orientation paths; the test fails if the old line is restored. pytest pairplex passes 68 tests, including the golden test.

@bnemoz
bnemoz merged commit 3ed106d into main Nov 17, 2026
8 checks passed
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