isONcorrect

isONcorrect error-corrects Oxford Nanopore cDNA reads. It handles highly variable coverage and exon variation within reads, and leverages regions shared between reads from different isoforms to reach low error rates even for low-abundance transcripts. See the paper.

Doing de novo transcriptome reconstruction? isONclust, isONcorrect and isONform are one workflow — isONpipe installs all three and runs them with one command.

v0.2.0 — isONcorrect is now written in Rust

Same command line, so existing pipelines do not need editing. About 10x faster, uses less memory, and more accurate — a bug in region selection meant every previous version corrected fewer regions than it should have. Corrected output therefore differs from earlier releases.

The Python implementation is still here but is deprecated, kept as the reference the Rust version is verified against. Details, numbers, and the removed flags: CHANGELOG.md.

Install

Needs a Rust toolchain (1.85+). No Rust? curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

git clone https://github.com/ksahlin/isONcorrect.git
cd isONcorrect
cargo build --release --manifest-path rust/Cargo.toml

That builds isONcorrect and run_isoncorrect into rust/target/release/. Copy them onto your PATH.

Test the installation

rust/target/release/isONcorrect --fastq test_data/isoncorrect/0.fastq --outfolder /tmp/isoncorrect_test

Should take less than a second and writes 100 corrected reads to /tmp/isoncorrect_test/corrected_reads.fastq.

Rather not build? Prebuilt binaries are attached to release v0.2.0. For Linux take musl if your glibc is older than 2.34 (CentOS 7, RHEL 8, Ubuntu 20.04) or you would rather not check, gnu otherwise.

Still want the Python version? (deprecated)

pip install isONcorrect && conda install -c bioconda spoa

Full pipeline

isONcorrect corrects one gene cluster at a time, so the usual workflow is pychopper for full-length reads → isONclust to group them into genes → isONcorrect per cluster.

isONpipe installs those tools together with isONform, which reconstructs isoforms from the corrected reads, and runs the whole thing:

isONpipe install
isONpipe run --reads reads.fq --outfolder out --t 20

To install and run the steps yourself instead — isONclust and pychopper are separate tools:

conda create -n isoncorrect python=3.9 pip && conda activate isoncorrect
pip install isONclust
conda install -c bioconda "hmmer>=3.0" "pychopper>=2.0"

Then either run the whole thing with one command:

./scripts/correction_pipeline.sh raw_reads.fq outfolder 20   # reads, outdir, cores

or the steps yourself:

cdna_classifier.py raw_reads.fq out/full_length.fq -t 20

isONclust --t 20 --ont --fastq out/full_length.fq --outfolder out/clustering
isONclust write_fastq --N 1 --clusters out/clustering/final_clusters.tsv \
          --fastq out/full_length.fq --outfolder out/clustering/fastq_files

run_isoncorrect --t 20 --fastq_folder out/clustering/fastq_files --outfolder out/correction

cat out/correction/*/corrected_reads.fastq > out/all_corrected_reads.fq

Reads need not be full-length, but running pychopper first is advised for downstream analysis.

Output is one corrected_reads.fastq per cluster with the input headers. Note the quality string is not real — it is + repeated to the length of the sequence, as in the Python version.

Useful flags (--help for the rest): --split_wrt_batches cuts runtime when isONclust produces a few very large clusters; --split_mod n --residual i spreads run_isoncorrect across n nodes; --k 9 --w 10 --max_seqs 1000 reproduces the paper's settings rather than the faster defaults.

Paper data

The result data behind the paper used to be committed here, making the repo ~2.4 GB to clone. It is now on Zenodo — https://zenodo.org/records/21920617 — and tools/fetch_data.sh restores and checksums it into data/. You only need it to regenerate the paper figures under paper/.

Because the data was stripped from history, commit SHAs from before the rewrite no longer resolve.

Credits

Please cite:

Sahlin, K., Medvedev, P. Error correction enables use of Oxford Nanopore technology for reference-free transcriptome analysis. Nat Commun 12, 2 (2021). https://doi.org/10.1038/s41467-020-20340-8

Licence

GPL v3.0, see LICENSE.txt.