Metadata-Version: 2.4
Name: fp-tools-bio
Version: 0.1.4
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 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

```bash
./scripts/build_release.sh
```

Release artifacts are written to `dist/`.

## Install

```bash
pip install fp-tools-bio
```

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

You can also use a fixed port:

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

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