fp-tools-bio 0.1.4__tar.gz

fp_tools_bio-0.1.4/PKG-INFO

@@ -0,0 +1,202 @@
+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.

fp_tools_bio-0.1.4/README.md

@@ -0,0 +1,164 @@
+# 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.

fp_tools_bio-0.1.4/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+# setuptools does the build; Cython & NumPy headers are available at build time
+requires = [
+  "setuptools>=68",
+  "wheel",
+  "Cython>=3.0",
+  "numpy>=1.22"
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fp-tools-bio"
+version = "0.1.4"
+description = "Standalone footprint tools with vendored Cython internals"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Yaoxiang Li", email = "liyaoxiang@outlook.com" }]
+requires-python = ">=3.12"
+keywords = ["ATAC-seq", "footprinting", "motif", "chromatin", "bioinformatics"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Cython",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+
+# Runtime deps (unified here so pip/wheel installs work without Poetry)
+dependencies = [
+  "numpy>=1.22,<3.0",
+  "scipy>=1.16,<2.0",
+  "pysam>=0.23.3,<0.24.0",
+  "pyBigWig>=0.3.24,<0.4.0",
+  "matplotlib>=3.10,<4.0",
+  "pandas>=2.3.3,<3.0",
+  "seaborn>=0.13.2,<0.14.0",
+  "pybedtools>=0.12,<0.13",
+  "scikit-learn>=1.5,<2.0",
+  "tqdm>=4.66,<5.0",
+  "kneed>=0.8.5,<0.9.0",
+  "adjustText>=1.3.0,<2.0.0",
+  "moods-python>=1.9.4.1,<2.0.0.0",
+  "biopython>=1.85,<2.0",
+  "logomaker>=0.8.7,<0.9.0",
+  "xlsxwriter>=3.2.9,<4.0.0",
+  "PyYAML>=6.0,<7.0",
+  "streamlit>=1.44,<2.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/lzyacht/fp-tools"
+Repository = "https://github.com/lzyacht/fp-tools"
+Issues = "https://github.com/lzyacht/fp-tools/issues"
+
+[project.scripts]
+ATACorrect = "fp_tools.cli:main"
+FootprintScores = "fp_tools.cli_scorebigwig:main"
+ScoreBigwig = "fp_tools.cli_scorebigwig:main"
+BINDetect = "fp_tools.tools.bindetect:run_cli"
+PlotAggregate = "fp_tools.cli_plotaggregate:main"
+fp-tools-run = "fp_tools.cli_batch:main"
+fp-tools-gui = "fp_tools.cli_gui:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where   = ["src"]
+include = ["fp_tools*"]
+
+# ship .pyx/.pxd in sdists so downstream builds can compile
+[tool.setuptools.package-data]
+"fp_tools.utils" = ["*.pyx", "*.pxd"]
+
+# --- Poetry mirror of the important bits so `poetry build` works too ---
+[tool.poetry]
+name = "fp-tools-bio"
+version = "0.1.4"
+description = "Standalone footprint tools with vendored Cython internals"
+authors = ["Yaoxiang Li <liyaoxiang@outlook.com>"]
+readme = "README.md"
+packages = [{ include = "fp_tools", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.12,<4.0"
+numpy = ">=1.22,<3.0"
+scipy = ">=1.16,<2.0"
+pysam = ">=0.23.3,<0.24.0"
+pybigwig = ">=0.3.24,<0.4.0"
+matplotlib = ">=3.10,<4.0"
+pandas = ">=2.3.3,<3.0"
+seaborn = ">=0.13.2,<0.14.0"
+pybedtools = ">=0.12,<0.13"
+scikit-learn = ">=1.5,<2.0"
+tqdm = ">=4.66,<5.0"
+kneed = ">=0.8.5,<0.9.0"
+adjusttext = ">=1.3.0,<2.0.0"
+moods-python = ">=1.9.4.1,<2.0.0.0"
+biopython = ">=1.85,<2.0"
+logomaker = ">=0.8.7,<0.9.0"
+xlsxwriter = ">=3.2.9,<4.0.0"
+pyyaml = ">=6.0,<7.0"
+streamlit = ">=1.44,<2.0"
+
+[tool.poetry.scripts]
+ATACorrect = "fp_tools.cli:main"
+FootprintScores = "fp_tools.cli_scorebigwig:main"
+ScoreBigwig = "fp_tools.cli_scorebigwig:main"
+BINDetect = "fp_tools.tools.bindetect:run_cli"
+PlotAggregate = "fp_tools.cli_plotaggregate:main"
+fp-tools-run = "fp_tools.cli_batch:main"
+fp-tools-gui = "fp_tools.cli_gui:main"

fp_tools_bio-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fp_tools_bio-0.1.4/setup.py

@@ -0,0 +1,21 @@
+# setup.py
+from setuptools import setup, Extension
+from Cython.Build import cythonize
+import numpy, pathlib
+
+ext_modules = [
+    Extension("fp_tools.utils.sequences", [str(pathlib.Path("src/fp_tools/utils/sequences.pyx"))],
+              include_dirs=[numpy.get_include()]),
+    Extension("fp_tools.utils.ngs",       [str(pathlib.Path("src/fp_tools/utils/ngs.pyx"))],
+              include_dirs=[numpy.get_include()]),
+    Extension("fp_tools.utils.signals",   [str(pathlib.Path("src/fp_tools/utils/signals.pyx"))],
+              include_dirs=[numpy.get_include()]),
+]
+
+setup(
+    ext_modules=cythonize(
+        ext_modules,
+        language_level="3",
+        compiler_directives={"boundscheck": False, "wraparound": False},
+    ),
+)

fp_tools_bio-0.1.4/src/fp_tools/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.4"
+
+__all__ = ["__version__"]

fp_tools_bio-0.1.4/src/fp_tools/cli.py

@@ -0,0 +1,8 @@
+from fp_tools.parsers import add_atacorrect_arguments
+from fp_tools.tools.atacorrect import run_atacorrect
+
+def main():
+    import argparse
+    parser = add_atacorrect_arguments(argparse.ArgumentParser())
+    args = parser.parse_args()
+    run_atacorrect(args)

fp_tools_bio-0.1.4/src/fp_tools/cli_batch.py

@@ -0,0 +1,155 @@
+"""Optional YAML-driven batch/config runner for fp-tools.
+
+Direct CLI usage remains primary. This module adds an extra path for:
+- replaying GUI-saved configs
+- running batch sample lists
+- running batch BINDetect comparison lists
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from fp_tools.gui_config import JobSpec, canonical_tool_name, dump_yaml_config, expand_jobs, load_yaml_config, normalize_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run fp-tools jobs from a YAML config file.")
+    parser.add_argument("--config", required=True, help="Path to YAML config.")
+    parser.add_argument("--run-root", default=None, help="Optional directory for run metadata/logs.")
+    parser.add_argument("--only", nargs="*", default=None, help="Optional tool filter, e.g. BINDetect.")
+    parser.add_argument("--dry-run", action="store_true", help="Print expanded commands without running.")
+    parser.add_argument("--list-jobs", action="store_true", help="List expanded jobs and exit.")
+    parser.add_argument("--fail-fast", action="store_true", help="Stop at first failed job.")
+    args = parser.parse_args()
+
+    only_tools = {canonical_tool_name(tool_name) for tool_name in (args.only or [])}
+    exit_code = run_config_file(
+        args.config,
+        run_root=args.run_root,
+        only_tools=only_tools or None,
+        dry_run=args.dry_run,
+        list_jobs=args.list_jobs,
+        fail_fast=args.fail_fast,
+    )
+    raise SystemExit(exit_code)
+
+
+def run_config_file(
+    config_path: str | os.PathLike[str],
+    run_root: str | os.PathLike[str] | None = None,
+    only_tools: set[str] | None = None,
+    dry_run: bool = False,
+    list_jobs: bool = False,
+    fail_fast: bool = False,
+) -> int:
+    config = normalize_config(load_yaml_config(config_path))
+    jobs = expand_jobs(config, only_tools=only_tools)
+    if not jobs:
+        print("No jobs matched the current config/filter.", file=sys.stderr)
+        return 1
+
+    if list_jobs or dry_run:
+        for job in jobs:
+            print(f"[{job.tool}] {job.job_id}: {' '.join(job.command)}")
+        if dry_run or list_jobs:
+            return 0
+
+    root = Path(run_root or config.get("run_root") or _default_run_root()).expanduser()
+    root.mkdir(parents=True, exist_ok=True)
+
+    batch_index = root / "batch_index.tsv"
+    with batch_index.open("w", encoding="utf-8") as handle:
+        handle.write("job_id\ttool\tstatus\texit_code\trun_dir\n")
+
+    exit_code = 0
+    for job in jobs:
+        code = run_job(job, root)
+        status = "succeeded" if code == 0 else "failed"
+        with batch_index.open("a", encoding="utf-8") as handle:
+            handle.write(f"{job.job_id}\t{job.tool}\t{status}\t{code}\t{root / job.job_id}\n")
+        if code != 0:
+            exit_code = code
+            if fail_fast:
+                break
+    return exit_code
+
+
+def run_job(job: JobSpec, run_root: Path) -> int:
+    run_dir = run_root / job.job_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    dump_yaml_config(
+        {
+            "version": 1,
+            "run_mode": "single",
+            "defaults": {},
+            "samples" if job.section == "samples" else "comparisons": [
+                {"job_id": job.job_id, "tool": job.tool, **job.params}
+            ],
+            "comparisons" if job.section == "samples" else "samples": [],
+        },
+        run_dir / "config.yml",
+    )
+
+    stdout_path = run_dir / "stdout.log"
+    stderr_path = run_dir / "stderr.log"
+    status_path = run_dir / "status.json"
+    cache_dir = run_dir / ".cache"
+    mpl_dir = run_dir / ".mplconfig"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    mpl_dir.mkdir(parents=True, exist_ok=True)
+
+    status = {
+        "tool": job.tool,
+        "job_id": job.job_id,
+        "status": "running",
+        "started_at": datetime.now().isoformat(timespec="seconds"),
+        "command": job.command,
+    }
+    status_path.write_text(json.dumps(status, indent=2), encoding="utf-8")
+
+    command = list(job.command)
+    command[0] = _resolve_executable(command[0])
+    status["command"] = command
+    status_path.write_text(json.dumps(status, indent=2), encoding="utf-8")
+    (run_dir / "command.txt").write_text(" ".join(command) + "\n", encoding="utf-8")
+
+    env = os.environ.copy()
+    env.setdefault("XDG_CACHE_HOME", str(cache_dir))
+    env.setdefault("MPLCONFIGDIR", str(mpl_dir))
+
+    with stdout_path.open("w", encoding="utf-8") as stdout_handle, stderr_path.open("w", encoding="utf-8") as stderr_handle:
+        process = subprocess.run(command, stdout=stdout_handle, stderr=stderr_handle, text=True, env=env)
+
+    status["status"] = "succeeded" if process.returncode == 0 else "failed"
+    status["finished_at"] = datetime.now().isoformat(timespec="seconds")
+    status["exit_code"] = process.returncode
+    status_path.write_text(json.dumps(status, indent=2), encoding="utf-8")
+    return process.returncode
+
+
+def _default_run_root() -> Path:
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return Path.cwd() / f"fp-tools-batch-{stamp}"
+
+
+def _resolve_executable(name: str) -> str:
+    local = Path(sys.executable).parent / name
+    if local.exists():
+        return str(local)
+    found = shutil.which(name)
+    if found:
+        return found
+    return name
+
+
+if __name__ == "__main__":
+    main()