Tooluniverse Drug Synergy

#!/usr/bin/env python3
"""Side-by-side synergy reference expectations for the
tooluniverse-drug-synergy skill.

Given the single-agent and combination fractional inhibition at one dose pair,
prints the Bliss, HSA, and simple-additive expected combination effects and the
corresponding synergy scores, so you can see at a glance whether the reference
models agree before running the full DrugSynergy_* tools (which also handle
dose-response models Loewe / CI / ZIP).

Inputs are FRACTIONAL inhibition (0-1). For % viability, convert first:
inhibition = 1 - viability/100.

Usage:
  python synergy_reference.py --ea 0.4 --eb 0.3 --ecombo 0.7
"""

import argparse


def _call(score):
    if score > 0.10:
        return "synergy"
    if score < -0.10:
        return "antagonism"
    return "additive"


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--ea", type=float, required=True, help="fractional inhibition of drug A (0-1)")
    ap.add_argument("--eb", type=float, required=True, help="fractional inhibition of drug B (0-1)")
    ap.add_argument("--ecombo", type=float, required=True, help="fractional inhibition of A+B (0-1)")
    args = ap.parse_args()

    ea, eb, ec = args.ea, args.eb, args.ecombo
    for v, name in ((ea, "ea"), (eb, "eb"), (ec, "ecombo")):
        if not 0 <= v <= 1:
            raise SystemExit(f"{name}={v} is not a fraction in [0,1]; convert % viability to 1-viability/100.")

    bliss_exp = ea + eb - ea * eb
    hsa_exp = max(ea, eb)
    additive_exp = min(1.0, ea + eb)

    print(f"\nObserved combination effect: {ec:.3f}  (single agents: A={ea:.3f}, B={eb:.3f})\n")
    print(f"{'Model':<26}{'expected':>10}{'score':>10}   call")
    for name, exp in (
        ("Bliss independence", bliss_exp),
        ("HSA (highest single)", hsa_exp),
        ("Simple additive (capped)", additive_exp),
    ):
        score = ec - exp
        print(f"{name:<26}{exp:>10.3f}{score:>10.3f}   {_call(score)}")

    if ec >= 0.95 and min(ea, eb) >= 0.9:
        print("\n  ! both single agents near-complete inhibition — ceiling effect; little headroom to detect synergy.")
    print("\nFor Loewe / Combination Index / ZIP (dose-response or matrix models) use the DrugSynergy_* tools.")


if __name__ == "__main__":
    main()

"""Tests for the drug-synergy skill helper script."""

import pathlib
import subprocess
import sys

import pytest

SCRIPT = pathlib.Path(__file__).parent / "scripts" / "synergy_reference.py"
sys.path.insert(0, str(SCRIPT.parent))
import synergy_reference as sr  # noqa: E402

pytestmark = pytest.mark.unit


def test_call_thresholds():
    assert sr._call(0.2) == "synergy"
    assert sr._call(0.0) == "additive"
    assert sr._call(-0.2) == "antagonism"
    # boundary: just inside +/-0.10 is additive
    assert sr._call(0.10) == "additive"
    assert sr._call(0.11) == "synergy"


def test_bliss_expected_matches_tool():
    # Bliss: E_exp = ea + eb - ea*eb; for 0.4,0.3 -> 0.58, score (0.7-0.58)=0.12
    out = subprocess.run(
        [sys.executable, str(SCRIPT), "--ea", "0.4", "--eb", "0.3", "--ecombo", "0.7"],
        capture_output=True,
        text=True,
        check=True,
    ).stdout
    assert "0.580" in out  # Bliss expected
    assert "0.120" in out  # Bliss synergy score (matches DrugSynergy_calculate_bliss)
    assert "synergy" in out


def test_rejects_out_of_range_fraction():
    r = subprocess.run(
        [sys.executable, str(SCRIPT), "--ea", "40", "--eb", "0.3", "--ecombo", "0.7"],
        capture_output=True,
        text=True,
    )
    assert r.returncode != 0
    assert "fraction" in (r.stderr + r.stdout).lower()