fp-tools-bio 0.1.7

Standalone footprint tools with vendored Cython internals

fp-tools

fp-tools is a standalone footprinting package for ATAC-seq style workflows. It provides command-first tools for bias correction, footprint scoring, differential binding detection, and aggregate signal plotting.

The PyPI distribution is named fp-tools-bio; the installed Python package is fp_tools.

Install

pip install fp-tools-bio

Commands

• atac-correct: correct ATAC-seq cutsite signal for Tn5 sequence bias.
• score-footprints: calculate footprint, sum, mean, or pass-through scores from bigWig signal.
• detect-tf-binding: scan motifs, infer bound sites, and compare TF binding across conditions.
• plot-aggregate: plot aggregate signal around TFBS or region sets.
• fp-tools-run: run optional YAML batch configs.
• fp-tools-gui: launch the optional Streamlit GUI wrapper.

Direct CLI usage is the primary interface. YAML configs and the GUI are optional wrapper paths and do not replace the plain command-line tools.

Legacy aliases remain available for compatibility: ATACorrect, FootprintScores, ScoreBigwig, BINDetect, and PlotAggregate.

Verify

atac-correct --help
score-footprints --help
detect-tf-binding --help
plot-aggregate --help
fp-tools-run --help
fp-tools-gui --help

Minimal Workflow

1. atac-correct

atac-correct \
  --bam test_data/Bcell.bam \
  --genome test_data/genome.fa.gz \
  --peaks test_data/merged_peaks.bed \
  --blacklist test_data/blacklist.bed \
  --outdir examples/atacorrect/atac-correct_test2 \
  --cores 1

2. score-footprints

score-footprints \
  --signal examples/atacorrect/atac-correct_test2/Bcell_corrected.bw \
  --regions test_data/merged_peaks.bed \
  --output examples/scorebigwig/score-footprints_test2/Bcell_footprints.bw \
  --cores 1

3. detect-tf-binding

detect-tf-binding \
  --motifs test_data/motifs.jaspar \
  --signals test_data/Bcell_footprints.bw test_data/Tcell_footprints.bw \
  --genome test_data/genome.fa.gz \
  --peaks test_data/merged_peaks_annotated.bed \
  --peak-header test_data/merged_peaks_annotated_header.txt \
  --outdir examples/bindetect/detect-tf-binding_output_htmlfix_014 \
  --cond-names Bcell Tcell \
  --cores 1

4. plot-aggregate

plot-aggregate \
  --TFBS test_data/IRF1_all.bed \
  --signals test_data/Bcell_corrected.bw \
  --output examples/reports/plotaggregate_control_mode_test.pdf \
  --output_aggregated_scores examples/reports/plotaggregate_control_mode_test_scores.csv

GUI

Start the GUI on a Linux server:

fp-tools-gui --host 0.0.0.0 --run-dir examples/gui_runs

If --port is omitted, the launcher picks a free port and prints the exact URL. A fixed port can also be supplied:

fp-tools-gui --host 0.0.0.0 --port 8891 --run-dir examples/gui_runs

The GUI can run directly from forms, load YAML, save YAML, and inspect run history. GUI run metadata and logs are written under examples/gui_runs/; ready-to-load YAML examples are in examples/gui_configs/.

YAML Runner

Run a saved config directly from the command line:

fp-tools-run --config examples/gui_configs/plotaggregate_single.yml

GUI-saved YAML files can be rerun the same way. YAML is optional for normal CLI use.

Extra Features

detect-tf-binding Replicate Grouping

detect-tf-binding --motifs test_data/motifs.jaspar \
  --signals test_data/demo_Bcell_rep1_footprints.bw test_data/demo_Bcell_rep2_footprints.bw test_data/demo_Tcell_rep1_footprints.bw test_data/demo_Tcell_rep2_footprints.bw \
  --genome test_data/genome.fa.gz \
  --peaks test_data/merged_peaks_annotated.bed \
  --peak-header test_data/merged_peaks_annotated_header.txt \
  --outdir examples/bindetect/detect-tf-binding_output_synthetic_replicates_demo \
  --cond-names Bcell Bcell Tcell Tcell \
  --cores 40

Grouped results are written to bindetect_results.txt under the output directory.

detect-tf-binding Skewness Report

For multi-condition runs, the skewness report is written automatically to:

<outdir>/bindetect_results_skewness_report.pdf

Single-condition runs do not produce this report.

plot-aggregate Control Overlay

plot-aggregate --TFBS test_data/IRF1_all.bed \
  --signals test_data/Bcell_corrected.bw test_data/Tcell_corrected.bw \
  --signal-labels Bcell Tcell \
  --control-label Bcell \
  --output examples/reports/plotaggregate_control_mode_test.pdf \
  --output_aggregated_scores examples/reports/plotaggregate_control_mode_test_scores.csv

plot-aggregate Directory Input

plot-aggregate --TFBS examples/plotaggregate_tfbs_dir \
  --signals test_data/Bcell_corrected.bw \
  --output examples/reports/plotaggregate_dirinput_test.pdf \
  --output_aggregated_scores examples/reports/plotaggregate_dirinput_test_scores.csv

plot-aggregate Fixed Grid Layout

plot-aggregate --TFBS examples/plotaggregate_tfbs_grid/CTCF_Bcell_bound.bed examples/plotaggregate_tfbs_grid/IRF1_Bcell_bound.bed examples/plotaggregate_tfbs_grid/ETS1_Bcell_bound.bed examples/plotaggregate_tfbs_grid/GATA3_Bcell_bound.bed examples/plotaggregate_tfbs_grid/RUNX1_Bcell_bound.bed \
  --signals test_data/Bcell_corrected.bw test_data/Tcell_corrected.bw \
  --signal-labels Bcell_corrected Tcell_corrected \
  --grid 2x5 \
  --output examples/reports/plotaggregate_grid_2x5_test.pdf \
  --output_aggregated_scores examples/reports/plotaggregate_grid_2x5_test_scores.csv

plot-aggregate CSV Exports

plot-aggregate --TFBS test_data/IRF1_all.bed \
  --signals test_data/Bcell_corrected.bw \
  --output examples/reports/plotaggregate_signals_export_test.pdf \
  --output_aggregated_signals examples/reports/plotaggregate_signals_export_test_signals.csv \
  --output_aggregated_scores examples/reports/plotaggregate_signals_export_test_scores.csv

The legacy --output-csv alias writes the aggregated signal CSV.

Larger Motif Databases

Large JASPAR and HOCOMOCO-scale motif databases are supported through the same detect-tf-binding command path. A JASPAR2026-scale run completed with 1019 motifs.

Yi Lab, 2026.