IsoTracks

Isoform models, reads with poly(A) tails, RNA modifications, coverage and gene fusions from IsoForge long-read RNA-seq results, one gene per figure.

Give IsoTracks an IsoForge run:

isotracks plot --gene SAT1 --isoforge results/project --output figures/SAT1

from isotracks import plot_gene

plot_gene("SAT1", isoforge="results/project", output="figures/SAT1")

results/project is the prefix IsoForge was run with (isoforge annotate --write_bam --o results/project). Both write figures/SAT1.pdf and figures/SAT1.png at journal column width.

For BAM files of your own, or to name the conditions, add them:

isotracks plot --gene SAT1 --isoforge results/project \
    --bam "Control:Control_1.bam,Control_2.bam;Treated:Treated_1.bam,Treated_2.bam" \
    --output figures/SAT1

plot_gene(
    "SAT1",
    isoforge="results/project",
    bam_files={"Control": ["Control_1.bam", "Control_2.bam"],
               "Treated": ["Treated_1.bam", "Treated_2.bam"]},
    output="figures/SAT1",
)

Contents

• Install
• Input
• The figure
• Isoforms and reads
• Views: zoom, close-up, shortened introns, highlights
• Fusion transcripts
• RNA modifications
• Tables
• Appearance
• Command line
• Python API
• Development
• Citation

Install

pip install isotracks

Python 3.10 or later; matplotlib, numpy, pandas, pyarrow, pysam and scipy are installed with it. From source:

git clone https://github.com/MustafaElshani/IsoTracks
cd IsoTracks
pip install .

Input

An IsoForge run

--isoforge (isoforge=) takes the prefix IsoForge was run with (--o results/project), the run's directory, or any one of its files. IsoTracks reads from it:

Any of these can be given on its own instead (--annotation-gtf, --read-annot, --tss, --polya, --fusion-table, --bam, --bed); an explicit file takes precedence over the run.

Only whole reads of the transcripts IsoForge reports are drawn (cluster_supported in the read table). --read-filter all draws every read in the table.

BAM files

The sorted, indexed BAMs IsoForge was given (--bam) or kept (--write_bam). Replicates within a condition are pooled into one read stack.

• From the run, samples are grouped as IsoForge groups them: the sample name up to its first underscore is the condition (Control_1, Control_2 → Control).

• With --bam, conditions are named explicitly:

  --bam "Control:Control_1.bam,Control_2.bam;Treated:Treated_1.bam,Treated_2.bam"
  bam_files={"Control": ["Control_1.bam", "Control_2.bam"], "Treated": ["Treated_1.bam", "Treated_2.bam"]}
  

Poly(A) tail lengths are read from the pt tag of the reads, or from the read annotation when the BAM has none.

Optional

The figure

Top to bottom:

• Every figure reads 5′ to 3′ from left to right. A minus-strand gene is drawn with the axis reversed.
• Every read stack has the same height. Its read count is in the gutter (n = 373).
• Coverage is built from the reads of the drawn isoforms. An arc's thickness is the number of reads across that junction.

Isoforms and reads

waterfall	diamond
Longest tail at the top.	Longest tail in the middle.

Views

Zoom

isotracks plot --gene SAT1 ... --zoom last_exon

view.plot(region=view.zoom("last_exon", padding=400))

Targets: first_exon, last_exon, exon_<N>, 5_prime, 3_prime, whole_gene. Exons are numbered 5′ to 3′. A window reaching the 3′ end is widened to fit the longest poly(A) tail.

A close-up beside the gene

--detail (detail=) draws a region again beside the whole figure, row for row, at true scale.

default	--detail last_exon

It takes last_exon, exon_<N>, 3_utr, junction_<N>, 3_prime, 5_prime or a range. --detail-share sets the fraction of the width the close-up takes (default 0.4). Depth and read-end density share one scale across both panels.

Shortened introns

--introns scaled	--introns fixed
Every intron shrunk by one factor; together they take --intron-share of the width (default 0.3).	Every intron drawn at the same small width.

Exons, flanks and poly(A) tails stay at true scale. Each shortened intron is marked with // on the axis.

Highlighting a region

--highlight (highlight=) marks regions with a band through every track.

isotracks plot --gene SAT1 ... --highlight junction_2 3_utr

view.plot(highlight=["junction_2", "3_utr:ENST00000111.1"])
view.plot(highlight=(31_950_000, 31_951_000), highlight_style="outline")

A named region is measured on the isoform with the most exons, or on the one given after a colon (exon_2:ENST00000111.1). --highlight-style is both (a faint box with a dotted edge), box or outline.

Fusion transcripts

--fusion draws a fusion called by IsoForge, by its genes or its call ID:

isotracks plot --fusion RIMS2::ATP6V1C1 --isoforge results/project \
    --reference-gtf gencode.gtf --output figures/RIMS2_ATP6V1C1

from isotracks import FusionView

view = FusionView("RIMS2::ATP6V1C1", isoforge="results/project", reference_gtf="gencode.gtf")
view.plot(output="figures/RIMS2_ATP6V1C1")

The schematic is drawn at the top of every fusion figure (--no-fusion-schematic leaves it out).

The panels below it follow the gene figure, one panel per partner in transcript order:

