WarpDemuX

Important Info: Please refer to "Available Models" below for the specific barcodes to be used for RNA004 (and Nano-tRNAseq). Currently, we do not support all 12 barcodes for RNA004 experiments.

WarpDemuX is an ultra-fast and high-accuracy adapter-barcoding and demultiplexing tool for Nanopore direct RNA sequencing. It enhances speed and accuracy through:

• Fast processing of raw signals
• Light-weight machine learning algorithms
• Optimized barcode sets
• Real-time enrichment capabilities through barcode-specific adaptive sampling

WarpDemuX supports the current (SQK-RNA004) sequencing chemistry (SQK-RNA002 is deprecated).

Available models

Model naming convention

The model name is composed of the following parts:

• WDX[n_barcodes][alternative-barcode-set-indicator]_[chemistry]_[version]

When unsure which model to use, we recommend using the default barcode set models. These are the best performing barcode subsets for the respective set sizes.

• WDX4, WDX6, WDX10, etc.: default barcode sets
• WDX4b, WDX4c, etc.: alternative barcode sets

To see which barcodes are used per model, see the column Barcodes Used in the respective model table.

Default (=recommended) barcode sets for RNA004

| Model | Number of samples | WarpDemuX barcodes | |-------|-------------------|-------------------| | WDX4 | 4 | 3 4 5 7 | | WDX6 | 6 | 4 5 6 7 11 12 | | WDX10 | 10 | 3 4 5 6 7 8 9 10 11 12 |

Standard WarpDemuX: default (mRNA) protocol

WarpDemuX models for the current sequencing chemistry (RNA004) are optimized for reads with poly(A) tails. For datasets with many short poly(A) tails, you have two options:

1. Enable LLR fallback, see Advanced Usage.
2. Switch to LLR detection entirely (slower but better handles short poly(A) tails)

| Model Name | Chemistry | Library Type | # Samples | Barcodes Used | |------------|-----------|--------------|-----------|---------------| | WDX4_rna004_v1_0 | RNA004 | polyA RNA | 4 | WDX_bc03, WDX_bc04, WDX_bc05, WDX_bc07 | | WDX4b_rna004_v1_0 | RNA004 | polyA RNA | 4 | WDX_bc04, WDX_bc05, WDX_bc07, WDX_bc11 | | WDX4c_rna004_v1_0 | RNA004 | polyA RNA | 4 | WDX_bc04, WDX_bc05, WDX_bc06, WDX_bc11 | | WDX6_rna004_v1_0 | RNA004 | polyA RNA | 6 | WDX_bc04, WDX_bc05, WDX_bc06, WDX_bc07, WDX_bc11, WDX_bc12 | | WDX10_rna004_v1_0 | RNA004 | polyA RNA | 10 | WDX_bc03, WDX_bc04, WDX_bc05, WDX_bc06, WDX_bc07, WDX_bc08, WDX_bc09, WDX_bc10, WDX_bc11, WDX_bc12 |

<span style="color:gray"> <details> <summary>RNA002 models</summary>

[DEPRECATED MODELS]

As RNA002 is deprecated, the following models are no longer supported (moved to DEPRECATED folder).

| Model Name | Chemistry | Library Type | # Samples | Barcodes Used | |------------|-----------|--------------|-----------|---------------| | WDX-DPC_rna002_v0_4_4 | RNA002 | polyA RNA | 4 | Original DeePlexiCon barcodes | | WDX4_rna002_v0_4_4 | RNA002 | polyA RNA | 4 | WDX_bc04, WDX_bc05, WDX_bc06, WDX_bc08 | | WDX6_rna002_v0_4_4 | RNA002 | polyA RNA | 6 | WDX_bc01, WDX_bc03, WDX_bc05, WDX_bc06, WDX_bc07, WDX_bc11 | | WDX8_rna002_v0_4_4 | RNA002 | polyA RNA | 8 | WDX_bc01, WDX_bc03, WDX_bc05, WDX_bc06, WDX_bc07, WDX_bc09, WDX_bc11, WDX_bc12 | | WDX10_rna002_v0_4_4 | RNA002 | polyA RNA | 10 | WDX_bc01, WDX_bc02, WDX_bc03, WDX_bc05, WDX_bc06, WDX_bc07, WDX_bc09, WDX_bc10, WDX_bc11, WDX_bc12 | | WDX12_rna002_v0_4_4 | RNA002 | polyA RNA | 12 | All 12 WDX barcodes |

</details> </span>

WarpDemuX-tRNA: Nano-tRNAseq protocol

ATTENTION: The WarpDemuX-tRNA is developed for the Nano-tRNAseq protocol and does not work with data using the Thomas splint adapter.

| Model Name | Chemistry | Library Type | # Samples | Barcodes Used | |------------|-----------|--------------|-----------|---------------| | WDX4_tRNA_rna004_v1_0 (Recommended) | RNA004 | tRNA (Nano-tRNAseq) | 4 | WDX_bc03, WDX_bc04, WDX_bc05, WDX_bc07 | | WDX4b_tRNA_rna004_v1_0 | RNA004 | tRNA (Nano-tRNAseq) | 4 | WDX_bc04, WDX_bc05, WDX_bc07, WDX_bc11 |

We recommend using the WDX4_tRNA_rna004_v1_0 model for Nano-tRNAseq data, which has improved performance compared to the WDX4b_tRNA_rna004_v1_0 model, especially in terms of recovery:

