Skip to main content

Pypi Releases Downloads CI

sanger

A lightweight toolkit for Sanger sequencing data: chromatogram visualization, alignment & mutation calling, quality control, base-calling, trimming, assembly and export — usable as a CLI, a Python library, or an MCP server for LLM agents.

Quick start

pip install sanger
sanger mut -q read.ab1 -s ref.fa -o out --plot
from sanger import Chromatogram, parse_fasta

cg = Chromatogram.from_abi("./data/B5-M13R_B07.ab1")
print(cg.length, cg.mean_quality, cg.gc_percent)   # 1141 50.2 52.0
ref = parse_fasta("./data/ref.fa")
print(cg.qc())                                    # QC metrics (CRL, SNR)
print(cg.to_vcf(ref))                             # variant calling -> VCF
cg.plot(region=(55, 90))                          # render a region

Examples

The gallery below is produced from the bundled real ABI sample (data/B5-M13R_B07.ab1 vs data/ref.fa) by python -m scripts.make_readme_examples.

Mutation calling — the SNP T61A is highlighted and annotated.

Mutation calling

Quality control — per-base Phred quality, CRL and Mott trimming.

Quality profile

Side-by-side panels — chromatogram + GC% + quality on a shared axis.

Side-by-side

Feature overlay — primers, amplicon and SNPs on the trace.

Feature overlay

Re-called bases — mixed/heterozygous sites are marked (M/W/K).

Re-called bases

Assembly — pileup depth and consensus against a reference.

Assembly

Installation

The default install pulls only numpy, click and rich-click — no C compiler and no plotting library required. Parsing, QC, alignment (a bundled Cython Smith-Waterman with a NumPy fallback), analysis and export all work out of the box.

pip install sanger

Optional extras:

pip install "sanger[plot]"     # matplotlib -> chromatogram figures
pip install "sanger[viewer]"   # DNA Features Viewer integration
pip install "sanger[agent]"    # MCP server for LLM agents
pip install "sanger[all]"      # everything

The bundled Cython Smith-Waterman accelerator (sanger._swalign, self-contained, no ssw dependency) is compiled automatically when a C compiler is present at build time; otherwise the NumPy fallback is used.

From source:

git clone git@github.com:y9c/sanger.git
cd sanger
make init       # install dependencies
make test       # run the test-suite

Command-line interface

Built on rich-click, with themed command groups (sanger --help):

sanger mut            mutation calling & reporting
sanger qc             per-read quality-control metrics
sanger track          split / join / slice chromatogram trace files
sanger edit           trim, strip primers, reverse-complement
sanger basecall       re-call bases from raw four-channel traces
sanger assemble       reference-guided pileup & consensus
sanger analyze        sequence biology (translate, motifs, restriction)
sanger export         FASTA / VCF / JSON / batch summary
sanger plot           chromatogram rendering (+ features / DNA viewer)

Examples:

sanger mut -q read.ab1 -s ref.fa -o out --plot        # mutation report + figure
sanger qc r1.ab1 r2.ab1                               # QC table
sanger track split read.ab1 -c 20,40 -f tsv           # split traces
sanger edit trim read.ab1 -c 0.05 -o out              # Mott quality trim
sanger edit strip-primers read.ab1 -f AAAA -r CCCA    # primer removal
sanger basecall call read.ab1 -r 0.45                 # re-call bases
sanger basecall hetero read.ab1                       # mixed/heterozygous sites
sanger assemble consensus a.ab1 b.ab1 -r ref.fa       # reference-guided consensus
sanger analyze rest read.ab1                          # restriction sites
sanger analyze translate read.ab1 -f 1                # protein translation
sanger export vcf -q read.ab1 -s ref.fa               # VCF of variants
sanger export batch *.ab1 -o out -f csv               # batch QC table
sanger plot dnaviewer read.ab1 --start 50 --end 100   # with DNA Features Viewer

Python API

The high-level Chromatogram object is the easiest way to work with the toolkit; the low-level modules remain available for custom work.

from sanger import Chromatogram, parse_fasta

cg = Chromatogram.from_abi("./data/B5-M13R_B07.ab1")
ref = parse_fasta("./data/ref.fa")
Common operations

Mutation calling & quality filtering

from sanger.quality import QualityFilter

snps = cg.call_mutations(ref)
confident = QualityFilter(min_base_qual=20, min_local_qual=20).filter(snps)
print([f"{s.ref_base}{s.ref_pos}{s.cf_base}" for s in confident])

QC metrics (incl. continuous read length)

m = cg.qc()
print(m["mean_qual"], m["trim_start"], m["trim_end"], m["crl"], m["snr"])

Re-call bases from raw traces + mixed/heterozygous sites

res = cg.basecall()
print(res.sequence)
for pos, major, minor, frac in res.heterozygotes(min_ratio=0.2):
    print(pos, major, minor, frac)

