fp-tools-bio 0.1.6

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

• ATACorrect: correct ATAC-seq cutsite signal for Tn5 sequence bias.
• FootprintScores: calculate footprint, sum, mean, or pass-through scores from bigWig signal.
• BINDetect: scan motifs, infer bound sites, and compare TF binding across conditions.
• PlotAggregate: 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.

Verify

ATACorrect --help
FootprintScores --help
BINDetect --help
PlotAggregate --help
fp-tools-run --help
fp-tools-gui --help

Minimal Workflow

1. ATACorrect

ATACorrect \
  --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/ATACorrect_test2 \
  --cores 1

2. FootprintScores

FootprintScores \
  --signal examples/atacorrect/ATACorrect_test2/Bcell_corrected.bw \
  --regions test_data/merged_peaks.bed \
  --output examples/scorebigwig/ScoreBigwig_test2/Bcell_footprints.bw \
  --cores 1

3. BINDetect

BINDetect \
  --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/BINDetect_output_htmlfix_014 \
  --cond-names Bcell Tcell \
  --cores 1

4. PlotAggregate

PlotAggregate \
  --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

BINDetect Replicate Grouping

BINDetect --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/BINDetect_output_synthetic_replicates_demo \
  --cond-names Bcell Bcell Tcell Tcell \
  --cores 40

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

BINDetect 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.

PlotAggregate Control Overlay

PlotAggregate --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

PlotAggregate Directory Input

PlotAggregate --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

PlotAggregate Fixed Grid Layout

PlotAggregate --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

PlotAggregate CSV Exports

PlotAggregate --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 BINDetect command path. A JASPAR2026-scale run completed with 1019 motifs.

Acknowledgement

fp-tools builds on ideas and workflows from TOBIAS.

unpublished tools, Yi Lab, 2026.