Get Started¶
fp-tools runs ATAC-seq footprint workflows from the command line or the optional browser GUI. The same YAML configuration can be saved from the GUI and rerun with run-workflow.
Install¶
pip install fp-tools-bio
For the browser GUI:
pip install "fp-tools-bio[gui]"
fp-tools-gui
Standard Workflow¶
1. Correct ATAC Signal¶
atac-correct \
--sample-table project/metadata/samples.tsv \
--genome hg38.fa.gz \
--blacklist hg38.blacklist.bed \
--outdir project
Output: corrected cut-site bigWigs and QC files. With a sample table and --outdir project, fp-tools uses the project layout by default, reads a generic sample condition bam peaks table, merges the sample peak BED files, writes project/peaks/merged_peaks.bed, and writes filtered peaks to project/peaks/merged_peaks_filtered.bed with mitochondrial chromosomes excluded. Downstream project-mode commands use this filtered BED when peak/background regions are omitted or when the project raw merged BED is passed.
For production runs where corrected bigWigs are the required output, add --skip-qc to skip the diagnostic PDF and pre/post correction bias-count summaries without changing the corrected signal tracks.
Optional q95 scaling for multi-sample projects:
normalize-bigwig \
--sample-table project/metadata/samples.tsv \
--background project/peaks/merged_peaks_filtered.bed \
--outdir project \
--method background-scale \
--stat q95 \
--target median
2. Call Footprints¶
call-footprints \
--sample-table project/metadata/samples.tsv \
--regions project/peaks/merged_peaks_filtered.bed \
--outdir project
Output: footprint score bigWig files. Add --call-candidates in project mode, or --output-bed/--output-beds in custom mode, to also write genomic coordinates for footprint peaks used by de novo motif discovery. In project mode, fp-tools uses q95-scaled corrected tracks when present and otherwise falls back to corrected tracks. The default footprint kernel uses the faster prefix-sum implementation; use --footprint-kernel legacy only when exact historical floating-point behavior is required.
3a. Match Motifs¶
match-motifs \
--sample-table project/metadata/samples.tsv \
--genome hg38.fa.gz \
--peaks project/peaks/merged_peaks_filtered.bed \
--motif-db jaspar2026_vertebrates \
--outdir project
Output: for each sample, the summary table contains motif binding statistics, motif-site/background caches are written for fast reuse by diff-footprints, and per-motif BED folders are materialized by default with files such as <motif>_all.bed, <motif>_<sample>_bound.bed, and <motif>_<sample>_unbound.bed. In project mode, match-motifs uses one shared motif scan across samples by default and then writes normal per-sample folders; per-motif BED folders are written in the background after report-ready outputs. Cached diff-footprints comparisons may create internal per-motif shard caches on first reuse, then reuse those shards for later comparisons. Use --match-scan-mode per-sample only when independent sample scans are needed for debugging. Use --motif-outputs summary only when you want to skip permanent BED folders.
3b. Discover De Novo Motifs¶
Use de novo motif discovery when you want to start from candidate footprint intervals rather than only a curated database.
call-footprints \
--signals project/samples/sample/atac_correct/sample_corrected.bw \
--sample-names sample \
--regions merged_peaks.bed \
--sample-output-root project/samples
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
Output: candidate FASTA files, a runnable MEME/STREME/DREME command script, motif-discovery outputs, and optional Tomtom comparison against the selected known motif database. Discovered motifs can be used alone with --motifs, or added to a database run with --motif-db plus --motifs.
4. Compare Conditions¶
diff-footprints \
--sample-table project/metadata/samples.tsv \
--comparison-table project/metadata/comparisons.tsv \
--genome hg38.fa.gz \
--peaks project/peaks/merged_peaks_filtered.bed \
--motif-db jaspar2026_vertebrates \
--outdir project
metadata/comparisons.tsv uses generic columns: comparison, cond1, and cond2. Project-mode diff-footprints reuses compact motif-site tables and background scores from prior match-motifs runs, and samples with the same condition are treated as replicates. Output includes motif tables, volcano-style results, and a standalone HTML report. Aggregate profiles in the report are capped by --plot-aggregate-top-n in sig and top modes; increase this value when you want more motif profiles in the HTML.
Workflow Improvements¶
fp-tools preserves the interpretable TOBIAS-style center-versus-flank footprint score while improving the multi-sample workflow. q95 scaling can align corrected cut-site tracks over shared background regions before scoring. The default footprint-scoring path uses optimized Cython-backed kernels, and project-mode motif analysis uses one shared motif scan plus compact caches that diff-footprints reuses for replicate-aware comparisons and HTML/SVG reports.
For a complete multi-condition shell-script template, see
examples/nutrient_stress_project/run_ctrl_vs_10fbs.sh in the GitHub
repository. It documents the expected raw-data layout, explains how to prepare
portable samples.tsv and comparisons.tsv files from an
ATAC_Nutrients_hg38_*.txt table, supports CHECK_ONLY=1 input validation, and
then runs the full project workflow.
5. Plot Aggregate¶
plot-aggregate \
--sample-table project/metadata/samples.tsv \
--motifs SPIB CEBPB \
--site-set bound \
--outdir project
Output: static PDF/SVG-style aggregate plots or an interactive HTML subplot browser, depending on --format or the --output extension.
Pseudobulk Single-Cell ATAC¶
Use pseudobulk-fragments to group single-cell fragments by annotation, then run the standard footprint commands on the grouped pseudobulk samples. Use pseudobulk-footprints when you want grouping, correction, scoring, motif reports, aggregate plots, and optional signature reporting in one wrapper 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
Standard outputs include pseudobulk fragments, pseudo-BAMs, corrected cut-site bigWigs, footprint-score bigWigs, motif-aware differential reports, aggregate plots, and optional single-cell footprint-signature heatmaps/UMAPs. The combined signature plot is written as plots/single_cell_footprinting/single_cell_footprinting.svg when --single-cell-signature-h5ad and --tf-site-dir are supplied.
For a lighter first step, use pseudobulk-fragments to only group fragments and write cut-site tracks. After motif-aware analysis, use find-signature-fp as a standalone reporting step for marker signature heatmaps and UMAPs.
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
Where To Go Next¶
Command Manuals
See the command overview and full help for every supported command.