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:

build a converted reference index (scheme.ref_from → ref_to)
transform each read per color channel and align it to the converted index via a pluggable backend (bwamem by default; pure-Python reference backend; minimap2/mappy optional)
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.

Install

pip install -e .              # bwamem + pure-Python backends
pip install -e "./[mappy]"    # + minimap2 backend

Usage

# 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

# list built-in schemes
prismalign schemes

Schemes

name	reference index	channels	use case
`MK`	`AC→GT`	2	dual-base conversion A→G + C→T (classic two-color)
`KM`	`GT→AC`	2	reverse of MK
`BS`	`C→T`	1	bisulfite-seq (3-nt)
`SLAM`	`T→C`	1	SLAM-seq
`A2G`	`A→G`	1	m6A / A-to-I editing
`THREE`	`AC→GT`	3	three-color demo (add your 3rd base pair in `schemes.py`)

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:

backend	engine	notes
`bwamem`	BWA-MEM via the `bwamem` package	default, fast C backend
`python`	pure-Python k-mer reference aligner	portable, tests / small data
`wfa2`	WFA2-lib (vendored v2.3.6, MIT) compiled in-process	exact gapped (indel-aware) wavefront alignment; no CLI wrapper
`mappy`	minimap2 via `mappy`	official minimap2 Python binding
`minibwa`	lh3/minibwa (bwa-mem successor) via PyO3 pip binding `minibwa` (fg-labs)	~2-3x faster than bwa-mem; `pip install minibwa`
`sam`	generic SAM-emitting mapper (subprocess)	wrap `bwa`, `bwa-mem2`, `bowtie2`, `hisat2`, … via a command template
`strobealign`	ksahlin/strobealign (Rust, ultra-fast short reads)	`.sti` index, SAM out; subprocess

Direct vs CLI backends. bwamem, minibwa, mappy, wfa2 and python are direct/in-process (native bindings / compiled C). The only CLI (subprocess) backends are sam (generic) and strobealign (ultra-fast short reads — no Rust→Python binding). wfa2 reuses PythonBackend's k-mer seeding to anchor a diagonal and runs WFA2's exact gap-affine alignment for true I/D CIGARs — the same "one core algorithm" as wfmash/gem3, minus the CLI layer. On exact / simple-mismatch reads every backend's output is identical; on gapped reads WFA2 may pick a different-but-equally-valid split of the M-runs around an indel than BWA (same position and I/D set), so byte-identity applies to the mapping, not to the exact CIGAR representation.

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

Limitations (v0.0.1)

no parallel worker pool yet (sequential mapping)
paired-end needs the bwamem backend (python/mappy backends are SE-only)

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

prismalign-0.0.1.tar.gz (135.0 kB view details)

Uploaded Aug 31, 2026 Source

File details

Details for the file prismalign-0.0.1.tar.gz.

File metadata

Download URL: prismalign-0.0.1.tar.gz
Upload date: Aug 31, 2026
Size: 135.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for prismalign-0.0.1.tar.gz
Algorithm	Hash digest
SHA256	`8148aee48debdd1511675b7e91d0bf5d8bcfa5ba99c9600c1eda667a849e7153`
MD5	`757df4ca77181fea2509b47ca1b47e67`
BLAKE2b-256	`5f8d69f1bf0962af09f2e9dc6d533bbfe88b8b6c179d0bbc676c7d4ec6b42223`

See more details on using hashes here.

Provenance

The following attestation bundles were made for prismalign-0.0.1.tar.gz:

Publisher: workflow.yml on y9c/prismalign

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: prismalign-0.0.1.tar.gz
- Subject digest: 8148aee48debdd1511675b7e91d0bf5d8bcfa5ba99c9600c1eda667a849e7153
- Sigstore transparency entry: 2661759978
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: y9c/prismalign@2ca786bc7a37bd2dad372ae165604ce01c91e9d2
- Branch / Tag: refs/tags/v0.0.1
- Owner: https://github.com/y9c
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: workflow.yml@2ca786bc7a37bd2dad372ae165604ce01c91e9d2
- Trigger Event: push