Metadata-Version: 2.4
Name: fp-tools-bio
Version: 0.1.6
Summary: Standalone footprint tools with vendored Cython internals
Author-email: Yaoxiang Li <liyaoxiang@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lzyacht/fp-tools
Project-URL: Repository, https://github.com/lzyacht/fp-tools
Project-URL: Issues, https://github.com/lzyacht/fp-tools/issues
Keywords: ATAC-seq,footprinting,motif,chromatin,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Cython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy<3.0,>=1.22
Requires-Dist: scipy<2.0,>=1.16
Requires-Dist: pysam<0.24.0,>=0.23.3
Requires-Dist: pyBigWig<0.4.0,>=0.3.24
Requires-Dist: matplotlib<4.0,>=3.10
Requires-Dist: pandas<3.0,>=2.3.3
Requires-Dist: seaborn<0.14.0,>=0.13.2
Requires-Dist: pybedtools<0.13,>=0.12
Requires-Dist: scikit-learn<2.0,>=1.5
Requires-Dist: tqdm<5.0,>=4.66
Requires-Dist: kneed<0.9.0,>=0.8.5
Requires-Dist: adjustText<2.0.0,>=1.3.0
Requires-Dist: moods-python<2.0.0.0,>=1.9.4.1
Requires-Dist: biopython<2.0,>=1.85
Requires-Dist: logomaker<0.9.0,>=0.8.7
Requires-Dist: xlsxwriter<4.0.0,>=3.2.9
Requires-Dist: PyYAML<7.0,>=6.0
Requires-Dist: streamlit<2.0,>=1.44

# 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

```bash
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

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

## Minimal Workflow

### 1. ATACorrect

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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:

```text
<outdir>/bindetect_results_skewness_report.pdf
```

Single-condition runs do not produce this report.

### PlotAggregate Control Overlay

```bash
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

```bash
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

```bash
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

```bash
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.*
