Skip to content
XinglabPublic

About

No description, website, or topics provided.

Resources

Stars

10 stars

Watchers

5 watching

Forks

Latest commit

 

History

42 Commits

Folders and files

Repository files navigation

NanoTS

NanoTS is a deep-learning variant caller for SNP detection from long-read transcriptome sequencing. It supports both Oxford Nanopore (ONT) and Pacific Biosciences (PacBio) platforms, with pretrained models for each technology and library type.

  • ONT: cDNA and direct RNA (R10.4.1)
  • PacBio: HiFi MAS-seq cDNA

Update

v1.0.1

  • Added --contigs auto and explicit contig selection throughout calling and phasing, supporting RefSeq and numeric chromosome names.
  • Fixed region parsing and duplicate sites at region chunk boundaries, and prevented stale intermediate files from entering phased results. The default chr* selection is preserved.

Installation

Note: NanoTS is currently supported only on Linux systems.

Ensure you have Conda installed, then create and activate the nanoTS environment and install nanoTS:

git clone https://github.com/Xinglab/NanoTS.git
cd NanoTS
conda env create -f environment.yml             # create the nanoTS environment (takes ~1 minute)
conda activate nanoTS

# Install nanoTS in this conda environment:
pip install .                                    # installs in ~5 seconds

Alternatively, after activating the nanoTS environment, run the NanoTS runner directly:

python ./source/nanoTS-runner.py <subcommand> [OPTIONS]

Supported Platforms & Models

Platform Library Chemistry Model (unphased) Model (phased)
ONT cDNA R10.4.1 unphased_cDNA_nanopore_R104_HG002.pth phased_cDNA_nanopore_R104_HG002.pth
ONT direct RNA R10.4.1 unphased_dRNA_nanopore_R104_HG002.pth phased_dRNA_nanopore_R104_HG002.pth
PacBio Revio cDNA (MAS-seq) HiFi (CCS), MAS-seq unphased_MASseq_PacBio_Revio_HG002.pth phased_MASseq_PacBio_Revio_HG002.pth

Tip: Choose the model that matches your platform (ONT vs PacBio), library type (cDNA vs dRNA), and pipeline stage (unphased vs phased).


Usage

NanoTS is a command-line tool with the following subcommands:

Subcommand Description
bam Appends a numeric suffix to each BAM alignment QNAME to ensure uniqueness.
unphased_call Extracts SNP candidates + features from unphased BAM and performs unphased DL calling.
haplotype Performs haplotype phasing using a VCF, reference, and BAM file.
phased_call Extracts features from H1 & H2 BAM and performs phased DL calling.
clean Removes temporary files from the output directory.
full_pipeline All-in-one command that includes all of the above steps.

General Command Format

nanoTS <subcommand> [OPTIONS]

Subcommands & Arguments

1️⃣ bam

Append a numeric suffix to each BAM alignment QNAME based on its count per read, ensuring each alignment has a unique QNAME (e.g., read_1, read_2).

Required Arguments:

Argument Description
-i/--input Input sorted BAM file.
-o/--output Output BAM file with suffixed QNAMEs.

Optional Arguments:

Argument Default Description
--region None Target region (chr1 or chr1:1000-2000).

2️⃣ unphased_call

Extracts SNP candidates + features from unphased BAM and performs unphased deep learning-based SNP calling.

Required Arguments:

Argument Description
--bam Sorted and indexed BAM file.
--ref Reference genome FASTA file.
--outdir Output directory.
--model Pre-trained unphased model (.pth file).

Optional Arguments:

Argument Default Description
--threads 24 Number of CPU threads.
--region None Target region for analysis (chr1 or chr1:1000-2000).
--contigs Canonical chr* names Exact contig names, or auto for all contigs shared by BAM and FASTA.
--ALT 2 Minimum number of reads supporting the ALT allele.
--total 2 Minimum total read coverage required at a variant site.
--ratio 0.05 Minimum proportion of ALT reads relative to total coverage.
--depth 1000 Maximum number of reads sampled per variant (0 to disable limit).

🔹 Note: Increasing --ALT and --total thresholds may affect haplotype inference efficiency.


3️⃣ haplotype

Performs haplotype phasing using an input VCF, reference genome, and BAM file.

Required Arguments:

