igvplot

IGV-style BAM read pileup, coverage, gene features, sashimi junctions and epigenetic base modifications in matplotlib — built on pysam and dna_features_viewer.

Reads, coverage and genes are stacked on shared x-axes so genomic positions line up exactly, with per-base mismatch / insertion / deletion detail, IGV colouring, and base-resolution zoom.

Contents

• Install
• Quick start
• Gallery
• Python API
• Command line
• Reference
• Regenerate the gallery
• Docs and development

pip install -e .
# optional: GFF/GTF feature support
pip install -e ".[gff]"

Requires pysam, matplotlib, numpy, dna-features-viewer, biopython.

import igvplot
view = igvplot.plot_view(
 bam_path="sample.bam",
 region="chr1:1,000-2,000", # 1-based inclusive
 features="annotation.gb",
 reference="genome.fa",
 sites={1050: "m6A"},
 sashimi=True,
 out_path="locus.png", # fig = view.render() to keep it in memory
)

Or stack tracks fluently with the IGV builder (IGV == GenomeView == AlignmentView):

from igvplot import IGV
igv = (
 IGV("chr1:1,000-2,000", reference="genome.fa", dpi=150)
 .add_sashimi("rna.bam")
 .add_coverage("rna.bam")
 .add_reads("rna.bam", color_by="pairOrientation", group_by="strand",
 link_mates=True, view_as_pairs=True, show_soft_clips=True)
 .add_features("annotation.gb")
 .add_sequence("genome.fa")
 .add_sites({1050: "m6A"})
 .add_base_mods({1050: (1, "m6A")})
 .add_highlight_regions([(1050, 1080)])
)
igv.savefig("locus.png")

Every figure below is produced by examples/generate_gallery.py from the synthetic data in data/.

Sashimi arcs → gene arrows → coverage (+ variant pile) → aligned reads → reference sequence.

default view

Base-level zoom — every read base as a letter, aligned to a colour-coded reference row, so SNPs, insertions (+) and deletions (−) are read position by position.

base-level zoom

Colour and cluster reads by attribute via color_by / group_by; link_mates draws a mate connector and view_as_pairs joins a fragment on one row (IGV "view as pairs").

Strand-aware m6A / m5C / ... markers (add_base_mods), reads coloured by the modification they span (color_by="basemod"), per-base variant fraction, modification stoichiometry and IUPAC motif (DRACH) tracks.

The m6A example below uses GLORI (a negative method): the reagent converts every unmodified A→G (and its reverse-strand complement T→C), but an m6A keeps its own base. The per-base conversion track dips to ~0% exactly at the m6A sites, and reads are coloured by strand with the converted bases in red.

m6A GLORI: converted reads + per-base A→G / T→C conversion

Base-resolution zoom at the forward-gene m6A sites — the A→G conversions are readable letter-by-letter while the m6A sites (chrM6A:250 & 350) keep their A:

m6A GLORI zoom: A→G conversions around m6A sites

per-base VAF / mod stoichiometry / motifs

Overlay coverage, comparison sashimi (add_sashimi_overlay), strand-specific coverage (add_coverage_strands) and reads (add_reads_overlay) from several samples on shared axes, then shade regions of interest.

multi-sample overlay

multi-sample comparison

Scale bar + contact heatmap + TAD boundaries + genes + coverage + reads.

Hi-C multi-track

One centred plot per variant, with the variant allele fraction in the title and the base change called out at the site.

variant VAF

A generic signal (.add_signal), GC content (.add_gc), interaction arcs (.add_arc), variants (.add_variants) and a fully custom track (.add_track).

signal / GC / loops / variants / custom

• plot_view(...) — one-call convenience (see Quick start).
• IGV / GenomeView / AlignmentView — fluent builder; every add_* returns self, and call order = top-to-bottom track order.
• summary(bam, region, reference) — region QC stats.
• set_font_size(n) / apply_theme() — styling.

Full signature reference: docs/api.md .

igvplot sample.bam chr1:1,000-2,000 -o locus.png \
 --features annotation.gb -r genome.fa \
 --sites sites.bed --sashimi --link-mates --view-as-pairs \
 --color-by pairOrientation --group-by strand --show-sequence \
 --coverage-strand --variants variants.vcf --gc

Variant batch (one figure per VCF/BED site, with VAF):

igvplot sample.bam --vcf variants.vcf -r genome.fa --window 100 \
 --prefix variant --sort-by-variant --vaf

Other flags: --insert-length/--read-length were removed as non-track QC plots; --fontSize N, --display-mode, --sort-by, --basemod, --highlight-regions, --bigwig, --version are available.

MIT — see LICENSE.

python examples/generate_gallery.py # or: make gallery

• docs/api.md — full API reference (regions, every track method, stats, CLI).
• CONTRIBUTING.md — setup, style, module map.
• CHANGELOG.md — release history.
• CI runs ruff lint + tests (warnings-as-errors) + a wheel build on every push (.github/workflows/ci.yml).

pip install -e ".[dev]" # build, pytest, pytest-cov
python -m pytest -q # run the test suite
# or: make test / make lint / make gallery / make build

python scripts/bump_version.py --patch # bump to v0.1.1 (update pyproject + __init__)
python scripts/bump_version.py --patch --tag # bump, commit, tag v0.1.1
git push && git push --tags # tag triggers .github/workflows/release.yml

Pushing a v* tag builds the wheel + sdist, verifies the wheel imports, and uploads the artifacts to a GitHub Release.