• A dashed line marks each breakpoint through every row.
• Transcripts and reads are joined across the gap between panels: by an intron line where the junction is on splice sites at both ends, and by a dotted line where it is not.
• Introns are shortened within each panel (--introns scaled is the default for a fusion).
• For a fusion of three or more genes, transcripts through every partner are drawn first, then those joining only some. --fusion-reads complete draws only the former.

Input. The fusion tables hold every read, so BAMs are optional: they add the poly(A) tails. Samples are grouped into conditions as for a gene; --conditions "Control:rep1,rep2;Treated:rep3" names the groups without BAMs. --reference-gtf gives the schematic each partner's whole gene.

A fusion can also be drawn without IsoForge's tables, from a line of breakpoints with its reads found in the BAMs. A junction is donor>acceptor, the last base kept upstream and the first kept downstream:

FusionView("RIMS2::ATP6V1C1  chr8::chr8  chr8:103501062>chr8:103062955",
           bam_files=bam_files, reference_gtf="gencode.gtf")

RNA modifications

Modification tracks are drawn from modkit pileup bedMethyl files in genome coordinates, bgzipped and tabix-indexed, one per replicate:

modkit pileup sample.bam sample.bed --ref genome.fa
bgzip sample.bed && tabix -p bed sample.bed.gz

isotracks plot --gene ACTB --isoforge results/project \
    --modkit "Control:Control_1.bed.gz;Treated:Treated_1.bed.gz" --mods a 17802 \
    --output figures/ACTB

Each lollipop is one site; its height is the modified fraction, from 0 to 100%: reads called modified over reads assessed at that position. Replicates are pooled by summing counts.

The gutter reports sites drawn over sites assessed (89/1,933 sites).

Differential modification

--dmr draws the change in modified fraction per site from a modkit dmr pair site table, sorted, bgzipped and tabix-indexed:

modkit dmr pair -a Control_1.bed.gz -a Control_2.bed.gz -b Treated_1.bed.gz -b Treated_2.bed.gz \
    --ref genome.fa --base A --header -o sites.bed
grep -v '^#' sites.bed | sort -k1,1 -k2,2n | bgzip > sites.bed.gz
tabix -p bed sites.bed.gz

isotracks plot --gene ACTB ... --dmr "Control vs Treated:sites.bed.gz"

The axis runs from −100% to +100%. modkit's effect size is a − b, so a stem pointing up is a site less modified in the second sample set, and a stem pointing down one more modified.

Tables

Coordinates of a gene's isoforms and exons, 1-based and inclusive:

isotracks info --gene SAT1 --isoforge results/project
isotracks info --gene SAT1 --isoforge results/project --format tsv --exons-table -o exons.tsv

view.print_info()        # the report
view.isoform_table()     # one row per isoform: exons, length, span, reads
view.exons()             # one row per exon

Per-read poly(A) tail lengths:

isotracks polya --gene SAT1 --isoforge results/project -o SAT1_polya.csv

view.polya_table()       # gene, transcript_id, condition, sample, read_name, polya_length

Appearance

Figures are built at the printed width. Isoform colours are Okabe–Ito. PDF output embeds TrueType fonts and SVG keeps live text.

from isotracks import IsoTracks, Layout, theme

theme.use(width="double", readability="large")
IsoTracks(..., isoform_colors=["#0072B2", "#D55E00"], layout=Layout(read_stack=4.5, coverage=2.0))

Command line

isotracks <command> --help lists every option.

Python API

from isotracks import IsoTracks

view = IsoTracks(gene_name="SAT1", isoforge="results/project", min_reads_per_condition=5)

view.transcripts()                               # the isoforms drawn
view.plot(output="figures/SAT1")                 # PDF and PNG
view.plot(output="figures/SAT1.svg")             # one format
view.plot(region=view.zoom("last_exon"), sort_style="diamond")
view.plot(detail="last_exon", introns="scaled", highlight="3_utr")

plot_gene(gene, isoforge=..., output=..., **options) builds and draws in one call. examples/ has a script and a notebook.

Tracks can also be stacked directly:

from isotracks import Canvas
from isotracks.io import CoverageReader

canvas = Canvas()
canvas.add("TranscriptTrack", file_name="models.bed", label="models")
canvas.add("CoverageTrack", reader=CoverageReader(file_names=["a.bam"]), label="depth")
canvas.add("CoordinateAxisTrack")
canvas.render(region=("chr1", 1_000_000, 1_010_000, "+"))

Development

pip install -e ".[dev]"
pytest

The figures in this README are written by the scripts in docs/: make_examples.py from synthetic data, make_gene_examples.py and make_fusion_example.py from an IsoForge run, and make_logo.py.

src/isotracks/
├── browser.py       IsoTracks, plot_gene: the gene view
├── fusion_view.py   FusionView: the fusion view
├── fusion.py        fusion calls, partners, reads and transcripts
├── isoforge.py      the files of an IsoForge run
├── annotation.py    GTF, read annotation and BED12
├── canvas.py        the figure: tracks in rows, in one or more panels
├── theme.py         widths, type sizes and colours
├── layout.py        track heights
├── cli.py           the isotracks command
├── io/              readers for alignments, features, sites and modifications
└── tracks/          one module per track type

Citation

IsoTracks is a companion tool of IsoForge. The IsoForge manuscript is in preparation. Until it is out, please cite the IsoForge repository:

Elshani M, Zhang Y, Harrison DJ. IsoForge, version 1.0.0. https://github.com/MustafaElshani/IsoForge

License

MIT