Prismalign

N-color nucleotide-conversion alignment engine with pluggable backends.

Prismalign maps sequencing reads from any nucleotide-conversion chemistry (bisulfite-seq C→T, SLAM-seq T→C, m6A / A-to-I A→G, MK/KM dual-base, or a custom 3rd channel) using a HISAT-3N-style strategy:

1. build a converted reference index (scheme.ref_from → ref_to)
2. transform each read per color channel and align it to the converted index via a pluggable backend (bwamem by default; WFA2-lib; minimap2/mappy; minibwa, all optional)
3. re-score every hit against the original reference so that real conversions are rewarded (not counted as mismatches), emitting a color-correct MD plus per-channel Y/Z counts in BAM tags.

All per-read heavy kernels are native C (BWA-MEM / WFA2-lib / minimap2 / minibwa); the Python layer is a thin, friendly wrapper.

Install

pip install -e .              # bwamem + built-in WFA2 C backends
pip install -e "./[mappy]"    # + minimap2 backend

Usage — Python (clean wrapper)

import prismalign as ps

# one-shot mapping -> BAM (builds indexes, maps, cleans up)
ps.map_reads("reads.fq", "ref.fa", "out.bam",
             scheme="MK", backend="bwamem", threads=4)

# object API / reuse
with ps.NColorMapper(scheme=ps.BS, backend="bwamem") as mapper:
    mapper.map_file("reads.fq", ref_files=["ref.fa"], output_files=["bs.bam"])

Usage — CLI

# classic two-color (MK: A->G + C->T) on bwamem
prismalign map -s MK --backend bwamem -r ref.fa -o out.bam reads.fq

# bisulfite-seq (3-nt single channel C->T)
prismalign map -s BS -r genome.fa -o bs.bam --index-dir idx reads.fq

# parallel (2 copies of the reads, byte-identical output to -t 1)
prismalign map -s MK -r ref.fa -o out.bam -t 4 reads.fq

# list built-in schemes
prismalign schemes

Schemes

Python API

from prismalign import NColorMapper, BS

mapper = NColorMapper(scheme=BS, backend="bwamem", index_dir="idx")
mapper.map_file(r1_file="reads.fq", ref_files=["genome.fa"],
                output_files=["out.bam"])

Backends

Prismalign's engine only needs align() -> [RawHit] from a backend (re-scoring against the original reference is engine-side), so adding one is easy:

Note on external-tool adapters. --backend selects the four native in-process backends above. To wrap an aligner prismalign has no binding for (e.g. bwa-mem2, bowtie2, hisat-3n, strobealign), use prismalign.adapters (SamAdapter, BwaMem2Adapter, Bowtie2Adapter, StrobealignAdapter) — these are not --backend-selectable.

Full inventory — including where each Python wrapper lives — is in docs/backends.md.

Speed & IO

• Parallel mapping: -t/--threads N maps reads in an ordered fork+COW process pool (any backend); batches are drained in read order so the BAM is byte-identical to threads=1. --batch-size tunes reads per worker.
• Reduced repeated IO: references are copy+converted once even when reused across layers (cache keyed by path+scheme); per-hit reference fetch is cached in memory for small contigs (RNA/transcript references), so only one indexed read per contig.

Limitations (v0.2.x)

• paired-end is supported natively by the bwamem, mappy and minibwa backends; wfa2 is single-end for now (the subprocess sam/ strobealign/bowtie2/bwa_mem2 adapters are also SE).
• hierarchical (layered) mapping uses the PLAIN identity scheme for non-converted short-RNA references. minibwa is the fastest native backend but needs standard (non-free-threaded) CPython ≤ 3.13, so on 3.14t mappy is the fastest available.