DadaNanoBC: Nanopore barcoding pipeline

This R package provides functions for clustering and validating amplicon sequencing data from specimen barcoding projects using Oxford Nanopore. Although not tested, it should work for PacBio data as well.

• sample demultiplexing of pooled reads
• inferring barcode sequences using a DADA2-based clustering strategy to accurately resolve haplotypes/polymorphic sequences
• automatic taxonomic assignents and recognition (down-ranking) of contaminant taxa
• detailed output files (comprehensive Excel table for curation, HTML report, BAM alignment files)

See here for a comprehensive explanation

A fully-fledged {targets} pipeline is provided for simple execution of a standard workflow (see below).

Table of contents:

• What type of data does it work with?
• System requirements
• Preparation: lab work and basecalling
• Installing and using the package
• Running the {targets} pipeline
• Running in the bash console
• Required software
• Useful references

What type of data does it work with?

• Basecalled amplicon reads with sample-specific tags attached to both ends (dual-indexed)
• Reads of sufficient quality (R10.4 chemistry)
• Amplicon lengths of 0.5-1.5kb have been successfully tested
• Works with fixed- and variable-length amplicons from different taxonomic groups that can be multiplexed and analyzed separately
• different taxonomic database types can be auto-downloaded (more may be implemented in the future)

System requirements

• An UNIX environment (Linux, OS X or Windows with WSL2) with Bash
• An R installation
• Four command-line programs (see required software); the package can always be installed without these, but error messages will appear when calling functions that rely on missing components.

If basecalling of the Nanopore data has not yet been done: an Nvidia GPU with Cuda support (details here).

Preparation: lab work and basecalling

1. Primer design (example report)
2. PCR, library preparation and sequencing
3. Basecalling

Installing and using the package

devtools::install_github("markschl/DadaNanoBC")

The package documentation is found here.

The package provides a mix of lower and higher level functions, The core clustering function is infer_barcode (detailed explanation here). The high-level pipeline functions all have names starting with do_ (e.g. do_trim_demux).

Running the {targets} pipeline

In the R console (for running in Bash, see below):

setwd("path/to/pipeline")
DadaNanoBC::init_pipeline()

Some files are created, some need to be still placed

path/to/pipeline/
 ├─ _targets.R               Pipeline R code
 └─ analysis/
    ├─ meta-ITS5-ITS4.xlsx   Metadata template (modify & rename to 'meta.xlsx')
    ├─ config.yaml           Pipeline configuration (modify)
    └─ reads.fastq.gz    <- Place base-called nanopore sequences here

There may also be warnings about missing software, which have to be handled (see required software).

Next:

• Modify the example metadata file meta-ITS5-ITS4.xlsx to contain your primer sequences and sample metadata, and rename it to meta.xlsx
• Copy or move your base-called sequencing reads to reads.fastq.gz
• Adapt config.yaml to your needs; at the minimum, the taxonony section needs to contain the correct taxonomic database.

  Consider starting with a reduced read depth as in the example configuration (max_sample_depth/max_contam_sample_depth)

Run the pipeline:

targets::tar_make()

Optional: Modify the number of parallel processes before calling tar_make: Sys.setenv('DadaNanoBC_cores' = 8)

Output

Some more files will appear in the analysis directory:

• report.html (example report): detailed HTML report, useful for troubleshooting
• report.xlsx: Excel report with sequences and taxonomic assignments, which can be inspected for issues (see curation)
• separate_alignments (and/or top_alignments, alignments depending on configuration): aligned sequencing reads in BAM format, may be imported into sequence viewing/editing software such as Geneious/CLC Workbench/UGENE/IGV, etc.
• tmp: contains temporary (but sometimes useful) data such as the demultiplexed FASTQ sample files (sometimes separate_alignments with many small BAM files, depending on the configuration); if not needed you may delete the files

Inspect the HTML report for anomalies, maybe adjust some other settings then re-run with at higher depth (adjust/remove max_sample_depth/max_contam_sample_depth)

Curation

Excel report contains sequences and issue flags, which might have to be addressed before exporting the sequences.

See curation tutorial

Running a different analysis

Prepare another directory with an appropriate meta.xlsx, reads.fastq.gz and config.yaml. Then, set the path and run the analysis. Taxonomic databases and other files in the taxdb directory is reused.

Sys.setenv('DadaNanoBC_ANALYSIS_DIR' = 'path/to/dir')
targets::tar_make()

Running in the bash console

Install the package if not already done

Rscript -e 'devtools::install_github("markschl/DadaNanoBC", upgrade = "never")'

Initialize a directory where the pipeline is run

cd path/to/pipeline
Rscript -e 'DadaNanoBC::init_pipeline(bash = TRUE)'

Then make sure there are the files meta.xlsx, reads.fastq.gz and config.yaml present in the analysis directory as described above.

Run the pipeline (for the default analysis directory, may be changed):

./infer_barcodes

Additional settings can be added, as in this more complicated/realistic example (see also custom program location):

./infer_barcodes cores=8 vsearch=path/to/vsearch

Different analysis in another directory:

./infer_barcodes ANALYSIS_DIR=path/to/analysis

Required software

The following tools are required:

• seqtool for primer trimming/demultiplexing
• samtools and minimap2 for dealing with alignments
• VSEARCH for sequence-based taxonomic assignments

The above call to init_pipeline() checks for available software and gives the URLs of missing software. The following does the same:

DadaNanoBC::check_system_requirements()

The message points to the download locations of missing tools. Samtools, minimap2 and VSEARCH are available from different sources:

Debian/Ubuntu (including Windows WSL2 with these OSes):

sudo apt install -y samtools minimap2 vsearch

OS X with Homebrew:

brew install samtools minimap2 vsearch

Conda package manager (e.g. Conda-forge) (run in the bash console):

conda install -y -n DadaNanoBC -c bioconda samtools minimap2 vsearch
conda activate DadaNanoBC
./infer_barcodes analysis_dir [options]

Instructions for downloading Seqtool are given on the Github site.

Custom program location

R needs to know about the tool's locations. If not placed at a standard location, either the PATH environment variable needs adjustment, or the paths can be communicated to DadaNanoBC.

In R (example with VSEARCH):

DadaNanoBC::set_global_opts(vsearch = '~/Downloads/vsearch-2.30.2-linux-x86_64/bin/vsearch')
tar_make()

In the Bash console, simply add program=... after the infer_barcodes call:

cd path/to/pipeline
./infer_barcodes analysis WORKERS=8 vsearch=~/Downloads/vsearch-2.30.2-linux-x86_64/bin/vsearch

Useful references

• Srivathsan & Meier (2024)
• Hebert et al. (2024) barcoded up to 100k samples with a single MinION run.
• ONT barcoding efforts by the MycoMap network (see also methods description) (software used: NGSpeciesID)