Argument Description
--vcf Input VCF file.
--ref Reference genome FASTA file.
--bam Input BAM file.
--outdir Output directory.

Optional Arguments:

Argument Default Description
-q/--QUAL 10 QUAL threshold to filter SNPs during haplotype phasing.
--contigs Canonical chr* names Exact contig names, or auto for all contigs shared by BAM and FASTA.

4️⃣ phased_call

Extracts features from H1 & H2 BAM and performs phased deep learning-based SNP calling.

Required Arguments:

Argument Description
--bam Sorted and indexed BAM file.
--ref Reference genome FASTA file.
--outdir Output directory.
--model Pre-trained phased model (.pth file).

Optional Arguments:

Argument Default Description
--threads 24 Number of CPU threads.
--depth 1000 Maximum reads per variant (0 to disable limit).
--contigs Canonical chr* names Exact contig names, or auto for all contigs shared by BAM and FASTA.

5️⃣ clean

Removes temporary files in the output folder.

Required Arguments:

Argument Description
--outdir Output directory to clean.

6️⃣ full_pipeline

Runs the entire NanoTS pipeline from a BAM file through final phased VCF output, then cleans up intermediate files.

Required Arguments:

Argument Description
--bam Input sorted & indexed BAM file.
--ref Reference genome FASTA file.
--model_unphased Path to unphased model (.pth file).
--model_phased Path to phased model (.pth file).
--outdir Output directory for all steps.

Optional Arguments:

Argument Default Description
--threads 24 Number of CPU threads.
--region None Target region for analysis (chr1 or chr1:1000-2000).
--contigs Canonical chr* names Exact contig names, or auto for all contigs shared by BAM and FASTA.
--ALT 2 Minimum number of reads supporting the ALT allele.
--total 2 Minimum total read coverage required at a variant site.
--ratio 0.05 Minimum proportion of ALT reads relative to total coverage.
--depth 1000 Maximum number of reads sampled per variant (0 to disable limit).
--hap_qual 10 QUAL threshold to filter SNPs during haplotype phasing.

Reference contig selection

By default, NanoTS analyzes chr1–chr22, chrX, and chrY that are present in the BAM. For references with other naming schemes, such as CHM13 RefSeq accessions or 1/2, add --contigs auto to analyze all contigs shared by the BAM and reference FASTA. This includes mitochondrial, alternate, or other contigs if they occur in both inputs. Contig names and lengths must agree between the BAM and FASTA; output VCFs retain the reference's exact names.

nanoTS full_pipeline \
  --bam cDNA.bam \
  --ref CHM13.fasta \
  --model_unphased model/unphased_cDNA_nanopore_R104_HG002.pth \
  --model_phased model/phased_cDNA_nanopore_R104_HG002.pth \
  --outdir cDNA_nanots \
  --contigs auto

To select specific contigs, use a space-separated list, for example --contigs NC_060925.1 NC_060926.1. A single contig or interval can also be selected with --region NC_060925.1 or --region NC_060925.1:1000-2000. If both options are supplied, the region's contig must be included in --contigs.

full_pipeline passes the selection through all calling and phasing steps. When running unphased_call, haplotype, and phased_call separately, supply the same --contigs selection to each command.


Example Workflow

Here’s an end-to-end example using NanoTS. The run takes about 5 minutes and requires at least 23 GB of memory.

cd example/

# Download and prepare the reference genome
wget https://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.fa.gz
gzip -d hg38.fa.gz
samtools faidx hg38.fa

# Align Nanopore reads to the reference genome
minimap2 -ax splice -ub -t 24 -k 14 -w 4 --secondary=no hg38.fa tutorial.fastq.gz | \
  samtools sort -o tutorial.bam # Note: requires at least 23 GB of memory
samtools index tutorial.bam
# Define output directory
outdir=nanoTS_result/
##################################
#### All-in-one step ####
nanoTS full_pipeline \
  --bam tutorial.bam \
  --ref hg38.fa \
  --model_unphased ../model/unphased_cDNA_nanopore_R104_HG002.pth \
  --model_phased   ../model/phased_cDNA_nanopore_R104_HG002.pth \
  --outdir $outdir \
  --threads 24 \
  --ALT 2 \
  --total 2 \
  --ratio 0.05 \
  --depth 1000 \
  --hap_qual 10
