IsoEnds

Poly(A) tail length, alternative polyadenylation and transcription start sites from IsoForge long-read RNA-seq results, tested over biological replicates.

IsoEnds reads an IsoForge run as it is. The per-read table of IsoForge holds each read's transcript, start site, poly(A) site and tail length, so IsoEnds needs no alignments. It compares two conditions and reports, per gene:

Every test uses replicates as its unit, never reads. The figures on this page are IsoEnds output for a simulated experiment of 10 units with three replicate pairs each.

isoends init --out config.yaml          # write a template, then edit it
isoends all --config config.yaml -j 4   # tails, APA, TSS and the report

import isoends as ie

exp = ie.Experiment.from_isoforge(
    runs={"my_run": "isoforge/results"}, samples="samples.tsv", control="control", treatment="treated",
    reference_gtf="gencode.primary_assembly.annotation.gtf", outdir="isoends_out")
res = exp.run(jobs=4)
res.volcano("tandem")

Contents

• Install
• Input
• Poly(A) tails
• Alternative polyadenylation
• Transcription start sites
• Statistics
• Output
• Python API
• Command line
• Development

Install

pip install isoends

Python 3.11 or later. pip install "isoends[bam]" adds pysam, for tails read from BAM files. R with limma is used for the moderated t-test when present; without it the built-in Python implementation gives the same results. isoends demo makes a synthetic experiment and analyses it.

Input

IsoEnds uses the supported reads of the Parquet read table: reads marked cluster_supported whose transcript is in the IsoForge GTF. These are the reads of IsoForge's filtered read TSV. Tail lengths come from their polya_length: a read without a call has -1 and is left out, a length of 0 is a call (tails.min_tail_nt: 1 leaves it out). A per-read tail table or BAMs with the pt:i tag can be given instead (tails:, tail_bams:).

Sample sheet

A tab- or comma-separated table with one row per dataset of the read table:

dataset      unit     condition  pair
A_control_1  line_A   control    1
A_treated_1  line_A   treated    1
A_control_2  line_A   control    2
A_treated_2  line_A   treated    2
B_control_1  line_B   control    1
...

A unit needs two or more replicates of each condition to be tested on its own. To compare another pair of conditions from the same sheet, run isoends all --control A --treatment C --outdir out_C.

Poly(A) tails

Per sample, the tail of a gene or transcript is the median over its reads, and the overall tail of the sample is the median over its transcripts with more than 20 reads. The change between conditions is tested within each unit and across units.

res.volcano("tail_genes")                 # genes; "tail_transcripts" for transcripts
res.get("tail_genes", level="within")     # the table behind it, per unit
exp.plot_tails("GENE", unit="line_A")     # the tail distribution of one gene

(A) Per-transcript median tails of each unit by condition, with their medians. (B) Change in the median tail of each gene, tested across units.

Also reported: the overall tail of each sample, tails by transcript category (reference type, or SQANTI3 class for novel models), NMD and retained-intron isoforms against the coding isoform of the same gene, and the share of short tails per gene set. Gene sets are ribosomal proteins, histones, snoRNA hosts and mitochondrial genes, or your own (gene_classes:).

Alternative polyadenylation

The 3′ ends of the reads are clustered per gene and each cluster is placed on the gene's Ensembl-canonical transcript. Genes are Ensembl gene IDs, so two genes that share a name are never pooled.

res.volcano("tandem")            # also "composite", "skipped", "internal", "five_utr", "intronic",
res.get("noncoding_tandem")      # "noncoding_tandem"
res.plot_sites("GENE", unit="line_A")

Each point is a gene tested across units. Under each panel are the two isoforms compared, coloured as the points: orange points are genes that move towards the orange isoform, teal points towards the teal one.

For each gene the tables give both sites of the tandem pair, their distance from the stop codon, the 3′UTR length gained or lost and the transcripts ending at each site. Where two sites are equally used, the one with the lower coordinate is taken. An intronic site is composite or skipped by the majority of the transcripts ending there, of any gene on that strand.

(A) Usage of the poly(A) sites of one gene (plot_sites). (B) Its tail distribution, with the sample medians that are tested as ticks (plot_tails).

Transcription start sites

The 5′ ends IsoForge assigns to a start site are clustered and placed on the canonical transcript in the same way.

res.volcano("tss_switch")        # also "tss_upstream", "tss_first_exon", "tss_internal"
res.plot_sites("GENE", unit="line_A", kind="tss")

Each point is a gene tested across units, with the two isoforms compared under each panel, coloured as the points.

A 5′ end inside an internal exon can be a promoter or a truncated read, so confirm internal exonic starts with an independent method.

Statistics

Reads from one sample are not independent, so a test with reads as its unit calls a difference between any two samples. IsoEnds summarises each sample first and tests over replicates.

The moderated t-test is limma's (empirical Bayes, robust). q is the Benjamini-Hochberg-adjusted P over the genes of a unit, or over the genes tested across units. Across units a gene must be measured in two thirds of the units.

The read-level test is still reported next to the replicate-level one, as a description only (q_reads_pooled in tails_gene_within_unit):

The genes of one unit tested over its three replicate pairs (A) and with every read as a unit (B).

Output

isoends_out/
  report.md          results, checks, parameters, tests, figures and table descriptions
  tables/            every table as Parquet and TSV
  figures/           PDF, SVG and PNG with captions
  provenance.json    inputs with SHA-256, versions, parameters
  logs/              counts at each step

report.md describes every table.

Python API

Tables are pandas DataFrames and plots are Matplotlib axes. docs/make_readme_figures.py draws the figures of this page, from a simulated experiment (--simulate FOLDER) or from a finished run of your own.

Command line

isoends init      [--out isoends.yaml]      write a configuration template
isoends validate  --config config.yaml      check the inputs and the sample sheet
isoends all       --config config.yaml      tails, apa, tss and the report
isoends tails | apa | tss | report          one stage
isoends isotracks --config config.yaml --gene NAME [--unit UNIT]
isoends demo      [--out DIR] [--unpaired]  a synthetic experiment, analysed

-j N summarises N runs in parallel; summaries are cached, so later stages and reruns start from them. --control, --treatment and --outdir override the config. Every parameter and its default is in the template that isoends init writes.

Development

git clone https://github.com/MustafaElshani/IsoEnds
cd IsoEnds
pip install -e ".[test]"
pytest

The tests check the statistics against R limma, statsmodels and SciPy, the site classes on hand-built gene models, and the whole pipeline on synthetic experiments with known effects.

IsoEnds is released under the MIT licence.