bagpiper

Bagpiper is an open-source Rust command-line tool for processing barcoded long-read single-cell RNA sequencing data generated by the BenchDrop-seq platform. It supports both Oxford Nanopore long-read data and matched 3' biased Illumina short-read data produced from the same barcoded cDNA pool.

Bagpiper performs:

• cellular barcode identification and error correction
• UMI-aware read grouping
• isoform- and gene-level single-cell quantification using an expectation-maximization framework

Features

• Optimized for Oxford Nanopore long-read error profiles
• Isoform-aware quantification without transcript collapsing
• Parallel throughout, with gzipped MatrixMarket output and no runtime dependencies beyond the aligner
• Compatible with standard transcriptome references

Workflow

Bagpiper is two commands with a transcriptome alignment in between:

1. barcode: assign and error-correct the four-segment cell barcode and the UMI per read, then emit the cDNA as gzipped FASTA with the cell and UMI in the record id (>readid_CB_UMI).
2. align the barcoded cDNA to a transcriptome with an external aligner (minimap2 for Nanopore).
3. count: deduplicate molecules and quantify per cell over the equivalence classes, writing a gzipped count matrix. count consumes the aligned BAM directly; the equivalence-class and deduplication steps are fused into it.

Install

Build from source (Rust 2021):

git clone https://github.com/avisrilab/bagpiper.git
cd bagpiper
cargo build --release

The binary is target/release/bagpiper. Run the test suite with cargo test.

Quickstart

Bagpiper is invoked through subcommands:

bagpiper --help
bagpiper <SUBCOMMAND> --help

1. Barcode preprocessing

Nanopore (single FASTQ):

bagpiper barcode --r1 nanopore.fastq.gz --whitelist whitelist.csv --nanopore -o out/barcode

Illumina (paired FASTQ):

bagpiper barcode --r1 read1.fastq.gz --r2 read2.fastq.gz --whitelist whitelist.csv -o out/barcode

2. Align the barcoded reads to a transcriptome (Nanopore example):

minimap2 -ax map-ont --for-only -N 200 -p 0.9 transcriptome.fa \
    out/barcode/passed.bcd.nanopore.fa.gz | samtools view -b -o aligned.bam

3. Count matrix from the aligned BAM:

bagpiper count --b1 aligned.bam -o out/counts

This writes matrix.mtx.gz, barcodes.tsv.gz, and features.tsv.gz into out/counts.

Command reference

bagpiper barcode

Assign cell barcodes and UMIs from FASTQ.

Required:

• --r1 <READ1>: input FASTQ (Nanopore) or Read 1 FASTQ (Illumina)
• --whitelist <CSV>: barcode whitelist, one column per barcode segment
• -o, --output <DIR>: output folder

Optional:

• --r2 <READ2>: Read 2 FASTQ (Illumina only)
• --nanopore: set this flag for Nanopore input

bagpiper count

Count matrix from a name-grouped, transcriptome-aligned BAM. Exact-deduplicates molecules (cell + UMI

• transcript set), runs a length-weighted per-cell EM, and writes the gzipped matrix with barcode and feature sidecars.

Required:

• --b1 <BAM>: name-grouped, transcriptome-aligned BAM
• -o, --output <DIR>: output folder

Versions

• 0.1.0 reproduces the published V4 count matrix: identical cell set and entries matching to the aligner-version floor.
• 0.1.1 adds three barcode and deduplication correctness fixes on top of 0.1.0: reject edit-1-ambiguous barcodes instead of guessing, key deduplication on the transcript set rather than alignment order, and normalize the UMI strand so both strands of a molecule collapse together.

Notes and expected inputs

• count expects a name-grouped BAM produced by an external aligner (minimap2 for Nanopore). A synthetic whitelist ships under tests/whitelist/.
• Illumina mode targets matched 3' biased short-read libraries generated from the same barcoded cDNA pool.

Citation

If you use bagpiper, please cite the associated BenchDrop-seq manuscript.

License

See LICENSE.