Skip to content
Ahituv-labPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

CypMPRA long read assignment

DOI

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.

Pipeline

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

1. System requirements

Software dependencies

  • Python ≥ 3.10
  • Python packages (installed automatically via pip):
    • pandas ≥ 1.5
    • pysam ≥ 0.20
    • biopython ≥ 1.80
    • tqdm ≥ 4.60
  • External dependency: pbmm2 ≥ 1.13 must be on PATH for the alignment step (install via conda install -c bioconda pbmm2).

Operating systems

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.

2. Installation guide

Instructions

# 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 .

Typical install time

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

3. Demo

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

Instructions to run

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.py

Expected output

test_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).

Expected run time for demo

Entry point Wall-clock
cypmpra run (full CLI pipeline) 7.1 s
python tests/run_test.py (library API) 8.2 s

4. Instructions for use

Full pipeline

cypmpra run reference.fasta reads.fasta -o results/

Individual steps

# 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 parameters

# 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 16

Output files

  • barcode_counts.csv — columns: reference, barcode, count
  • qc_summary.tsv — key metrics (mapped reads, barcodes per reference, ambiguous %)
  • assignments/<SUBLIB>/<SUBLIB>_assignments.tsv.gz — per-sublibrary barcode→reference mapping (MPRAsnakeflow-compatible)

Reproducing manuscript results (optional)

The barcode→CRS assignment files produced are the direct input to the downstream MPRAsnakeflow.

  1. Install CypMPRA and pbmm2 as above.
  2. Run cypmpra run on each sublibrary's reference FASTA and PacBio HiFi BAM (raw data deposited to IGVF).
  3. Pass the resulting assignments/<SUBLIB>/<SUBLIB>_assignments.tsv.gz files to MPRAsnakeflow using the config provided under IGVF_full_data/Code/MPRAsnakeflow/.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages