babappai 2.0.0__tar.gz

babappai-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KRISHNENDU SINHA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

babappai-2.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include babappai/py.typed
+include babappaomega/py.typed
+recursive-include babappai/data *.json
+recursive-include babappai/assets *.json
+recursive-include babappaomega/data *.json
+recursive-include babappaomega/assets *.json

babappai-2.0.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: babappai
+Version: 2.0.0
+Summary: BABAPPAi: diagnostic framework for identifiability of episodic branch-site structure
+Author: Krishnendu Sinha
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/krishnendusinha/babappai
+Project-URL: Documentation, https://github.com/krishnendusinha/babappai
+Project-URL: Source, https://github.com/krishnendusinha/babappai
+Project-URL: LegacySoftwareDOI, https://doi.org/10.5281/zenodo.18520163
+Project-URL: LegacyModelDOI, https://doi.org/10.5281/zenodo.18195869
+Keywords: episodic selection,branch-site,identifiability,evolutionary genomics,likelihood-free inference,deep learning
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Requires-Dist: numpy
+Requires-Dist: biopython
+Requires-Dist: ete3
+Requires-Dist: six
+Requires-Dist: platformdirs
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-mock>=3.14; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# BABAPPAi (`babappai`)
+
+BABAPPAi is the renamed continuation of the BABAPPAΩ codebase.
+It is a diagnostic software/manuscript ecosystem for identifiability of episodic branch-site structure.
+
+## 1) What BABAPPAi is
+
+BABAPPAi is a likelihood-free diagnostic framework that estimates whether episodic branch-site structure is statistically identifiable from finite coding-sequence alignments.
+
+## 2) What it is not
+
+- Not a classical dN/dS estimator.
+- Not a likelihood-ratio branch-site test.
+- Not definitive proof of adaptive substitution.
+
+## 3) Installation
+
+```bash
+pip install babappai
+```
+
+Optional CLI-centric install:
+
+```bash
+pipx install babappai
+```
+
+## 4) Quickstart
+
+```bash
+babappai model fetch
+babappai example write --outdir demo
+babappai run --alignment demo/aln.fasta --tree demo/tree.nwk --outdir demo_out
+```
+
+## 5) CLI reference
+
+```bash
+babappai --help
+```
+
+Core commands:
+
+```bash
+babappai run --alignment aln.fasta --tree tree.nwk --outdir results
+babappai run --alignment aln.fasta --tree tree.nwk --outdir results --tree-calibration
+babappai model fetch
+babappai model status
+babappai model verify
+babappai doctor
+babappai example write --outdir demo
+babappai validate orthogroups select --input ORTHOGROUP_DIR --outdir selection_out
+babappai validate orthogroups run --input selection_out --outdir empirical_out
+babappai validate synthetic run --simulator scripts/simulator.py --neutral-generator scripts/generate_neutral_calibration.py --outdir synthetic_out
+babappai validate report --input validation_root --outdir report_out
+babappai version
+```
+
+## 6) Output files explained
+
+`babappai run ...` emits:
+
+- `results.json`
+- `branch_summary.tsv`
+- `site_summary.tsv`
+- `interpretation.txt`
+- `run_metadata.json`
+
+Validation workflows emit additional summaries/reports (selection, empirical, synthetic, master report outputs).
+
+## 7) Interpretation of `EII_z` and `EII_01`
+
+- `EII_z`: calibrated raw identifiability score.
+- `EII_01`: bounded companion score in `[0,1]`.
+
+Deterministic transform:
+
+```text
+EII_01 = sigmoid(EII_z)
+```
+
+## 8) Definitive identifiability regimes
+
+- `0.00 <= EII_01 < 0.30` -> `not_identifiable`
+- `0.30 <= EII_01 < 0.70` -> `weak_or_ambiguous`
+- `0.70 <= EII_01 < 0.90` -> `identifiable`
+- `0.90 <= EII_01 <= 1.00` -> `strongly_identifiable`
+
+Also emitted everywhere:
+
+- `identifiable_bool = (EII_01 >= 0.70)`
+- `identifiability_extent`
+
+## 9) Legacy model download/cache/checksum/provenance notes
+
+The currently configured frozen model is a **legacy BABAPPAΩ model asset** used for backward-compatible inference in BABAPPAi.
+
+- model file: `babappaomega.pt`
+- legacy model DOI: `10.5281/zenodo.18195869`
+- URL: `https://zenodo.org/records/18195869/files/babappaomega.pt?download=1`
+- SHA-256: `657a662563af31304abcb208fc903d2770a9184632a9bab2095db4c538fed8eb`
+
+Cache uses `platformdirs.user_cache_dir("babappai")` (or `BABAPPAI_CACHE_DIR`).
+Checksum verification is always enforced.
+
+## 10) Validation and benchmarking
+
+Validation includes:
+
+- empirical orthogroup-based validation
+- simulator-driven synthetic benchmarking
+- unified report generation with figures/tables
+
+## 11) Orthogroup selection workflow
+
+Deterministic top-100 selection with hard filters and anti-cherry-picking stratification:
+
+```bash
+babappai validate orthogroups select --input ORTHOGROUP_DIR --outdir selection_out
+```
+
+Outputs:
+
+- `selected_100_orthogroups.tsv`
+- `rejected_orthogroups.tsv`
+- `orthogroup_qc_metrics.tsv`
+- `orthogroup_selection_report.txt`
+- `selection_metadata.json`
+
+## 12) Synthetic benchmarking using the supplied simulator
+
+```bash
+babappai validate synthetic run \
+  --simulator scripts/simulator.py \
+  --outdir synthetic_out \
+  --grid-config demo/synthetic_grid.json
+```
+
+Optional neutral generator integration:
+
+```bash
+babappai validate synthetic run \
+  --simulator scripts/simulator.py \
+  --neutral-generator scripts/generate_neutral_calibration.py \
+  --outdir synthetic_out
+```
+
+## 13) Neutral calibration generator integration
+
+BABAPPAi includes an adapter for external neutral calibration generators:
+
+- module: `babappai/calibration/neutral_generator_adapter.py`
+- CLI integration: `--neutral-generator PATH`
+- metadata logging includes script path, attempted command, seed, and output reference file.
+
+## 14) Reproducibility/version metadata
+
+Run/validation outputs include software version, command string, model DOI/SHA/cache path, and calibration metadata.
+
+## 15) Citation
+
+Cite BABAPPAi software release/version and, while legacy frozen model assets are still used, cite the legacy model DOI.
+
+Legacy records currently referenced for provenance:
+
+- legacy software record: `https://zenodo.org/records/18520163`
+- legacy frozen model record: `https://zenodo.org/records/18195869`
+
+## 16) Legacy BABAPPAΩ compatibility note
+
+BABAPPAi is the renamed continuation of BABAPPAΩ.
+Some legacy artifacts and DOI records still carry the BABAPPAΩ naming. These are retained for provenance and reproducibility and are explicitly marked as legacy assets.
+
+## Development quick commands
+
+```bash
+pip install -e .[test]
+pytest
+python -m build --sdist --wheel
+python -m twine check dist/*
+```

