Add SASA exposure gating of liability flags

Dockerfile

@@ -12,9 +12,11 @@ FROM condaforge/miniforge3:latest
 # ---- conda-only deps (pin python to mirror the verified env) --------------
 # anarci + hmmer  -> bioconda (IMGT numbering; hmmer is ANARCI's engine)
 # openmm + pdbfixer -> conda-forge (ABodyBuilder2 structure refinement)
+# biopython is used for Shrake-Rupley SASA (exposure gating of liability flags);
+# it also comes in via anarci, but pin it explicitly since the app now needs it.
 RUN mamba install -y -n base \
         -c conda-forge -c bioconda \
-        python=3.13 anarci hmmer openmm pdbfixer && \
+        python=3.13 anarci hmmer openmm pdbfixer biopython && \
     mamba clean -afy
 
 # ---- pip deps -------------------------------------------------------------

app.py

@@ -16,6 +16,7 @@ The liability flags are HEURISTIC screens, not disqualifiers. MyAbs yields in-si
 CANDIDATES, not patent-ready antibodies — wet-lab validation still required.
 """
 
+import io
 import os
 import time
 import gradio as gr
@@ -28,6 +29,13 @@ try:
 except Exception:
     HAVE_ANARCI = False
 
+try:
+    from Bio.PDB import PDBParser
+    from Bio.PDB.SASA import ShrakeRupley
+    HAVE_SASA = True
+except Exception:
+    HAVE_SASA = False
+
 print("Loading ABodyBuilder2 ensemble...")
 PREDICTOR = ABodyBuilder2()
 print("Ready.")
@@ -105,8 +113,17 @@ LEGEND_HTML = (
     + "</div>"
 )
 
-SEV_ORDER = {"High": 0, "Medium": 1, "Low": 2}
-SEV_ICON = {"High": "🔴", "Medium": "🟠", "Low": "🟡"}
+SEV_ORDER = {"High": 0, "Medium": 1, "Low": 2, "Minimal": 3}
+SEV_ICON = {"High": "🔴", "Medium": "🟠", "Low": "🟡", "Minimal": "⚪"}
+SEV_LEVELS = ["High", "Medium", "Low", "Minimal"]
+
+# Tien et al. 2013 theoretical max ASA (Ų), for relative solvent accessibility.
+MAXASA = {
+    "ALA": 129, "ARG": 274, "ASN": 195, "ASP": 193, "CYS": 167, "GLU": 223,
+    "GLN": 225, "GLY": 104, "HIS": 224, "ILE": 197, "LEU": 201, "LYS": 236,
+    "MET": 224, "PHE": 240, "PRO": 159, "SER": 155, "THR": 172, "TRP": 285,
+    "TYR": 263, "VAL": 174,
+}
 
 
 def clean(seq: str) -> str:
@@ -141,6 +158,54 @@ def cdr_of(imgt: int):
     return None
 
 
+# -------------------------------------------------------------- accessibility
+def rsa_map(pdb: str):
+    """Per-residue relative solvent accessibility from the folded Fv.
+    Returns {(chain_id, imgt_resseq): rsa} or None if SASA is unavailable.
+    Computed on the whole Fv, so the VH/VL interface counts as buried."""
+    if not HAVE_SASA or not pdb:
+        return None
+    try:
+        model = PDBParser(QUIET=True).get_structure("ab", io.StringIO(pdb))[0]
+        ShrakeRupley().compute(model, level="R")  # sets .sasa on each residue
+        out = {}
+        for chain in model:
+            for res in chain:
+                if res.resname not in MAXASA:
+                    continue
+                rsa = res.sasa / MAXASA[res.resname]
+                key = (chain.id, res.id[1])  # (chain, resseq); insertion code dropped
+                out[key] = max(out.get(key, 0.0), rsa)  # keep max across insertions
+        return out
+    except Exception:
+        return None
+
+
+def exposure_tier(rsa):
+    """buried (<15%), partial (15-30%), exposed (>=30%), or None if no RSA."""
+    if rsa is None:
+        return None
+    if rsa < 0.15:
+        return "buried"
+    if rsa < 0.30:
+        return "partial"
+    return "exposed"
+
+
+def adjust_severity(raw_sev: str, tier, desc: str) -> str:
+    """Down-rank a sequence-motif flag by how buried the residue is: buried motifs
+    can't undergo solvent-driven chemistry (oxidation, deamidation, glycosylation).
+    A free cysteine is a covalent/structural concern beyond exposure, so it is
+    never down-ranked more than one level."""
+    if tier is None:
+        return raw_sev
+    steps = {"exposed": 0, "partial": 1, "buried": 2}[tier]
+    if "cysteine" in desc.lower():
+        steps = min(steps, 1)
+    i = min(SEV_LEVELS.index(raw_sev) + steps, len(SEV_LEVELS) - 1)
+    return SEV_LEVELS[i]
+
+
 # ---------------------------------------------------------------- liabilities
 def scan_chain(chain_label: str, residues):
     """Scan one numbered chain for sequence-liability motifs.
@@ -203,10 +268,12 @@ def scan_chain(chain_label: str, residues):
     return flags, highlights
 
 
-def developability(heavy: str, light: str):
-    """Scan both chains + CDR-H3 length. Returns (flags, highlights_by_chain, h3_len, ok)."""
-    all_flags = []
-    highlights = {"H": [], "L": []}
+def developability(heavy: str, light: str, pdb: str = None):
+    """Scan both chains + CDR-H3 length, then gate by solvent exposure using the
+    folded structure. Returns (flags, highlights_by_chain, h3_len, ok).
+    Each flag: (sev, chain, imgt, desc, loc, rsa, tier) where sev is the
+    exposure-adjusted severity and rsa/tier are None when no structure is given."""
+    raw_flags = []
     h3_len = None
     ok = True
     for label, seq in (("H", heavy), ("L", light)):
