PeakATail

Quick install

System prerequisites

# Debian/Ubuntu
sudo apt-get install samtools bedtools
# macOS (Homebrew)
brew install samtools bedtools

Python version

Install from source

git clone https://github.com/BMGLab/PeakATail.git
cd PeakATail
# Create and activate a virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
# Install with uv (recommended — matches the development environment)
pip install uv
uv pip install -e .
# Or with plain pip
pip install -e .

Quick start

# Step 1: copy the example config and edit paths
cp example.yaml my_run.yaml
# Edit my_run.yaml — set datasets[].bams, gtf, seqlen, cb_len, barcode_tag
# Step 2: run the full pipeline (peak calling → annotation → clustering)
uv run ema run --config my_run.yaml --threads 4
# Step 3: differential APA between every cluster pair
uv run ema switch diff \
 -i peakatail_runs/<run>/per_dataset/<ds>/clusters.h5ad \
 --pasbed peakatail_runs/<run>/per_dataset/<ds>/pasbed.bed \
 --strategy fisher
# Step 4: 3'UTR length quantification across clusters
uv run ema switch length \
 -i peakatail_runs/<run>/per_dataset/<ds>/clusters.h5ad \
 --strategy classic

peakatail_runs/emaout_20240501_143022/
 run_config.json # full resolved parameters
 peakatail_<ts>.log # structured run log
 per_dataset/
 <dataset_id>/
 raw/ # pre-filter BEDs and matrices
 posbed.bed # filtered positive-strand PAS BED
 negbed.bed # filtered negative-strand PAS BED
 pasbed.bed # combined filtered PAS BED (both strands)
 filtered_cb.tsv # barcodes that passed min_read filter
 pas_gene.tsv # PAS-to-gene mapping table
 annotatedpas.bed # pasbed.bed extended with gene_id column
 annotated_matrix.mtx # post-annotation count matrix (MatrixMarket)
 annotated_pas_ids.tsv # row index for annotated_matrix.mtx
 annotated_cells.tsv # column index for annotated_matrix.mtx
 preprocessed.h5ad # filtered AnnData before clustering
 clusters.h5ad # AnnData with leiden cluster labels
 switch_diff_<ts>/ # output of `ema switch diff` (auto-routed)
 switch_length_<ts>/ # output of `ema switch length` (auto-routed)
 switch_match_<ts>/ # output of `ema switch match` (auto-routed)
 switch_geneview_<ts>/ # output of `ema switch geneview` (auto-routed)

What PeakATail produces

Peak calling stage

Annotation stage

Clustering stage

Differential APA stage (ema switch diff)

Available CLI commands

Available strategies

Peak calling (ema run --peak-strategy)

Clustering (ema run --cluster-method)

Cross-dataset cluster matching (ema switch match --strategy / ema run --match-method)

3'UTR length quantification (ema switch length --strategy)

Differential APA testing (ema switch diff --strategy)

Documentation

Repository layout

PeakATail/
 ema/ # core Python package (entry point: ema.cli:main)
 cli/ # Click subcommands and config schema
 strategies/ # peak-calling strategy registry
 clustering/ # clustering strategies and cross-dataset matching
 quantification/ # PDUI / proportion / entropy strategies
 switch_test/ # differential APA testing strategies
 outputs.py # all file I/O for the pipeline
 main.py # pipeline orchestration
 downstream_runner.py# per-dataset worker (safe for multiprocessing)
 data/ # example data files
 test/ # test suite (pytest)
 other_repos/ # reference implementations (Sierra, SCAPE, scTail, etc.)
 example.yaml # canonical YAML config template
 combined_polya_scrna_methods.csv # comparison of poly(A) scRNA methods
 pyproject.toml # package metadata, dependencies, entry points
 ROADMAP.md # development and publication roadmap
 LICENSE # MIT License
 Dockerfile # container build

Citation

@software{peakatail,
 author = {Amiri Tabat, Amir},
 title = {{PeakATail}: single-cell poly(A) site detection and APA analysis},
 url = {https://github.com/BMGLab/PeakATail},
 version = {0.2.0},
 note = {TODO: replace with journal citation when available}
}

License