babappai-2.0.0/README.md

@@ -0,0 +1,181 @@
+# BABAPPAi (`babappai`)
+
+BABAPPAi is the renamed continuation of the BABAPPAΩ codebase.
+It is a diagnostic software/manuscript ecosystem for identifiability of episodic branch-site structure.
+
+## 1) What BABAPPAi is
+
+BABAPPAi is a likelihood-free diagnostic framework that estimates whether episodic branch-site structure is statistically identifiable from finite coding-sequence alignments.
+
+## 2) What it is not
+
+- Not a classical dN/dS estimator.
+- Not a likelihood-ratio branch-site test.
+- Not definitive proof of adaptive substitution.
+
+## 3) Installation
+
+```bash
+pip install babappai
+```
+
+Optional CLI-centric install:
+
+```bash
+pipx install babappai
+```
+
+## 4) Quickstart
+
+```bash
+babappai model fetch
+babappai example write --outdir demo
+babappai run --alignment demo/aln.fasta --tree demo/tree.nwk --outdir demo_out
+```
+
+## 5) CLI reference
+
+```bash
+babappai --help
+```
+
+Core commands:
+
+```bash
+babappai run --alignment aln.fasta --tree tree.nwk --outdir results
+babappai run --alignment aln.fasta --tree tree.nwk --outdir results --tree-calibration
+babappai model fetch
+babappai model status
+babappai model verify
+babappai doctor
+babappai example write --outdir demo
+babappai validate orthogroups select --input ORTHOGROUP_DIR --outdir selection_out
+babappai validate orthogroups run --input selection_out --outdir empirical_out
+babappai validate synthetic run --simulator scripts/simulator.py --neutral-generator scripts/generate_neutral_calibration.py --outdir synthetic_out
+babappai validate report --input validation_root --outdir report_out
+babappai version
+```
+
+## 6) Output files explained
+
+`babappai run ...` emits:
+
+- `results.json`
+- `branch_summary.tsv`
+- `site_summary.tsv`
+- `interpretation.txt`
+- `run_metadata.json`
+
+Validation workflows emit additional summaries/reports (selection, empirical, synthetic, master report outputs).
+
+## 7) Interpretation of `EII_z` and `EII_01`
+
+- `EII_z`: calibrated raw identifiability score.
+- `EII_01`: bounded companion score in `[0,1]`.
+
+Deterministic transform:
+
+```text
+EII_01 = sigmoid(EII_z)
+```
+
+## 8) Definitive identifiability regimes
+
+- `0.00 <= EII_01 < 0.30` -> `not_identifiable`
+- `0.30 <= EII_01 < 0.70` -> `weak_or_ambiguous`
+- `0.70 <= EII_01 < 0.90` -> `identifiable`
+- `0.90 <= EII_01 <= 1.00` -> `strongly_identifiable`
+
+Also emitted everywhere:
+
+- `identifiable_bool = (EII_01 >= 0.70)`
+- `identifiability_extent`
+
+## 9) Legacy model download/cache/checksum/provenance notes
+
+The currently configured frozen model is a **legacy BABAPPAΩ model asset** used for backward-compatible inference in BABAPPAi.
+
+- model file: `babappaomega.pt`
+- legacy model DOI: `10.5281/zenodo.18195869`
+- URL: `https://zenodo.org/records/18195869/files/babappaomega.pt?download=1`
+- SHA-256: `657a662563af31304abcb208fc903d2770a9184632a9bab2095db4c538fed8eb`
+
+Cache uses `platformdirs.user_cache_dir("babappai")` (or `BABAPPAI_CACHE_DIR`).
+Checksum verification is always enforced.
+
+## 10) Validation and benchmarking
+
+Validation includes:
+
+- empirical orthogroup-based validation
+- simulator-driven synthetic benchmarking
+- unified report generation with figures/tables
+
+## 11) Orthogroup selection workflow
+
+Deterministic top-100 selection with hard filters and anti-cherry-picking stratification:
+
+```bash
+babappai validate orthogroups select --input ORTHOGROUP_DIR --outdir selection_out
+```
+
+Outputs:
+
+- `selected_100_orthogroups.tsv`
+- `rejected_orthogroups.tsv`
+- `orthogroup_qc_metrics.tsv`
+- `orthogroup_selection_report.txt`
+- `selection_metadata.json`
+
+## 12) Synthetic benchmarking using the supplied simulator
+
+```bash
+babappai validate synthetic run \
+  --simulator scripts/simulator.py \
+  --outdir synthetic_out \
+  --grid-config demo/synthetic_grid.json
+```
+
+Optional neutral generator integration:
+
+```bash
+babappai validate synthetic run \
+  --simulator scripts/simulator.py \
+  --neutral-generator scripts/generate_neutral_calibration.py \
+  --outdir synthetic_out
+```
+
+## 13) Neutral calibration generator integration
+
+BABAPPAi includes an adapter for external neutral calibration generators:
+
+- module: `babappai/calibration/neutral_generator_adapter.py`
+- CLI integration: `--neutral-generator PATH`
+- metadata logging includes script path, attempted command, seed, and output reference file.
+
+## 14) Reproducibility/version metadata
+
+Run/validation outputs include software version, command string, model DOI/SHA/cache path, and calibration metadata.
+
+## 15) Citation
+
+Cite BABAPPAi software release/version and, while legacy frozen model assets are still used, cite the legacy model DOI.
+
+Legacy records currently referenced for provenance:
+
+- legacy software record: `https://zenodo.org/records/18520163`
+- legacy frozen model record: `https://zenodo.org/records/18195869`
+
+## 16) Legacy BABAPPAΩ compatibility note
+
+BABAPPAi is the renamed continuation of BABAPPAΩ.
+Some legacy artifacts and DOI records still carry the BABAPPAΩ naming. These are retained for provenance and reproducibility and are explicitly marked as legacy assets.
+
+## Development quick commands
+
+```bash
+pip install -e .[test]
+pytest
+python -m build --sdist --wheel
+python -m twine check dist/*
+```