@@ -214,15 +281,29 @@ def developability(heavy: str, light: str):
         if residues is None:
             ok = False
             continue
-        flags, hi = scan_chain(label, residues)
-        all_flags += flags
-        highlights[label] += hi
+        flags, _hi = scan_chain(label, residues)
+        raw_flags += flags
         if label == "H":
             h3_len = sum(1 for (imgt, _ins, _aa) in residues if 105 <= imgt <= 117)
             if h3_len >= 18:
-                all_flags.append(("High", "H", 105,
+                raw_flags.append(("High", "H", 105,
                                   f"Long CDR-H3 ({h3_len} aa) — aggregation risk", "CDR-H3"))
-    return all_flags, highlights, h3_len, ok
+
+    # Exposure-gate each flag against the folded structure (if available).
+    rmap = rsa_map(pdb)
+    enriched = []
+    highlights = {"H": [], "L": []}
+    for sev, chain, imgt, desc, loc in raw_flags:
+        # CDR-H3 length is a whole-loop property, not single-residue exposure.
+        is_h3len = desc.startswith("Long CDR-H3")
+        rsa = None if is_h3len else (rmap.get((chain, imgt)) if rmap else None)
+        tier = exposure_tier(rsa)
+        adj = sev if is_h3len else adjust_severity(sev, tier, desc)
+        enriched.append((adj, chain, imgt, desc, loc, rsa, tier))
+        # Paint only residues whose flag survives exposure gating (High/Medium).
+        if adj in ("High", "Medium") and not is_h3len and chain in highlights:
+            highlights[chain].append(imgt)
+    return enriched, highlights, h3_len, ok
 
 
 def format_flags(flags, h3_len, ok):
@@ -235,27 +316,43 @@ def format_flags(flags, h3_len, ok):
                 "No glycosylation sequons, PTM hotspots, or free cysteines found in the CDRs "
                 "or framework"
                 + (f", and CDR-H3 length is normal ({h3_len} aa)" if h3_len else "")
-                + ".\n\n_Structure-based hydrophobic-patch scoring is the next add._")
+                + ".")
 
     flags_sorted = sorted(flags, key=lambda f: (SEV_ORDER[f[0]], f[1], f[2]))
     highs = sum(1 for f in flags if f[0] == "High")
     meds = sum(1 for f in flags if f[0] == "Medium")
     lows = sum(1 for f in flags if f[0] == "Low")
+    mins = sum(1 for f in flags if f[0] == "Minimal")
+    have_exposure = any(f[6] is not None for f in flags)
+
+    def _exp_cell(rsa, tier):
+        if rsa is None:
+            return "—"
+        return f"{tier} ({rsa * 100:.0f}%)"
 
+    tally = f"{highs} high · {meds} medium · {lows} low"
+    if mins:
+        tally += f" · {mins} minimal"
     lines = [
-        f"### Developability flags — {highs} high · {meds} medium · {lows} low",
-        "Flagged residues are drawn as **magenta sticks** on the structure.",
-        "",
-        "| Severity | Chain | IMGT | Location | Liability |",
-        "|---|---|---|---|---|",
-    ]
-    for sev, chain, imgt, desc, loc in flags_sorted:
-        lines.append(f"| {SEV_ICON[sev]} {sev} | {chain} | {imgt} | {loc} | {desc} |")
-    lines += [
+        f"### Developability flags — {tally}",
+        ("Severity is **adjusted by solvent exposure** from the fold: buried motifs are "
+         "down-ranked because they can't undergo solvent-driven chemistry. Surviving "
+         "(high/medium) liabilities are drawn as **magenta sticks** on the structure."
+         if have_exposure else
+         "Flagged residues are drawn as **magenta sticks** on the structure."),
         "",
-        "_Heuristic sequence-liability flags, not disqualifiers. Liabilities in CDRs matter "
-        "most (exposed, near the paratope). Confirm experimentally before acting._",
+        "| Severity | Exposure | Chain | IMGT | Location | Liability |",
+        "|---|---|---|---|---|---|",
     ]
+    for sev, chain, imgt, desc, loc, rsa, tier in flags_sorted:
+        lines.append(
+            f"| {SEV_ICON[sev]} {sev} | {_exp_cell(rsa, tier)} | {chain} | {imgt} | {loc} | {desc} |"
+        )
+    footer = ("_Heuristic screens, not disqualifiers. Exposure (relative solvent accessibility) "
+              "sharpens the ranking but is not the whole story: an exposed motif can still be "
+              "fine (far from the paratope, slow kinetics, controlled by formulation). Confirm "
+              "experimentally before acting._")
+    lines += ["", footer]
     return "\n".join(lines)
 
 
@@ -306,7 +403,7 @@ def fold(heavy: str, light: str):
                 f"Error: {e}", "", None, "", {}, False, reset_btn)
 
     pdb = open("myabs_fold.pdb").read()
-    flags, highlights, h3_len, ok = developability(heavy, light)
+    flags, highlights, h3_len, ok = developability(heavy, light, pdb)
     viewer = render_structure(pdb, spin=False, highlights=highlights)
     status = (f"Folded in {dt:.1f} s  ·  VH {len(heavy)} aa / VL {len(light)} aa  ·  "
               f"CDRs highlighted (H: yellow/orange/red, L: cyan/blue).")