fp-tools-bio 0.1.4

Standalone footprint tools with vendored Cython internals

fp-tools

fp-tools is a standalone footprinting package built around four packaged commands:

• ATACorrect
• FootprintScores
• BINDetect
• PlotAggregate

It also includes:

• fp-tools-run for optional YAML-driven batch execution
• fp-tools-gui for a browser-based per-user GUI wrapper

Build

./scripts/build_release.sh

Release artifacts are written to dist/.

Install

pip install fp-tools-bio

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 automatically and prints the exact URL.

You can also use a fixed port:

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

The GUI supports:

• direct form-driven runs
• loading YAML configs
• saving YAML configs
• sample-list batch runs
• BINDetect comparison-list batch runs
• basic pre-launch config validation
• run-history inspection with detected output paths

GUI run metadata and logs are written under:

• examples/gui_runs/

Example GUI output files are written under:

• examples/gui_demo_outputs/

Ready-to-load GUI YAML examples are in:

• examples/gui_configs/

YAML Runner

Direct CLI usage remains primary and does not require YAML.

YAML is an optional extra path for:

• GUI interoperability
• saved run configs
• batch execution

Run a config file with:

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

Reference Examples

Core validated example outputs:

• examples/atacorrect/ATACorrect_test_rc014
• examples/scorebigwig/ScoreBigwig_test_rc014
• examples/bindetect/BINDetect_output_rc014
• examples/reports/plotaggregate_rc014.pdf

Additional validated examples:

• examples/bindetect/BINDetect_output_synthetic_replicates_demo
• examples/bindetect/BINDetect_output_jaspar2026_manualcheck
• examples/bindetect/BINDetect_output_htmlfix_014
• examples/reports/plotaggregate_control_mode_test.pdf
• examples/reports/plotaggregate_dirinput_test.pdf
• examples/reports/plotaggregate_signals_export_test.pdf

Notes

• fp-tools builds on ideas and workflows from TOBIAS.
• The direct packaged commands remain the primary interface.
• The GUI is an isolated wrapper layer and does not replace the core CLI.