babappai-2.0.0/babappai/__init__.py

@@ -0,0 +1,20 @@
+"""BABAPPAi package metadata exports."""
+
+from babappai.metadata import (
+    LEGACY_CODEBASE_NAME,
+    MODEL_COMPATIBILITY_NOTE,
+    PACKAGE_NAME,
+    SOFTWARE_NAME,
+    SOFTWARE_VERSION,
+)
+
+__version__ = SOFTWARE_VERSION
+
+__all__ = [
+    "__version__",
+    "PACKAGE_NAME",
+    "SOFTWARE_NAME",
+    "LEGACY_CODEBASE_NAME",
+    "MODEL_COMPATIBILITY_NOTE",
+]
+

babappai-2.0.0/babappai/assets/metadata.json

@@ -0,0 +1,8 @@
+{
+  "name": "BABAPPAi",
+  "lineage": "BABAPPAΩ",
+  "version": "2.0.0",
+  "model": "legacy_frozen",
+  "description": "BABAPPAi diagnostic identifiability software (renamed continuation of BABAPPAΩ)",
+  "provenance_note": "BABAPPAi is the renamed continuation of the BABAPPAΩ codebase."
+}

babappai-2.0.0/babappai/calibration/__init__.py

@@ -0,0 +1,100 @@
+"""BABAPPAi neutral calibration utilities and adapters."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+from babappai.metadata import MODEL_TAG
+
+
+def _get_data_dir() -> Path:
+    # Keep calibration references in the shared package data directory.
+    return Path(__file__).resolve().parent.parent / "data"
+
+
+def _get_reference_path(model_tag: str) -> Path:
+    if model_tag in {"legacy_frozen", "frozen"}:
+        suffix = "frozen"
+    else:
+        suffix = model_tag
+    return _get_data_dir() / f"neutral_reference_{suffix}.json"
+
+
+def load_neutral_reference(model_tag: str = MODEL_TAG) -> Dict[str, Dict[str, float]]:
+    path = _get_reference_path(model_tag)
+    if not path.exists():
+        raise FileNotFoundError(f"Neutral calibration file not found: {path}")
+    return json.loads(path.read_text())
+
+
+def _extract_grid(table: Dict[str, Dict[str, float]]) -> Tuple[list[int], list[int]]:
+    l_values = set()
+    k_values = set()
+    for key in table.keys():
+        parts = key.split("_")
+        l_values.add(int(parts[1]))
+        k_values.add(int(parts[3]))
+    return sorted(l_values), sorted(k_values)
+
+
+def lookup_interpolated(
+    L: int,
+    K: int,
+    table: Dict[str, Dict[str, float]],
+) -> Optional[Dict[str, float]]:
+    l_grid, k_grid = _extract_grid(table)
+    if not l_grid or not k_grid:
+        return None
+
+    l_low = max((x for x in l_grid if x <= L), default=None)
+    l_high = min((x for x in l_grid if x >= L), default=None)
+    k_low = max((x for x in k_grid if x <= K), default=None)
+    k_high = min((x for x in k_grid if x >= K), default=None)
+    if None in (l_low, l_high, k_low, k_high):
+        return None
+
+    def get(lv: int, kv: int) -> Optional[Dict[str, float]]:
+        return table.get(f"L_{lv}_K_{kv}")
+
+    q11 = get(l_low, k_low)
+    q12 = get(l_low, k_high)
+    q21 = get(l_high, k_low)
+    q22 = get(l_high, k_high)
+    if None in (q11, q12, q21, q22):
+        return None
+
+    denom = (l_high - l_low) * (k_high - k_low)
+    if denom == 0:
+        return None
+
+    def bilinear(field: str) -> float:
+        return float(
+            (
+                q11[field] * (l_high - L) * (k_high - K)
+                + q21[field] * (L - l_low) * (k_high - K)
+                + q12[field] * (l_high - L) * (K - k_low)
+                + q22[field] * (L - l_low) * (K - k_low)
+            )
+            / denom
+        )
+
+    return {"sigma2_mean": bilinear("sigma2_mean"), "sigma2_sd": bilinear("sigma2_sd")}
+
+
+def get_neutral_reference(
+    L: int,
+    K: int,
+    model_tag: str = MODEL_TAG,
+) -> Optional[Dict[str, float]]:
+    table = load_neutral_reference(model_tag)
+    return lookup_interpolated(L, K, table)
+
+
+__all__ = [
+    "_get_reference_path",
+    "get_neutral_reference",
+    "load_neutral_reference",
+    "lookup_interpolated",
+]

babappai-2.0.0/babappai/calibration/neutral_generator_adapter.py

@@ -0,0 +1,100 @@
+"""Adapter layer for external neutral calibration generator scripts."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional
+
+from babappai.calibration import _get_reference_path
+
+
+def _run_command(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=str(cwd),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def _discover_reference_file(output_dir: Path, model_tag: str) -> Optional[Path]:
+    candidates = sorted(output_dir.glob("neutral_reference*.json"))
+    if candidates:
+        return candidates[0]
+
+    package_reference = _get_reference_path(model_tag)
+    if package_reference.exists():
+        return package_reference
+    return None
+
+
+def run_neutral_generator(
+    *,
+    generator_path: str,
+    output_dir: str,
+    model_tag: str,
+    seed: Optional[int] = None,
+    extra_args: Optional[Iterable[str]] = None,
+) -> Dict[str, Any]:
+    """Execute an external neutral-generator script with robust fallback behavior."""
+
+    script = Path(generator_path).expanduser().resolve()
+    if not script.exists():
+        raise FileNotFoundError(f"Neutral generator script not found: {script}")
+
+    outdir = Path(output_dir).expanduser().resolve()
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    extra = list(extra_args or [])
+    command_with_args = [sys.executable, str(script), "--outdir", str(outdir)]
+    if seed is not None:
+        command_with_args.extend(["--seed", str(seed)])
+    command_with_args.extend(extra)
+
+    attempted_commands: list[list[str]] = [command_with_args]
+    first = _run_command(command_with_args, cwd=outdir)
+
+    if first.returncode != 0:
+        fallback = [sys.executable, str(script), *extra]
+        attempted_commands.append(fallback)
+        second = _run_command(fallback, cwd=outdir)
+        result = second
+    else:
+        result = first
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            "Neutral generator failed. "
+            f"Attempted commands: {attempted_commands}. "
+            f"stderr: {result.stderr.strip()}"
+        )
+
+    discovered = _discover_reference_file(outdir, model_tag=model_tag)
+    if discovered is None:
+        raise RuntimeError(
+            "Neutral generator completed but no neutral reference JSON was found."
+        )
+
+    copied_reference = outdir / discovered.name
+    if discovered.resolve() != copied_reference.resolve():
+        shutil.copy2(discovered, copied_reference)
+
+    metadata = {
+        "generator_path": str(script),
+        "attempted_commands": attempted_commands,
+        "seed": seed,
+        "output_dir": str(outdir),
+        "reference_file": str(copied_reference),
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+    }
+    (outdir / "neutral_generator_run_metadata.json").write_text(
+        json.dumps(metadata, indent=2) + "\n"
+    )
+    return metadata
+