fp-tools-bio 0.1.9

Standalone footprint tools with vendored Cython internals

fp-tools

fp-tools is a Python package for ATAC-seq footprint analysis. It helps users turn ATAC-seq data into bias-corrected cut-site tracks, footprint scores, motif-centered comparisons, aggregate plots, and static HTML reports.

Documentation: https://oncologylab.github.io/fp-tools/

Install

pip install fp-tools-bio

To use the browser interface:

pip install "fp-tools-bio[gui]"
fp-tools-gui

The GUI opens in a browser and writes the same YAML configs that can be run from the command line.

What You Can Do

• Correct ATAC-seq cut-site signal for Tn5 sequence bias.
• Call footprint scores from corrected bigWig tracks.
• Scan known motif databases, including bundled JASPAR 2026 and HOCOMOCO files.
• Compare footprint scores across conditions or replicates.
• Generate volcano-style differential footprint HTML reports.
• Plot motif-centered aggregate footprints.
• Group single-cell ATAC fragments into pseudobulk cell-type profiles.
• Plot per-cell footprint-signature heatmaps and UMAP reports from single-cell fragments.

Typical Workflow

atac-correct -> call-footprints -> match-motifs or motif-discovery -> diff-footprints -> plot-aggregate

Use match-motifs to inspect motif sites and bound/unbound calls for one or more footprint tracks. Use motif-discovery when candidate footprint intervals should be searched for de novo motifs. For two or more conditions, use diff-footprints; it can scan the same motif database, compare conditions, and write an interactive HTML report.

Minimal Example

Create a simple sample table:

sample	condition	bam	peaks
A	conditionA	A.bam	A_peaks.bed
B	conditionB	B.bam	B_peaks.bed

For condition comparisons, create a comparison table:

comparison	cond1	cond2
conditionA_vs_conditionB	conditionA	conditionB

atac-correct \
  --sample-table project/metadata/samples.tsv \
  --genome hg38.fa.gz \
  --blacklist hg38.blacklist.bed \
  --outdir project

normalize-bigwig \
  --sample-table project/metadata/samples.tsv \
  --background project/peaks/merged_peaks.analysis.bed \
  --outdir project \
  --method background-scale \
  --stat q95 \
  --target median

call-footprints \
  --sample-table project/metadata/samples.tsv \
  --regions project/peaks/merged_peaks.analysis.bed \
  --outdir project

match-motifs \
  --sample-table project/metadata/samples.tsv \
  --genome hg38.fa.gz \
  --peaks project/peaks/merged_peaks.analysis.bed \
  --motif-db jaspar2026_vertebrates \
  --outdir project

diff-footprints \
  --sample-table project/metadata/samples.tsv \
  --comparison-table project/metadata/comparisons.tsv \
  --genome hg38.fa.gz \
  --peaks project/peaks/merged_peaks.analysis.bed \
  --motif-db jaspar2026_vertebrates \
  --outdir project

With a sample table and --outdir project, fp-tools uses the recommended project layout by default: merged peaks in project/peaks, per-sample outputs in project/samples/<sample>/, differential reports in project/comparisons, and review pages in project/reports. Custom paths remain available with --layout custom.

After match-motifs, project-mode diff-footprints reuses each sample folder's cached motif-site tables and background scores instead of rescanning motifs or rereading footprint bigWigs. Repeated samples with the same condition are treated as biological replicates.

Pseudobulk Workflow

For single-cell ATAC data, start with pseudobulk-fragments to group fragments by cell annotation. Then run the standard footprint workflow on the grouped pseudobulk samples. After motif-aware comparisons are available, use find-signature-fp to write marker footprint-signature heatmaps and UMAP reports. pseudobulk-footprints is the convenience wrapper that can run grouping, correction, scoring, motif reports, aggregate plots, and optional signature reporting in one command.