##################################
#### Separate steps ####
# Step 1: Suffix each BAM alignment QNAME by count per read
nanoTS bam \
  -i tutorial.bam \
  -o tutorial.qname.bam

# Step 2: Unphased SNP calling
nanoTS unphased_call \
  --bam tutorial.qname.bam \
  --ref hg38.fa \
  --threads 24 \
  --ALT 2 \
  --total 2 \
  --ratio 0.05 \
  --depth 1000 \
  --outdir $outdir \
  --model ../model/unphased_cDNA_nanopore_R104_HG002.pth

# Step 3: Haplotype phasing
nanoTS haplotype \
  --vcf ${outdir}unphased_predict.pass.vcf \
  --ref hg38.fa \
  --bam tutorial.qname.bam \
  --outdir $outdir \
  --QUAL 10

# Step 4: Phased SNP calling
nanoTS phased_call \
  --bam tutorial.qname.bam \
  --ref hg38.fa \
  --threads 24 \
  --depth 1000 \
  --outdir $outdir \
  --model ../model/phased_cDNA_nanopore_R104_HG002.pth

# Step 5: Clean temporary files
nanoTS clean \
  --outdir $outdir

Run NanoTS with Singularity from the NanoTS repository root (always bind host folders you read/write):

cd example/

SIF=../nanots_latest.sif # assumes the SIF is in the NanoTS repository root; adjust if needed
EXAMPLE_DIR="$(pwd)"
MODEL_DIR="$(cd ../model && pwd)"   # the model folder in this repository. Adjust if your model files live elsewhere

OUTDIR="$EXAMPLE_DIR/nanoTS_result"
mkdir -p "$OUTDIR"

# Bind BOTH the data dir and the model dir so the container can see them.
singularity exec -B "$EXAMPLE_DIR","$MODEL_DIR" "$SIF" \
  /opt/conda/envs/nanoTS/bin/nanoTS full_pipeline \
    --bam "$EXAMPLE_DIR/tutorial.bam" \
    --ref "$EXAMPLE_DIR/hg38.fa" \
    --model_unphased "$MODEL_DIR/unphased_cDNA_nanopore_R104_HG002.pth" \
    --model_phased  "$MODEL_DIR/phased_cDNA_nanopore_R104_HG002.pth" \
    --outdir "$OUTDIR" \
    --threads 24 \
    --ALT 2 --total 2 --ratio 0.05 --depth 1000 --hap_qual 10

Output Files

Primary output files

  • unphased_predict.pass.vcf — Filtered SNP calls in VCF format generated by the unphased_call step.
  • phased_predict.pass.vcf — Filtered SNP calls in VCF format generated by the phased_call step.

Supporting output files

  • unphased_predict.vcf — Unfiltered SNP calls in VCF format generated by the unphased_call step, including homozygous reference sites.
  • phased_predict.vcf — Unfiltered SNP calls in VCF format generated by the phased_call step, including homozygous reference sites.
  • unphased_predict.txt — Plain-text version of unfiltered SNP calls from the unphased_call step, including homozygous reference sites.
  • phased_predict.txt — Plain-text version of unfiltered SNP calls from the phased_call step, including homozygous reference sites.
  • unphased_predict.pass.txt — Plain-text version of filtered SNP calls generated by the unphased_call step.
  • phased_predict.pass.txt — Plain-text version of filtered SNP calls generated by the phased_call step.

All results are stored in the specified --outdir directory.


Computational Resource Requirements

The runtime and memory usage of NanoTS scale with the number of variant sites analyzed.

For the whole-transcriptome ONT cDNA dataset used in this study:

  • Default settings: ~126 GB peak memory and ~21 hours of runtime.
  • With --ALT 5: ~21 GB peak memory and ~8 hours of runtime.

For the whole-transcriptome ONT dRNA dataset used in this study:

  • Default settings: ~14 GB peak memory and ~6 hours of runtime.
  • With --ALT 5: ~7 GB peak memory and ~5 hours of runtime.

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.


Contact

For questions, bug reports, or feature requests, contact:

📧 Zelin Liu – liuz6@chop.edu

About

No description, website, or topics provided.

Resources

Stars

10 stars

Watchers

5 watching

Forks

Releases

Packages

Contributors

Languages