Trim / reverse-complement / orientation

trimmed = cg.trim().trim_leading_ns()     # Mott trim then drop leading Ns
rc      = cg.reverse_complement()
ori     = cg.detect_orientation(ref)      # +1 forward, -1 reverse-complement

Sequence-level analysis

print(cg.analyze("translate", frame=1))            # protein translation
print(cg.analyze("restriction"))                    # {'EcoRI': [27], ...}
print(cg.analyze("motif", motif="AATT"))            # motif positions

Export

print(cg.to_fasta())
print(cg.to_vcf(ref))
cg.export("out")                                    # write FASTA to disk

Feature overlay (for external tools)

from sanger import ChromatogramFeature
from sanger.features import plot_features

feat = ChromatogramFeature(start=90, end=130, strand=+1, label="primer F")
fig, ax = cg.plot(region=(80, 140))
plot_features(cg.to_record, ax, features=[feat])

Side-by-side with another tool's output (shared x-axis)

from sanger.composite import side_by_side

def my_panel(ax, trace_x, peaks, seq, record, start=None):
    ax.bar(range(len(seq)), [1.0] * len(seq), color="0.66")
    ax.set_ylabel("my tool signal")

fig, (ax_chrom, ax_panel) = side_by_side(cg.to_record, my_panel, region=(10, 40))

Consensus / assembly from many reads

from sanger import parse_abi
from sanger.assembly import pileup, consensus

reads = [parse_abi(f) for f in ["a.ab1", "b.ab1", "c.ab1"]]
table = pileup(reads, ref, quality_threshold=20)
print(consensus(table))

Plot together with DNA Features Viewer (needs sanger[viewer])

from sanger import ChromatogramFeature
from sanger.dnalink import plot_combined

feats = [ChromatogramFeature(start=90, end=130, strand=+1, label="primer F")]
fig, (ax_feat, ax_chrom) = plot_combined(cg.to_record, features=feats, region=(55, 90))

Chromatogram object

A terse, idiomatic workflow in one object:

from sanger import Chromatogram

cg = Chromatogram.from_abi("./data/B5-M13R_B07.ab1")
cg.length, cg.mean_quality, cg.gc_percent, cg.channels   # 1141 50.2 52.0 GATC
cg.qc()                            # QC metrics (CRL, SNR)
cg.basecall()                      # re-call bases from raw traces
cg.call_mutations(ref)             # variant calling
cg.trim().trim_leading_ns()        # quality trimming
cg.reverse_complement()            # reverse-strand view
cg.analyze("restriction")          # restriction-site scan
cg.plot(region=(55, 90))           # render a region
cg.to_fasta(), cg.to_vcf(ref)      # export
cg.export("out")                   # write to disk

Agent / MCP

sanger ships a Model Context Protocol server so LLM agents and MCP clients can call the toolkit as tools:

pip install "sanger[agent]"     # adds mcp>=2
sanger-mcp                        # run the MCP server over stdio
python -m sanger.mcp_server       # identical
Tool Purpose
read_chromatogram(path) parse an ABI → summary (length, GC%, quality, CRL)
qc_metrics(path) full per-read QC metrics (incl. CRL, signal, SNR)
call_mutations(query ab1, subject fa) variants vs a reference (SNPs/indels)
re_call_bases(path) re-call bases from raw traces + heterozygotes
analyze_sequence(path, kind) translate / motifs / restriction / GC
trim_read(path, mode) quality-trim a read
export_sequence(path, outdir) write FASTA or VCF
plot_chromatogram(path, out, start, end) render a chromatogram PNG

Register it in an MCP client's config, e.g.:

{ "mcpServers": { "sanger": { "command": "sanger-mcp" } } }

ChangeLog

  • Replace the external ssw aligner with a bundled Cython Smith-Waterman (+ NumPy fallback) — no external alignment dependency.
  • Reverse-complement the chromatogram file (inspired by Snapgene).
  • Add per-base quality filtering, continuous read length (CRL), signal/SNR QC.
  • Add base-calling from raw four-channel traces + heterozygote (mixed-base) calling.
  • Add feature overlay API and DNA Features Viewer integration.
  • Add split / join / slice trace operations with provenance (offset).
  • Add reference-guided pileup & consensus (assembly module).
  • Add FASTA / VCF / JSON / batch export.
  • Fix false-positive mutations from lowercase reference bases (case-insensitive).
  • Build the CLI with rich-click (themed groups, short options, --version).

TODO

  • call mutation by alignment and plot Chromatogram graphic
  • add a doc
  • change x-axis by peak location
  • fix bug that chromatogram switches position after trim
  • wrap as a CLI app
  • return quality score in output (quality module + report)
  • fix selected base not being centred (center_region)
  • fix plot_chromatograph rendering bug (full-region bounds, channels)
  • add projection/assembly (assembly module)
  • preserve trimmed-origin positions when slicing/joining (offset provenance)

