midsplit

Demultiplex a multi-reference BAM file into per-reference buckets and call a consensus sequence for each non-empty bucket.

What it does

When reads are aligned to multiple reference sequences in a single BAM file, midsplit assigns each read (or read pair) to the reference(s) it matches best, then produces a separate BAM, consensus FASTA, and per-site statistics file for each reference that received at least one read.

The classification uses the NM (edit-distance) tag to compute a percent identity for each alignment. A read is assigned to a reference if its percent identity is at least --threshold times the best percent identity that read achieves across all references (default 0.95). Paired-end reads are treated as a unit using an overlap-aware combined percent identity, so both mates always land in the same bucket(s).

Output

For each reference that receives reads, midsplit writes:

The per-site TSV has columns: site, ref_base, consensus_base, depth, A, C, G, T. When --align is used, the consensus base is mapped back to the correct reference position even when ivar has inserted or deleted bases relative to the reference.

Usage

midsplit [options] INPUT_BAM

Options

Example

midsplit \
  --reference references/multi.fasta \
  --output-dir results/ \
  --align \
  --threshold 0.95 \
  alignments/reads-vs-multi.bam

Requirements

• Python 3.10+
• samtools and ivar on PATH
• Python dependencies are managed with uv; run uv sync to install them

Notes

• Only primary and secondary alignments are used; supplementary alignments (chimeric/split reads) are skipped.
• Reads aligned with Bowtie2 --all or -k N emit non-best hits as secondary alignments; midsplit includes these in classification so that all alignment evidence is used.
• For circular genomes (e.g. HBV) mapped against a linearised reference, local alignment (bowtie2 --very-sensitive-local) is strongly recommended over end-to-end alignment. End-to-end mode cannot soft-clip reads that span the linearisation junction, which introduces artefactual bases near position 1 of the reference and can corrupt the consensus at those positions.