Skip to content

Visium HD read splitting and spot-level barcode calling - #441

Merged
andrewprzh merged 25 commits into
masterfrom
visium_hd_spot_calling
Nov 18, 2026
Merged

andrewprzh merged 25 commits into
masterfrom
visium_hd_spot_calling

Conversation

@andrewprzh

@andrewprzh andrewprzh commented Oct 30, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Visium HD barcode calling for concatenated ONT reads, and spot-level barcode calling.

Read splitting for Visium HD (VisiumHDSplittingBarcodeDetector)

  • Concatenated reads are split into molecules, as for 10x and Stereo-seq; on by default (--split_molecules auto).
  • Shares the scanning loop with the 10x splitter (SplittingScanMixin); 10x output verified byte-identical.
  • Both barcode parts are read backwards from polyT, so R1 is optional; polyT rescue near R1; strand-safe per-read fallback.
  • Simulated concatenated ONT data (2.2 molecules/read), 800K reads: recall 35.1% → 74.0% at 97.7% precision; non-concatenated reads unchanged.
  • Fixed the Visium HD UMI being one base too long when R1 is not detected.

Spot-level barcode calling (--barcode2barcode while IsoQuant calls Visium HD barcodes)

  • Barcodes are reported as spot IDs of one selected resolution (FILE:0:COL).
  • A read whose best barcode candidates tie is assigned when all tied pairs fall into one spot.
  • Barcode windows are 3 bp wider in this mode.
  • Simulated ONT, 800K reads:
    • 8 µm: recall 76.0% → 78.8%, precision 99.3% → 99.2%;
    • 16 µm: recall 76.2% → 79.3%, precision 99.6% → 99.5%.
  • Real data (8.6M ONT reads): 8 µm spots agree with 2 µm calls on 99.96% of shared molecules, +3.4% molecules.
  • Without --barcode2barcode the output is byte-identical.

Behaviour changes

  • -m visium_hd with aligned input (--bam, also with --barcoded_bam/--barcoded_reads) now needs --split_molecules false. This is a deliberate explicit error, as for 10x.
  • isoquant_detect_barcodes.py --mode visium_hd now writes one row per molecule plus a split FASTA by default.
  • --barcode2barcode now works only while IsoQuant calls Visium HD barcodes (-m visium_hd with --barcode_whitelist) and must select exactly one spot column. Other modes, --barcoded_reads and --barcoded_bam stop with an error pointing to --barcode2spot.
  • Removed the extra UMI deduplication rounds of --barcode2barcode with their barcode_barcode_col{C} outputs, which never reached quantification, the forced allinfo output, and --read_group barcode_barcode, which now stops with an error. CHECKPOINT_FORMAT is bumped to 3.

Tests and CI

  • Unit tests for the splitting detector, spot mapping, tie resolution, window margin, option resolution and QA scoring; the full unit suite passes.
  • New barcode CI configs on simulated data, baselines validated locally:
    • Mouse.VisiumHD_concat.v1.s1.800K and ….8um, in the new Barcode.Mouse.VisiumHD_concat.yml;
    • correct_struct.split, .8um and .16um.
  • New pipeline-level config SC.Mouse.VisiumHD.spot_calling.allinfo, in SC.Mouse.VisiumHD.barcode2barcode.yml, which replaces the removed SC.Mouse.VisiumHD.barcode2barcode.allinfo.
  • BAM-input and single-molecule Visium HD configs are pinned to --split_molecules false.
  • misc/assess_barcode_quality.py: new visium_hd_split QA mode and --barcode2spot spot-level scoring.
  • Barcode.Mouse.VisiumHD_concat.yml is a new workflow and can only be dispatched after merge.

Design notes and measurements: .claude/VISIUM_HD_SPLITTING.md, .claude/VISIUM_HD_SPOT_CALLING.md.

🤖 Generated with Claude Code

andrewprzh and others added 25 commits November 18, 2026 20:21
…up rounds

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ode, including details on barcode mapping and error handling
@andrewprzh
andrewprzh force-pushed the visium_hd_spot_calling branch from c6c5f59 to 9dc7c04 Compare November 18, 2026 21:45
@andrewprzh
andrewprzh merged commit dfb2a40 into master Nov 18, 2026
2 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