Long-read barcode assignment pipeline for MPRA experiments. Assigns PacBio long-read sequences to reference CRS (cis-regulatory sequences) and extracts barcodes for downstream analysis with MPRAsnakeflow.
Step 1: align pbmm2 alignment of long reads → reference CRS (100% concordance)
Step 2: extract Barcode extraction from aligned BAM using a fixed upstream pattern
Step 3: filter Ambiguous barcode removal + per-sublibrary assignment files
- Python ≥ 3.10
- Python packages (installed automatically via
pip):pandas≥ 1.5pysam≥ 0.20biopython≥ 1.80tqdm≥ 4.60
- External dependency:
pbmm2≥ 1.13 must be onPATHfor the alignment step (install viaconda install -c bioconda pbmm2).
Linux is required - macOS and Windows users should run CypMPRA inside a Linux environment to run pbmm2:
- Tested configurations:
- Ubuntu 22.04 (WSL2, x86_64), Python 3.10–3.11, pbmm2 1.13.
- Ubuntu 22.04 (x86_64), Python 3.11.15, pbmm2 26.1.99, minimap2 2.26 — inside Orbstack on macOS.
# 1. Create a conda env with pbmm2 (external aligner)
conda create -n cypmpra --override-channels -c bioconda -c conda-forge \
pbmm2 python=3.11 pip -y
conda activate cypmpra
# 2. Install CypMPRA from the package directory
cd package/
pip install .Measured in a clean Ubuntu 22.04 amd64 container (Apple Silicon Mac via OrbStack + Rosetta, wall-clock):
| Step | Time |
|---|---|
| Miniforge install (conda bootstrap) | 44 s |
conda create … pbmm2 python=3.11 pip |
24 s |
pip install . (cypmpra + deps from PyPI) |
11 s |
| Total (fresh environment) | ≈ 80 seconds |
A small demo dataset (CEBP sublibrary, 10k long reads, 63 reference CRS) is bundled under package/tests/:
CEBPRE_reference.fasta— reference CRS (21 KB, 63 sequences)CEBPRE_10k.bam— 10,000 PacBio HiFi (Revio) reads (4.3 MB; kinetics and methylation tags stripped for distribution — alignment output is unchanged)CEBPRE_metadata.tsv.gz— sublibrary metadata
From the CLI (the canonical entry point, produces the full output set including qc_summary.tsv):
cd package/tests/
cypmpra run CEBPRE_reference.fasta CEBPRE_10k.bam -o test_output/Equivalently, via the bundled library-level test script:
cd package/tests/
python run_test.pytest_output/ after a successful run:
| File | Size | Contents |
|---|---|---|
alignment.bam |
73 MB | pbmm2-aligned, coordinate-sorted, filtered to best hit + 100% concordance |
alignment.bam.bai |
5 KB | BAM index |
barcode_counts.csv |
190 KB | 5,386 rows — columns: reference, barcode, count |
qc_summary.tsv |
221 B | 9 metrics (see below) |
assignments/CEBP/CEBP_assignments.tsv.gz |
34 KB | 5,073 rows — MPRAsnakeflow-compatible barcode→reference table |
Expected qc_summary.tsv (tab-separated):
| metric | value |
|---|---|
| total_reads_with_pattern | 6994 |
| unique_barcodes | 5227 |
| unique_references | 63 |
| barcodes_per_ref_median | 74 |
| barcodes_per_ref_min | 15 |
| barcodes_per_ref_max | 794 |
| ambiguous_barcodes | 313 |
| ambiguous_pct | 5.8 |
| kept_barcodes | 5073 |
Interpretation of the demo on the 10k-read input:
- 7,094 / 10,000 reads map at 100 % concordance (3,381 forward, 3,713 reverse).
- 6,994 / 7,094 mapped reads (98.6 %) contain the expected upstream barcode pattern.
- 5,386 unique barcode↔reference pairs; 313 (5.8 %) are dropped as ambiguous, leaving 5,073 kept assignments across all 63 references (median 74 barcodes/reference).
| Entry point | Wall-clock |
|---|---|
cypmpra run (full CLI pipeline) |
7.1 s |
python tests/run_test.py (library API) |
8.2 s |
cypmpra run reference.fasta reads.fasta -o results/# Step 1: Align (accepts BAM or FASTA input)
cypmpra align reference.fasta reads.bam -o aligned.bam
# Step 2: Extract barcodes (reads sequences directly from aligned BAM)
cypmpra extract aligned.bam -o barcode_counts.csv
# Step 3: Filter ambiguous barcodes & write per-sublibrary assignments
cypmpra filter barcode_counts.csv -o assignments/
# Preview filter output without writing
cypmpra filter barcode_counts.csv -o assignments/ --dry-run# Custom barcode pattern and length
cypmpra extract aligned.bam -o counts.csv \
--pattern "GCAAAGTGAACACATCGCTAAGCGAAAGCTAAG" \
--barcode-length 15
# FASTA fallback (only if BAM lacks embedded sequences)
cypmpra extract aligned.bam -o counts.csv --fasta reads.fasta
# Alignment with different preset
cypmpra align ref.fasta reads.bam -o out.bam --preset CCS -t 16barcode_counts.csv— columns:reference,barcode,countqc_summary.tsv— key metrics (mapped reads, barcodes per reference, ambiguous %)assignments/<SUBLIB>/<SUBLIB>_assignments.tsv.gz— per-sublibrary barcode→reference mapping (MPRAsnakeflow-compatible)
The barcode→CRS assignment files produced are the direct input to the downstream MPRAsnakeflow.
- Install CypMPRA and pbmm2 as above.
- Run
cypmpra runon each sublibrary's reference FASTA and PacBio HiFi BAM (raw data deposited to IGVF). - Pass the resulting
assignments/<SUBLIB>/<SUBLIB>_assignments.tsv.gzfiles to MPRAsnakeflow using the config provided underIGVF_full_data/Code/MPRAsnakeflow/.
MIT