isoforge 1.0.0

IsoForge uses a hypergraph, rather than a splice graph, to preserve transcript models and the reads behind them. Each long read is kept whole, with its intron chain and both ends, as one hyperedge. From Oxford Nanopore or PacBio RNA-seq, a single run reports annotated and novel isoforms with their transcription start and poly(A) sites, read counts per sample (annotated small RNAs included) and gene fusions.

Installation

pip install isoforge

IsoForge needs Python 3.10 or later and is tested on Linux (x86-64), where pip installs a ready-built package: minimap2 and htslib are compiled in, so there is nothing else to install. On other systems pip builds IsoForge from source, which takes a few minutes and needs Rust 1.85 or later and the C build tools (a compiler, make, cmake).

To build from this repository with conda:

git clone https://github.com/MustafaElshani/IsoForge.git
cd IsoForge
bash install.sh              # creates the conda environment "isoforge" and builds into it
conda activate isoforge

bash install.sh --help shows the other ways to call the script. The repository as it stands is installed with pip install git+https://github.com/MustafaElshani/IsoForge.git; the conda environment of environment.yml has what that build needs (conda env create -f environment.yml, then conda activate isoforge).

Quick start

IsoForge needs the reads, the genome and the annotation:

# from FASTQ
isoforge annotate --reads Control_1.fastq.gz Treated_1.fastq.gz \
    --genome hg38.fa --annotation gencode.v49.annotation.gtf --o results/project

# or from sorted BAM files
isoforge annotate --bam Control_1.bam Treated_1.bam \
    --genome hg38.fa --annotation gencode.v49.annotation.gtf --o results/project

FASTQ files are aligned with the minimap2 built into IsoForge. The annotation is indexed on the first run, beside the GTF, and the index is used again after that. Every output is written; nothing else has to be set.

If your genome has a minisplice score table (human GRCh38: human-GRCh38.v4.tsv.gz), add --splice_scores human-GRCh38.v4.tsv.gz. It is used to place and check novel splice sites.

isoforge <command> --help shows the main options of a command, and isoforge annotate --help-all every option.

Input

Reads

Give one file per sample: FASTQ or FASTA, gzipped or not, with --reads, or sorted BAM with --bam. The samples are named after their files unless --names gives the names. For FASTQ, set the library type:

--oriented (-uf) is only for reads that run in the transcript's direction. --write_bam keeps the alignments IsoForge makes, which IsoTracks reads.

BAM files of your own must be aligned to the genome with minimap2, sorted and indexed:

minimap2 -ax splice --junc-bed annotation.bed hg38.fa reads.fastq.gz | samtools sort -o sample.bam
samtools index sample.bam

annotation.bed is made with paftools.js gff2bed annotation.gtf; --junc_bed gives the same file to the built-in aligner.

Poly(A) tail lengths are read from the pt:i tag when the reads carry it, and measured in the soft clip otherwise. To keep Dorado's tag, convert with samtools fastq -T pt and add --copy_comment (minimap2 -y).

Sample sheet

For many samples, --config takes a CSV in place of --reads or --bam, with one sample per line: name, description, platform and file.

Control_rep1,Control replicate 1,ONT,/data/control_rep1.fastq.gz
Control_rep2,Control replicate 2,ONT,/data/control_rep2.fastq.gz
Treated_rep1,Treated replicate 1,ONT,/data/treated_rep1.fastq.gz
Treated_rep2,Treated replicate 2,ONT,/data/treated_rep2.fastq.gz

The part of a sample name before the first underscore is the condition (Control, Treated).

Output

With --o results/project:

--hypergraph also writes the read hypergraph of the reported models (project_isoforge_hypergraph.tsv) and tests of which exons are spliced together in the same molecules (project_isoforge_coordination.tsv).

Options

The defaults are meant to be run as they are. These are the options most often changed:

Filtering a run again

A run kept with --keep-db can be filtered with other settings without reading the alignments again:

isoforge post --database results/project_isoforge_db --annotation gencode.v49.annotation.gtf \
    --genome hg38.fa --minCount 10 --o results/project_min10

isoforge post takes the filtering options of isoforge annotate. Give it --genome and --splice_scores as in the run.

Downstream analysis

IsoForge_Sqanti3, IsoTracks and IsoEnds are companion tools of IsoForge. SQANTI3 itself takes the GTF as it is:

python sqanti3_qc.py --isoforms results/project_isoforge.gtf \
    --refGTF gencode.v49.annotation.gtf --refFasta hg38.fa -d results/sqanti3 -o project

Citation

The IsoForge manuscript is in preparation. Until it is out, please cite this repository:

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

License

MIT, see LICENSE.