PeakATail

PeakATail is a Python tool for single-cell poly(A) site (PAS) detection and alternative polyadenylation (APA) analysis. It works with any scRNA-seq BAM that carries a CB:Z (corrected cell barcode) tag — STARsolo, CellRanger, Alevin-fry, or any aligner that emits the standard 10x-style tag schema. UMI (UB:Z) tags are NOT required or used: PeakATail counts raw read 3'ends, not UMI-deduplicated molecules. PeakATail does NOT correct barcodes; your aligner must apply a barcode whitelist (e.g. STARsolo's --soloCBwhitelist). From the input BAM it calls polyadenylation sites at the read level, builds a per-cell PAS count matrix, clusters cells by their APA profiles, and provides downstream analyses including differential APA testing between clusters, 3'UTR length quantification, and cross-dataset cluster matching. Developed at BMGLab.

Quick install

System prerequisites

PeakATail calls samtools and bedtools as subprocesses. Both must be on your PATH before running the pipeline.

# Debian/Ubuntu
sudo apt-get install samtools bedtools

# macOS (Homebrew)
brew install samtools bedtools

The code has been tested against samtools >= 1.10 (enforced at runtime in ema/datasets/manager.py).

Python version

Python 3.11 or later is required (declared in pyproject.toml as requires-python = ">=3.11").

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 .

All Python dependencies are declared in pyproject.toml and installed automatically.

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 peakatail run --config my_run.yaml --threads 4

# Step 3: differential APA between every cluster pair
uv run peakatail 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 peakatail switch length \
    -i peakatail_runs/<run>/per_dataset/<ds>/clusters.h5ad \
    --strategy classic

The pipeline writes all output under peakatail_runs/<name>_<timestamp>/. A typical run directory looks like:

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 `peakatail switch diff` (auto-routed)
    switch_length_<ts>/              # output of `peakatail switch length` (auto-routed)
    switch_match_<ts>/               # output of `peakatail switch match` (auto-routed)
    switch_geneview_<ts>/            # output of `peakatail switch geneview` (auto-routed)

What PeakATail produces

Peak calling stage

Annotation stage

Clustering stage

Differential APA stage (peakatail switch diff)

Available CLI commands

All commands are accessed through the peakatail entry point installed by pip install -e .. The old ema command still works as a deprecated alias.

Use --list-strategies on peakatail run, peakatail switch diff, peakatail switch length, and peakatail switch match to see the strategies registered in the current installation.

Every command accepts --help for full flag documentation.

Available strategies

Peak calling (peakatail run --peak-strategy)

Clustering (peakatail run --cluster-method)

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

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

Differential APA testing (peakatail switch diff --strategy)

Documentation

Full docs: https://bmglab.github.io/PeakATail/

The MkDocs documentation site is built automatically from the develop and main branches via the .github/workflows/docs.yml GitHub Actions workflow and published to GitHub Pages.

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

If you use PeakATail, please cite the software entry below for now. The author field mirrors the package author declared in pyproject.toml; the full manuscript author list and a machine-readable CITATION.cff will be added with the paper release (tracked in the release-engineering issue).

@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.3.1},
  note    = {Preprint in preparation; replace with the journal citation when available}
}

License

This project is licensed under the MIT License — see the LICENSE file for the full text. pyproject.toml declares the matching SPDX identifier (license = "MIT").