tview 0.1.2.dev0

Publication-quality alignment viewer for nucleotide and amino acid sequences

tview

Publication-quality alignment viewer for nucleotide and amino acid sequences. A lightweight alternative to samtools tview that produces clean, stable image output.

Supports BAM files (with reference FASTA), pre-aligned FASTA (e.g. MAFFT output), and stacking multiple inputs into a single figure.

BAM mode — SNP (yellow), 3bp deletion, 2bp insertion (purple columns), reverse-strand insertion

FASTA mode — HIV Env protein alignment (HxB2 reference), amino acid palette

Stacked mode — two BAM files sharing a reference and region

---

Installation

pip install tview

Installs matplotlib, click, and pysam.

---

Quick Start

BAM file

tview \
  --bam aligned.bam \
  --ref reference.fa \
  --region chr1:100-200 \
  -o alignment.png

Aligned FASTA (e.g. MAFFT output)

The first sequence in the file is treated as the reference.

tview \
  --fasta env_protein_aligned.fasta \
  --palette aa \
  -o env_alignment.png

Subset columns from a FASTA alignment

Use --columns with 1-based inclusive range to window into long alignments.

tview \
  --fasta aligned.fasta \
  --columns 1-120 \
  --palette aa \
  -o first_120_cols.png

---

Stacking Multiple Panels

Each input file becomes a vertically stacked panel separated by a thin line. Panels are labeled on the left with the filename stem.

Multiple BAMs (shared reference and region)

tview \
  --bam sample1.bam --bam sample2.bam --bam sample3.bam \
  --ref reference.fa \
  --region chr1:100-200 \
  -o stacked.png

Multiple FASTAs

tview \
  --fasta group1_aligned.fasta --fasta group2_aligned.fasta \
  --palette aa \
  --columns 1-120 \
  -o comparison.png

Mix BAM and FASTA panels

--ref and --region apply only to BAM panels; --columns applies only to FASTA panels.

tview \
  --bam reads.bam \
  --ref reference.fa \
  --region chr1:100-200 \
  --fasta protein_aligned.fasta \
  --columns 1-120 \
  -o mixed.png

BAM panels are rendered first (top), FASTA panels below.

---

Piping from stdin

Pass - to read file paths from stdin (one per line). Each path becomes its own panel.

# find → stacked panels
find ./alignments -name "*.fasta" -type f | \
  tview --fasta - --palette aa --columns 1-120 -o all.png

# ls with pattern
ls samples/*.bam | \
  tview --bam - --ref ref.fa --region chr1:100-200 -o all_samples.png

# single file via echo
echo "my_alignment.fasta" | \
  tview --fasta - --palette aa -o out.png

---

Python API

The core functions are available as a Python library:

from tview import fasta_panel, bam_panel, render_panels

# FASTA alignment
panel = fasta_panel("aligned.fasta", col_start=1, col_end=120)
render_panels([panel], "output.png", palette="aa")

# BAM alignment
panel = bam_panel("sample.bam", "reference.fa", "chr1:100-200")
render_panels([panel], "output.png")

# Stack multiple panels
panels = [
    bam_panel("sample1.bam", "ref.fa", "chr1:100-200"),
    bam_panel("sample2.bam", "ref.fa", "chr1:100-200"),
]
render_panels(panels, "stacked.png", dpi=300, fontsize=7, cell=0.14)

---

Visual Conventions

Element	Symbol	Style
Match (forward)	.	light grey
Match (reverse)	,	light grey, reduced opacity
Mismatch	A T etc.	colored, yellow highlight, bold
Mismatch (reverse)	a t etc.	lowercase, colored, yellow highlight
Deletion	-	grey dash
Insertion	colored bases	purple column shading
Gap (ref in insertion col)	-	grey dash
Gap (FASTA alignment)	-	grey dash

---

Color Palettes

--palette nt (default) — Nucleotides

Base	Color
A	green #4CAF50
C	blue #2196F3
G	orange #FF9800
T	red #F44336

--palette aa — Amino Acids (Clustal-inspired)

Group	Residues	Color
Hydrophobic	A V L I M F W P	blue #2196F3
Positive charge	K R H	red #F44336
Negative charge	D E	magenta #E040FB
Polar uncharged	S T N Q	green #4CAF50
Special	G C Y	orange #FF9800

---

Full Argument Reference

Usage: tview [OPTIONS]

  Publication-quality alignment viewer (BAM or FASTA).

Options:
  --bam TEXT              BAM file(s) — each becomes a panel. Use '-' for stdin.
  --ref PATH              Reference FASTA (required for BAM mode).
  --region TEXT            Genomic region chr:start-end (required for BAM mode).
  --fasta TEXT             Aligned FASTA file(s) — each becomes a panel. Use '-' for stdin.
  --columns TEXT           Column range for FASTA, 1-based inclusive (e.g. 1-120).
  -o, --output TEXT        Output image path.  [default: alignment.png]
  --palette [nt|aa]        Color palette.  [default: nt]
  --dpi INTEGER            Image resolution.  [default: 300]
  --fontsize INTEGER       Base font size in points.  [default: 7]
  --cell FLOAT             Cell size in inches.  [default: 0.14]
  -h, --help               Show this message and exit.

Argument	Description	Default
--bam	BAM file(s), each becomes a panel. Use - for stdin.	—
--ref	Reference FASTA (required for BAM mode)	—
--region	Genomic region chr:start-end (required for BAM)	—
--fasta	Aligned FASTA file(s), each becomes a panel. Use - for stdin.	—
--columns	Column range for FASTA, 1-based inclusive (e.g. 1-120)	full alignment
-o, --output	Output image path	alignment.png
--palette	Color palette: nt or aa	nt
--dpi	Image resolution	300
--fontsize	Base font size in points	7
--cell	Cell size in inches (controls spacing)	0.14

---

Tips for Publication Figures

• Use --dpi 300 (default) for print, --dpi 150 for drafts.
• Use --cell 0.10 for denser layouts with many sequences, --cell 0.18 for fewer.
• Use --fontsize 5 or 6 when displaying wide alignments (>100 columns).
• The output format is determined by the file extension: .png, .pdf, .svg all work.
• For Nature-style figures, .pdf or .svg output preserves vector text.

# Vector output for publication
tview \
  --fasta aligned.fasta \
  --palette aa \
  --columns 1-120 \
  --cell 0.12 \
  --fontsize 6 \
  -o figure_2a.pdf

---

FASTA Input Format

The FASTA input must be pre-aligned (e.g. by MAFFT, MUSCLE, Clustal). The first sequence is used as the reference for comparison. Gap characters (-) in the alignment are preserved and rendered as grey dashes.

>HxB2_reference
MRVK---EKYQHLWRWGWRWGTMLLGMLMICS...
>sample_001
MRVKGIRKNAQHL----WRGGTLLLGMLMICS...
>sample_002
--------------------------MLMICS...

The x-axis labels count non-gap positions in the reference sequence (1, 10, 20, ...), so position numbers always correspond to the reference residue numbering regardless of gap columns.