Download files

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

Source Distribution

sanger-0.1.2.tar.gz (133.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

sanger-0.1.2-cp314-cp314-musllinux_1_2_x86_64.whl (245.0 kB view details)

Uploaded CPython 3.14musllinux: musl 1.2+ x86-64

sanger-0.1.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (245.1 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

sanger-0.1.2-cp313-cp313-musllinux_1_2_x86_64.whl (246.0 kB view details)

Uploaded CPython 3.13musllinux: musl 1.2+ x86-64

sanger-0.1.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (246.2 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

sanger-0.1.2-cp312-cp312-musllinux_1_2_x86_64.whl (249.2 kB view details)

Uploaded CPython 3.12musllinux: musl 1.2+ x86-64

sanger-0.1.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (249.5 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

sanger-0.1.2-cp311-cp311-musllinux_1_2_x86_64.whl (242.2 kB view details)

Uploaded CPython 3.11musllinux: musl 1.2+ x86-64

sanger-0.1.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl (242.3 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.28+ x86-64manylinux: glibc 2.5+ x86-64

File details

Details for the file sanger-0.1.2.tar.gz.

File metadata

  • Download URL: sanger-0.1.2.tar.gz
  • Upload date:
  • Size: 133.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sanger-0.1.2.tar.gz
Algorithm Hash digest
SHA256 d6794068348e45c1dbc68ef4263c0c87a3ae437262475351180f0c8c4fb4a487
MD5 262be058680caf209655b93391a53af0
BLAKE2b-256 77e1f075cd77e9e81f1bb65233573f3d3dd0d2fa768b492a03bdec591950d1b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2.tar.gz:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp314-cp314-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp314-cp314-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 5d6dab336580d573e11df26f801f593cd5df784ea2aad73a75d8f5c29e074d82
MD5 a814c3425599879597ddac74a0839d80
BLAKE2b-256 d6e7b1b54d19aa29c0951c855def24d09f27bc71b0681f6421ab6fa111ad5d6c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp314-cp314-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 5451cfb9ed1b0eaf60b3102a07dab4e1152e3b0e04f088dc699e2ce8a4190ee1
MD5 6831f76ea01dbe288af930aec64c4087
BLAKE2b-256 26761503c2367983e84797148e1661f6cdc88cd8f804a3114f5addfec0211dee

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp313-cp313-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp313-cp313-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 7598d0090304ff3a3bdd9506198e25637d984f58822a3e271d80a990890d6a6f
MD5 be86e3ed102edfdb62af09ca470fed2a
BLAKE2b-256 92184e64550a6edbd2f01d735fe158e39c15d0610028a48a2b2a9c5abd00e52e

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp313-cp313-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 3b672077396e8e1cb20c997d5ff72641849fe599b55dba0cc4839e428a8eeffa
MD5 f0edadda19aae5be86425e1877e7206c
BLAKE2b-256 e8930eff087bb20bd52f0a62c2442d074dd1928884f800db522a82f1bfca6d0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp312-cp312-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp312-cp312-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a099b020c485d4655e65744eaf1b357f8bebadda4cbfd45eafc157f8f0e22e84
MD5 0f82e959455351a35453865e28bdc42e
BLAKE2b-256 462155d31b4f2fc5380e26fc49edd3f3649a34dbc893a48a7bb50ccbf39a76d8

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp312-cp312-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 c3313c8e208b2f02fc6c03bc7e825c4c06c6ad33fb0f70fcdbec822e95d571bd
MD5 bb0409c0d5e821720cb37cf085261620
BLAKE2b-256 6ed4d4e191f0e220d3200caad2027c6444926e3a848ab16b6be134053fd7adc5

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp311-cp311-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp311-cp311-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 19fa545f04ba4adfa2fa6f5b295d734bea49626ec0010f79dfe843f1d3f8d59d
MD5 61d909566ce836fcaffb3676a1cefdb8
BLAKE2b-256 88ac9418ae16b45b9cdacd3eed2c4311c054c1dd67d93861ae08f23f290e2a6d

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp311-cp311-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

File details

Details for the file sanger-0.1.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl.

File metadata

File hashes

Hashes for sanger-0.1.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Algorithm Hash digest
SHA256 9d8f435c057447708f2e1438a24915f10dbfacbc4c42a2bbd07054eabf18c5e8
MD5 54e6e287845d1963b48991565d2a5783
BLAKE2b-256 c5988accbfb0602a3b58b445aac1fd8f8ae4542f906da3ae6cc59e10e788644c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sanger-0.1.2-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl:

Publisher: pypi.yml on y9c/sanger

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

Release history Release notifications | RSS feed

0.1.5

21 files

0.1.4

16 files

0.1.3

11 files

This release

0.1.2 This release

9 files

0.1.1

1 file

0.1.0

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page