| WDX_bc | Precision | Recall | Recovery | |---------:|:------------|:------------|:-------------| | 4 | 0.993 | 0.988 | 95.210 (+3%) | | 5 | 0.982 (-1%) | 0.991 | 98.890 | | 7 | 0.991 (+1%) | 0.991 | 98.780 (+3%) | | 3 (vs 11) | 0.995 (+1%) | 0.992 (+1%) | 99.380 (+7%) |

<caption><b>WDX-tRNA performance metrics for WDX4_tRNA_rna004_v1_0 vs WDX4b_tRNA_rna004_v1_0.</b></caption>

WarpDemuX-rRNA: rRNAseq / sequence specific protocols

| Model Name | Chemistry | Library Type | # Samples | Barcodes Used | |------------|-----------|--------------|-----------|---------------| | WDX4_rRNA_rna004_v1_0 | RNA004 | rRNA / sequence specific | 4 | WDX_bc03, WDX_bc04, WDX_bc05, WDX_bc07 |

Barcodes

WarpDemuX uses custom barcode sequences embedded within the RTA (Reverse Transcription Adapter) during library preparation.

Available Barcodes

| Barcode ID | Barcode sequence | |------------|-------------------| | Barcode 1 | TTTTTACTGCCAGTGACT | | Barcode 2 | AGGGGAGAGAGCCCCCCC | | Barcode 3 | CACGTCATTTTCCACGTC | | Barcode 4 | GGAGGCCAGGCGGACCGA | | Barcode 5 | ACGGACCTTTTGACTTAA | | Barcode 6 | TATTGCATACTGCGCCGC | | Barcode 7 | CCACGGAGGGAGGATTGG | | Barcode 8 | TTACCGGCAGTGACGGAC | | Barcode 9 | CGAGATTGCATCCCCCCC | | Barcode 10 | TACCACCTGCCGGCGGCC | | Barcode 11 | GCCCGCCGGGGGAGAAGC | | Barcode 12 | TTTTTTTTACCGGCAGTT |

To create the barcoded RTA's you need to order the respective oligos. For example:

| Oligo Name | Sequence 5'-3' | |------------|-------------------| | WDX_bc01_A | /5Phos/GGTTTTTACTGCCAGTGACTGGTAGTAGGTTC | | WDX_bc01_B | GAGGCGAGCGGTCAATTTTAGTCACTGGCAGTAAAAACCTTTTTTTTTT | | WDX_bc02_A | /5Phos/GGAGGGGAGAGAGCCCCCCCGGTAGTAGGTTC | | WDX_bc02_B | GAGGCGAGCGGTCAATTTTGGGGGGGCTCTCTCCCCTCCTTTTTTTTTT | | WDX_bc03_A | /5Phos/GGCACGTCATTTTCCACGTCGGTAGTAGGTTC | | ... (etc.) | ... (etc.) |

For detailed information about barcode design, optimization, and performance characteristics, please refer to our manuscript.

Quick Start

Installation takes approximately 10 minutes and requires gcc to be available in PATH.

# Clone this repository with the adapt submodule
git clone --recursive https://github.com/KleistLab/WarpDemuX.git [path/to/store/WarpDemuX]

# Create a new conda environment using the environment.yml file
# We advise to use mamba instead of conda for speed
mamba env create -n WDX -f [path/to/store/WarpDemuX]/environment.yml
mamba activate WDX

# install in editable mode
pip install -e [path/to/store/WarpDemuX]

# For barcode-specific adaptive sampling
cd [path/to/store/WarpDemuX]
pip install -e '.[live-demux]'

The first time you run WarpDemuX, gcc has to be available in your system. When working on a HPC, consider adding/loading the gcc module.

Using a different branch

After switching to a different branch, you need to update the submodules.

For example, to switch to the dev branch:

git switch dev && git submodule update

To switch back to the main branch:

git switch main && git submodule update

Non-editable mode

WarpDemuX depends on ADAPTed, our tool for adapter and poly(A) tail detection. ADAPTed is included as a submodule for now. To make sure WDX can access this module correctly, you need to install WDX in editable mode. See above.

If you don't wish to install in editable mode, you can install the warpdemux and adapted packages separately:

cd [path/to/store/WarpDemuX]
pip install .

cd warpdemux/adapted
pip install .

If you decide for this approach, you need to reinstall both packages whenever you switch branches.

Basic Usage

conda activate WDX
warpdemux demux -i INPUT [INPUT ...] -o OUTPUT -m MODEL_NAME -j NCORES

Where:

• INPUT: Pod5 file(s) or directory(s) to demultiplex
• OUTPUT: Path for run output folder
• MODEL_NAME: Model to use (see Models section)
• NCORES: Number of cores for parallel processing

For further instructions and options, run warpdemux --help and warpdemux demux --help.

Finalizing the demultiplexing

After running the demultiplexing, you can use the barcode predictions to create barcode-specific pod5 files using the pod5 package.

First, unzip the predictions output and remove the '#' character from the start of the header:

gunzip -c PREDICTIONS_FILE.csv.gz > PREDICTIONS_FILE.csv # unzip
sed -i '1s/#read_id/read_id/' PREDICTIONS_FILE.csv # remove '#' from header

Optionally, if the model used for demultiplexing has a noise class, you can filter out the predictions assigned to the noise class (-1):

awk -F, '$2 != -1' PREDICTIONS_FILE.csv > PREDICTIONS_FILE_filtered.csv
mv PREDICTIONS_FILE_filtered.csv PREDICTIONS_FILE.csv

Then, create barcode-specific pod5 files:

pod5 subset POD5_FILE [POD5_FILE ...] --table PREDICTIONS_FILE.csv --columns predicted_barcode --template "{predicted_barcode}.subset.pod5" 

Where:

• POD5_FILE: Pod5 f