fp-tools: command-first ATAC-seq footprinting with YAML workflows and a GUI
Command-first ATAC-seq footprinting, motif analysis, and reproducible interactive reports
At a glance
- What is it?
- fp-tools-bio is a Python package and desktop app for chromatin footprinting and motif comparison in bulk and single-cell ATAC-seq. It is command-first, but every step also runs from YAML or a browser interface.
- Who is it for?
- Adopt fp-tools if your ATAC-seq work already produces coordinate-sorted BAM/BAI and peak BED files and you want footprint calls and motif comparisons in one command chain. Skip it if you need a fully offline pip install on Windows, since de novo motif tools are downloaded on first use, or if you need FASTQ-to-BAM outside Linux.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 8 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 27, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What fp-tools solves for ATAC-seq analysts
ATAC-seq footprinting is normally a chain of separate tools: bias correction, footprint calling, motif matching, differential comparison, and then a pile of plots that someone rebuilds by hand for each project. fp-tools treats that chain as one unit. The README describes the package as analyzing ATAC-seq and CUT&Tag data to measure chromatin footprints and compare motif-associated signals, starting from aligned reads and peak files for bulk work, or fragments and cell annotations for single-cell work.
The intended user is a computational biologist or core-facility analyst who already has alignments and peaks and does not want to rewrite the same glue script per dataset. The packaging supports that reading: the pyproject.toml lists anndata, scikit-learn, logomaker and xlsxwriter alongside pysam, which points at single-cell embedding output, motif logos and Excel reports rather than a bare footprint caller. The Development Status classifier is 4 - Beta, so the interface is still moving.
The pipeline behind bulk-footprinting and its command chain
The wrapper is the mechanism worth understanding. According to the README, bulk-footprinting runs atac-correct, call-footprints, match-motifs, diff-footprints and review-multi-comparisons in sequence, and each of those commands can also be run directly. That matters when one stage fails or when you want to substitute your own bias correction: you keep the rest of the chain instead of abandoning the run.
Inputs are two tables. samples.tsv carries one row per biological sample with the columns sample, condition, bam and peaks. comparisons.tsv uses comparison, cond1 and cond2 to name each comparison and its two conditions. Genome labels hg38 and mm10 resolve to checksum-verified FASTA and blacklist files from a managed reference cache, and a custom FASTA with an optional custom blacklist can be supplied instead. There is a second comparison mode: diff-footprints --comparison-axis regions compares matched genomic region sets within one sample or across biological replicates, which is a different question from condition-versus-condition.
Single-cell work takes a separate path. sc-footprinting groups fragments, runs pseudobulk footprinting, and produces per-cell KNN footprint-signature heatmaps and UMAPs, taking fragments.tsv.gz, an annotation table, an AnnData embedding and a merged peak BED. The two workflows do not share an entry point, so a project that mixes bulk and single-cell data runs two commands and reconciles the reports afterward.
Installing fp-tools-bio and running a first bulk comparison
The README offers three routes: a desktop app for Windows or Apple Silicon macOS, the Python package for Windows, macOS or Linux on Python 3.11 to 3.13, and a container built from the repository. The pip route is the shortest on Linux and macOS.
python -m pip install --upgrade fp-tools-bio
bulk-footprinting --helpThe install pulls compiled extensions: setup.py cythonizes fp_tools.utils.sequences, fp_tools.utils.ngs and fp_tools.utils.signals, so a source build needs a compiler and NumPy headers. After the install, bulk-footprinting --help should list the wrapper options.
The README gives this example for the wrapper, with --sample-table, --comparison-table, --genome, --outdir and --cores:
bulk-footprinting \
--sample-table samples.tsv \
--comparison-table comparisons.tsv \
--genome hg38 \
--outdir project \
--cores 8The README states that samples.tsv carries one row per biological sample with the columns sample, condition, bam and peaks, and that comparisons.tsv uses comparison, cond1 and cond2. The hg38 and mm10 labels use checksum-verified FASTA and blacklist files from the managed reference cache, so the first run downloads references before analysis starts. The outdir receives the intermediate stages and the final interactive comparison report. If you would rather not use the CLI, fp-tools-gui opens the browser interface, and the container image exposes port 8891 with that GUI as its default command.
Where fp-tools stops: platform gaps and the reference cache
The clearest limitation is stated by the README itself. Optional FASTQ-to-BAM preparation is a separate prepare-atac command, and it exists only on the Linux CLI and in the Linux container. bulk-footprinting, the GUI, and native macOS and Windows installations start from BAM/BAI and peak BED files. If your data is still FASTQ and your workstation is a Mac or a Windows machine, fp-tools is not the front of your pipeline; you align elsewhere first.
Two more constraints follow from the packaging. Optional de novo motif tools are downloaded automatically on first use, which the README notes without describing an offline mode, so an air-gapped cluster needs that step planned. And the dependency markers in pyproject.toml are platform-specific: pysam is excluded on Windows in favor of bamnostic, pyBigWig is limited to Linux on x86_64, and pyfastx is Windows-only. Those markers are a sign the Windows path is maintained through different libraries rather than the same ones, and it is the path least covered by the README's examples.
A subtler failure mode sits in the input tables. The wrapper takes BAM and peak files as given. Nothing in the README describes peak re-calling, so a mismatched peak set between conditions propagates straight into diff-footprints and the comparison inherits that mismatch.
How fp-tools differs from a general single-cell toolkit
The obvious alternative is Signac, which handles single-cell ATAC-seq inside R and Seurat. The difference is where the work happens and what the output is. Signac keeps chromatin data in a Seurat object and expects you to write R to move from fragments to a footprint or a motif enrichment; fp-tools ships sc-footprinting as a command that takes fragments, an annotation table and an AnnData embedding, and returns pseudobulk footprinting plus per-cell KNN footprint-signature heatmaps and UMAPs. If your lab lives in R and Seurat, Signac fits the existing object model. If your single-cell stack is Python and AnnData, fp-tools avoids a cross-language hop.
The second alternative is a chain of single-purpose tools driven by a workflow manager such as Snakemake or Nextflow. That gives you finer control over every step and container. fp-tools trades that control for a fixed chain with a YAML option: run-yaml-workflow saves workflows as YAML, and the wrapper commands are also individually runnable. The trade is real in both directions. You get reproducibility without writing a workflow, and you accept the stages the project chose.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-09-14, the same day as the v0.2.6 release. Three releases landed that day: v0.2.4, v0.2.5 and v0.2.6, all dated 2026-09-14. That cadence suggests active work, but it also means the 0.2.x line moves quickly. The pyproject.toml classifier is Development Status 4 - Beta, so pinning a version is the reasonable posture for a published analysis.
The licence is MIT, which is permissive and places few obligations on redistribution or modification. The bundled dependencies are a separate question: the README says optional de novo motif tools are downloaded on first use, and those carry their own licences, which the README does not enumerate. If you redistribute a container, check what those tools permit rather than assuming the MIT licence covers the whole runtime. Nothing here is legal advice.
Upgrade cost concentrates in the two input tables and the YAML schema. Because samples.tsv and comparisons.tsv encode the analysis design, a column rename between minor versions would touch every project's tables. The repository ships tests/ and test_data/ plus a Makefile with a test target, so a version bump can be checked locally before it reaches a shared environment.
Editorial conclusion
Adopt fp-tools if your ATAC-seq work already produces coordinate-sorted BAM/BAI and peak BED files and you want footprint calls and motif comparisons in one command chain. Skip it if you need a fully offline pip install on Windows, since de novo motif tools are downloaded on first use, or if you need FASTQ-to-BAM outside Linux. Before committing, run bulk-footprinting --help on your target platform and confirm the hg38 or mm10 reference cache downloads cleanly.
Frequently asked questions
What is fp-tools?
fp-tools is a command-line and GUI toolkit for ATAC-seq and CUT&Tag analysis that measures chromatin footprints and compares motif-associated signals. It ships as the fp-tools-bio Python package, a desktop app, and a container, and supports both bulk and single-cell workflows.
How do I install fp-tools?
The README gives three routes: a desktop app for Windows or Apple Silicon macOS, the Python package via python -m pip install fp-tools-bio on Python 3.11 to 3.13, or a container built from the repository with docker build.
What input files does bulk-footprinting need?
It starts from coordinate-sorted BAM/BAI files and matching peak BED files. You supply samples.tsv with the columns sample, condition, bam and peaks, plus comparisons.tsv with comparison, cond1 and cond2.
Can fp-tools process FASTQ files?
Only on Linux. The README states that optional FASTQ-to-BAM preparation is a separate prepare-atac command available on the Linux CLI and in the Linux container, while bulk-footprinting, the GUI and native macOS and Windows installations start from BAM/BAI and peak BED files.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/oncologylab-fp-tools)