pseudobulk-footprints \
  --fragments pbmc_fragments.tsv.gz \
  --annotations cell_annotations.tsv \
  --group-by cell_type \
  --genome-sizes hg38.chrom.sizes \
  --genome hg38.fa.gz \
  --peaks merged_peaks.bed \
  --motif-db jaspar2026_vertebrates \
  --tf-site-dir marker_motif_sites \
  --single-cell-signature-h5ad pbmc_embedding.h5ad \
  --outdir project/pseudobulk

To run the signature report as a standalone step:

find-signature-fp \
  --annotations cell_annotations.tsv \
  --fragments pbmc_fragments.tsv.gz \
  --h5ad pbmc_embedding.h5ad \
  --tf-site-dir marker_motif_sites \
  --all-motif-results project/pseudobulk/pseudobulk_diff_footprints_results.txt \
  --all-motif-diff-dir project/pseudobulk/diff_footprints \
  --outdir project/pseudobulk/signature_fp

Key outputs include pseudobulk fragments, pseudo-BAMs, corrected bigWigs, footprint-score bigWigs, differential footprint reports, aggregate plots, and single-cell footprint-signature heatmaps/UMAPs.

De Novo Motif Workflow

Use candidate footprints from call-footprints --output-bed to prepare de novo motif discovery. This route writes a reproducible MEME/STREME/DREME script and can compare discovered motifs to a built-in motif database.

motif-discovery \
  --candidates project/samples/sample/footprints/sample_candidate_footprints.bed \
  --genome hg38.fa.gz \
  --flank 75 \
  --method streme \
  --known-motif-db jaspar2026_vertebrates \
  --outdir project/de_novo/sample

Use discovered motifs alone for a de novo-only run, or add them to a standard database run:

diff-footprints \
  --signals conditionA_footprints.bw conditionB_footprints.bw \
  --sample-names conditionA conditionB \
  --genome hg38.fa.gz \
  --peaks merged_peaks.bed \
  --cond-names conditionA conditionB \
  --motif-db jaspar2026_vertebrates \
  --motifs project/de_novo/sample/streme/streme.txt \
  --outdir project/comparisons/database_plus_de_novo

Main Commands

Command	Use
atac-correct	Bias-correct ATAC-seq cut-site signal.
call-footprints	Create footprint score tracks from one or more bigWigs.
match-motifs	Scan motifs for one or more footprint tracks.
diff-footprints	Compare motif footprints across conditions.
normalize-bigwig	Scale bigWigs before aggregate plotting.
plot-aggregate	Make aggregate footprint plots as PDF/SVG-style output or HTML.
review-multi-comparisons	Review multiple differential-footprint HTML reports in one page.
motif-discovery	Prepare candidate-centered de novo motif discovery.
motif-summary	Summarize motif discovery outputs.
pseudobulk-fragments	Group single-cell fragments by annotation.
find-signature-fp	Plot per-cell footprint-signature heatmaps and UMAP reports.
pseudobulk-footprints	Run the full pseudobulk footprint workflow, including optional signature reporting.
run-workflow	Run a saved YAML config.
fp-tools-gui	Open the optional browser GUI.
fp-tools-score-variants	Optional variant-annotation utility; not part of the standard footprint workflow.

Check any command with --help:

atac-correct --help
call-footprints --help
match-motifs --help
diff-footprints --help
normalize-bigwig --help
plot-aggregate --help
review-multi-comparisons --help
run-workflow --help
fp-tools-gui --help
motif-discovery --help
motif-summary --help
fp-tools-score-variants --help
pseudobulk-fragments --help
find-signature-fp --help
pseudobulk-footprints --help

GUI

fp-tools-gui --host 0.0.0.0 --port 8891

Open the printed URL in a browser. If running on a server or cloud VM, make sure the selected port is allowed by the firewall or security group.

More Examples

Example YAML configs are in examples/gui_configs/. They can be loaded in the GUI or run directly with run-workflow:

run-workflow --config examples/gui_configs/footprintscores_single.yml

Static report demos and GUI screenshots are available in the documentation site.