LongBarcodeQC

LongBarcodeQC is a command-line tool for analyzing combinatorial barcode libraries sequenced with Oxford Nanopore or other long read platforms. It aligns reads, extracts the multi-cloning site (MCS) region, scores each read against a barcode library, and generates an interactive HTML summary report.

Features

• Merges and preprocesses FASTQ input (one or multiple files)
• Aligns reads to a reference plasmid using minimap2
• Extracts the MCS region from each read using flanking sequence anchors (parasail Smith-Waterman)
• Scores each read against a barcode library and calls the best-matching barcode per position
• Detects restriction enzyme cut sites within the MCS
• Generates a self-contained HTML report with interactive plots (read length distributions, barcode heatmaps, z-score distributions, restriction site summaries)
• Outputs a compressed summary CSV with per-read barcode calls and QC metrics

Installation

LongBarcodeQC requires Python ≥ 3.10 and several external bioinformatics tools (minimap2, samtools, parasail, cutadapt). Install them with conda, which provides prebuilt binaries for all supported platforms including Apple Silicon and ARM Linux:

conda create -n longbarcodeqc -c conda-forge -c bioconda \
  python=3.12 minimap2 samtools parasail-python cutadapt
conda activate longbarcodeqc
pip install LongBarcodeQC

Or create the environment from the file in the repository:

conda env create -f environment.yml
conda activate longbarcodeqc
pip install LongBarcodeQC

To install the development version instead of the released one:

pip install git+https://github.com/ArpiarSaundersLab/LongBarcodeQC.git

After installation, the lbqc command will be available in your environment.

Usage

lbqc -i <fastq_pass_dir> -o <output_dir> -b <barcodes>

Required arguments

Barcode presets

Three built-in barcode libraries are included:

lbqc -i fastq_pass/ -o results/ -b EV

To use a custom barcode library, provide a path to a FASTA file where each entry is one barcode sequence and all headers are unique:

lbqc -i fastq_pass/ -o results/ -b /path/to/barcodes.fa

Optional arguments

Example

lbqc \
  -i /data/run01/fastq_pass/ \
  -o /results/run01_EV/ \
  -b EV \
  -r enzymes.txt \
  -S \
  -a

Output

Requirements

• Python ≥ 3.10
• minimap2 and samtools (external tools, installed with conda — see above)
• parasail and cutadapt ≥ 5.2 (compiled dependencies; installed with conda — see above)
• pandas, matplotlib, seaborn, jinja2, pyarrow, tqdm (pure-Python; installed automatically with pip)

cutadapt is only needed for the -T/--trim option, but it is installed as a dependency so trimming works out of the box.

Test data

Four small test datasets (3,000 reads each) are included in the GitHub repository under longbarcodeqc/test/data/ to verify an installation. They are not shipped in the PyPI package to keep the download small — clone the repository to use them:

git clone https://github.com/ArpiarSaundersLab/LongBarcodeQC.git
cd LongBarcodeQC

lbqc -i longbarcodeqc/test/data/PadlockSeq_AP/ -o /tmp/test_AP -b AP -l 300
lbqc -i longbarcodeqc/test/data/PadlockSeq_EV/ -o /tmp/test_EV -b EV -S -a -l 300
lbqc -i longbarcodeqc/test/data/TritSeq_AP/   -o /tmp/test_TS_AP -b TS -l 300
lbqc -i longbarcodeqc/test/data/TritSeq_EV/   -o /tmp/test_TS_EV -b TS -S -a -l 300

Each run writes a *_summary_report.html file that can be opened in a browser. Note that the output directory must be empty.

Citation

If you use LongBarcodeQC in your work, please cite:

Goode Z, et al. LongBarcodeQC. (manuscript in preparation)

License

MIT — see LICENSE.