Add codon-optimization analysis panel

Dockerfile

@@ -29,7 +29,7 @@ COPY . .
 ENV PORT=5007 \
     HOST=0.0.0.0
 
-# Hugging Face Spaces runs as UID 1000 (non-root); point caches at /tmp
+# HF Spaces runs as UID 1000; caches -> /tmp
 ENV HOME=/tmp \
     XDG_CACHE_HOME=/tmp/.cache \
     MPLCONFIGDIR=/tmp/matplotlib \

core/analysis/codon_analysis.py

@@ -0,0 +1,177 @@
+"""
+Codon-optimization analysis for an mRNA CDS.
+
+Goes beyond a single CAI number to show *where* codon usage helps or hurts
+expression:
+
+  - **Per-codon optimality** — each codon's relative adaptiveness (0–1) vs the
+    best synonymous codon for that amino acid in the host.
+  - **%MinMax profile** — the classic sliding-window measure (Clarke & Clark):
+    positive = a run of common/fast codons, negative = rare/slow codons (the
+    kind of cluster that stalls ribosomes).
+  - **Rare-codon clusters** — runs of low-optimality codons worth recoding.
+  - **Original vs optimized** — projected CAI gain and rare-codon reduction if
+    the CDS were codon-optimized for the host (reuses the existing optimizer).
+
+Pure-Python (stdlib only); reuses the host codon tables already in the project.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from core.analysis.cai import CODON_TABLES, calculate_cai
+from core.sequence_tools.codon_optimizer import CODON_TABLE, AA_TO_CODONS
+
+_STOP = {"TAA", "TAG", "TGA"}
+RARE_THRESHOLD = 0.20          # optimality below this = rare codon
+RARE_CLUSTER_MIN = 3           # consecutive rare codons → a cluster
+DEFAULT_WINDOW = 17            # codons, for the %MinMax sliding window
+
+
+def resolve_organism(organism: Optional[str]) -> str:
+    key = (organism or "human").lower().replace(" ", "").replace(".", "")
+    if key in ("ecoli", "escherichiacoli"):
+        return "ecoli"
+    return "human" if key not in CODON_TABLES else key
+
+
+def _codons(cds: str) -> List[str]:
+    s = (cds or "").upper().replace("U", "T")
+    return [s[i:i + 3] for i in range(0, len(s) - len(s) % 3, 3)]
+
+
+def _freq_stats(table: Dict[str, float]) -> Tuple[Dict[str, float], Dict[str, float], Dict[str, float], Dict[str, float]]:
+    """Per-codon synonymous frequency, and per-AA max/min/avg of those freqs."""
+    freq: Dict[str, float] = {}
+    aa_max: Dict[str, float] = {}
+    aa_min: Dict[str, float] = {}
+    aa_avg: Dict[str, float] = {}
+    for aa, syns in AA_TO_CODONS.items():
+        if aa in ("*", "Stop"):
+            continue
+        ws = [max(table.get(c, 0.0), 0.0) for c in syns]
+        tot = sum(ws)
+        fs = [w / tot if tot > 0 else 0.0 for w in ws]
+        for c, f in zip(syns, fs):
+            freq[c] = f
+        aa_max[aa] = max(fs) if fs else 0.0
+        aa_min[aa] = min(fs) if fs else 0.0
+        aa_avg[aa] = (sum(fs) / len(fs)) if fs else 0.0
+    return freq, aa_max, aa_min, aa_avg
+
+
+def per_codon_optimality(cds: str, organism: str = "human") -> List[float]:
+    """Relative adaptiveness (0–1) per non-stop codon."""
+    table = CODON_TABLES[resolve_organism(organism)]
+    # max synonymous weight per AA
+    aa_maxw = {aa: max((table.get(c, 0.0) for c in syns), default=0.0)
+               for aa, syns in AA_TO_CODONS.items()}
+    out: List[float] = []
+    for c in _codons(cds):
+        aa = CODON_TABLE.get(c)
+        if aa is None or aa in ("*", "Stop") or c in _STOP:
+            continue
+        mx = aa_maxw.get(aa, 0.0)
+        out.append((table.get(c, 0.0) / mx) if mx > 0 else 0.0)
+    return out
+
+
+def min_max_profile(cds: str, organism: str = "human",
+                    window: int = DEFAULT_WINDOW) -> Tuple[List[int], List[float]]:
+    """%MinMax per sliding window; x positions are codon indices (window centres)."""
+    table = CODON_TABLES[resolve_organism(organism)]
+    freq, aa_max, aa_min, aa_avg = _freq_stats(table)
+    codons = [c for c in _codons(cds) if CODON_TABLE.get(c) not in (None, "*", "Stop")]
+    positions: List[int] = []
+    values: List[float] = []
+    n = len(codons)
+    if n < window:
+        return positions, values
+    for i in range(n - window + 1):
+        win = codons[i:i + window]
+        actual = sum(freq.get(c, 0.0) for c in win)
+        mx = sum(aa_max.get(CODON_TABLE.get(c, ""), 0.0) for c in win)
+        mn = sum(aa_min.get(CODON_TABLE.get(c, ""), 0.0) for c in win)
+        av = sum(aa_avg.get(CODON_TABLE.get(c, ""), 0.0) for c in win)
+        if actual >= av:
+            pmm = ((actual - av) / (mx - av) * 100.0) if mx > av else 0.0
+        else:
+            pmm = (-(av - actual) / (av - mn) * 100.0) if av > mn else 0.0
+        positions.append(i + window // 2)
+        values.append(pmm)
+    return positions, values
+
+
+@dataclass
+class CodonAnalysis:
+    organism: str
+    cai: Optional[float]
+    n_codons: int
+    rare_count: int
+    rare_fraction: float
+    rare_positions: List[int] = field(default_factory=list)
+    rare_clusters: List[Tuple[int, int]] = field(default_factory=list)  # (start, end) codon idx
+    minmax_positions: List[int] = field(default_factory=list)
+    minmax_values: List[float] = field(default_factory=list)
+    optimality: List[float] = field(default_factory=list)
+    # original-vs-optimized projection
+    optimized_cai: Optional[float] = None
+    optimized_rare_count: Optional[int] = None
+    codons_changed: Optional[int] = None
+
+
+def _clusters(rare_positions: List[int], min_len: int = RARE_CLUSTER_MIN) -> List[Tuple[int, int]]:
+    if not rare_positions:
+        return []
+    runs = []
+    start = prev = rare_positions[0]
+    for p in rare_positions[1:]:
+        if p == prev + 1:
+            prev = p
+        else:
+            if prev - start + 1 >= min_len:
+                runs.append((start, prev))
+            start = prev = p
+    if prev - start + 1 >= min_len:
+        runs.append((start, prev))
+    return runs
+
+
+def analyze_codons(cds: str, organism: str = "human",
+                   window: int = DEFAULT_WINDOW,
+                   include_optimized: bool = True) -> CodonAnalysis:
+    """Full codon analysis for a CDS."""
+    org = resolve_organism(organism)
+    opt = per_codon_optimality(cds, org)
+    n = len(opt)
+    rare_positions = [i for i, w in enumerate(opt) if w < RARE_THRESHOLD]
+    mm_pos, mm_val = min_max_profile(cds, org, window)
+
+    try:
+        cai = calculate_cai(cds, org)
+    except Exception:
+        cai = None
+
+    result = CodonAnalysis(
+        organism=org, cai=cai, n_codons=n,
+        rare_count=len(rare_positions),
+        rare_fraction=(len(rare_positions) / n) if n else 0.0,
+        rare_positions=rare_positions,
+        rare_clusters=_clusters(rare_positions),
+        minmax_positions=mm_pos, minmax_values=mm_val,
+        optimality=opt,
+    )
+
+    if include_optimized and n:
+        try:
+            from core.sequence_tools.codon_optimizer import optimize_codons
+            res = optimize_codons(cds, org)
+            result.optimized_cai = res.optimized_cai
+            result.codons_changed = res.codons_changed
+            result.optimized_rare_count = len(
+                [w for w in per_codon_optimality(res.optimized_cds, org) if w < RARE_THRESHOLD]
+            )
+        except Exception:
+            pass
+    return result

tests/test_codon_analysis.py

@@ -0,0 +1,76 @@
+"""Tests for codon-optimization analysis."""
+import pytest
+
+from core.analysis.codon_analysis import (
+    resolve_organism, per_codon_optimality, min_max_profile, analyze_codons,
+    RARE_THRESHOLD,
+)
+
+# Human top-synonym codons (relative adaptiveness 1.00)
+OPTIMAL = "ATG" + "CTG" + "ATC" + "GTG" + "GCC" + "ACC"   # M L I V A T, all = 1.00
+# Rare Leu codon TTA = 0.07 in the human table
+RARE = "ATG" + "TTA" * 6                                   # M then 6 rare Leu
+
+
+class TestResolveOrganism:
+    def test_human_default(self):
+        assert resolve_organism(None) == "human"
+        assert resolve_organism("Human") == "human"
+
+    def test_ecoli_variants(self):
+        assert resolve_organism("E. coli") == "ecoli"
+        assert resolve_organism("ecoli") == "ecoli"
+
+    def test_unknown_falls_back_to_human(self):
+        assert resolve_organism("martian") == "human"
+
+
+class TestOptimality:
+    def test_optimal_codons_score_one(self):
+        opt = per_codon_optimality(OPTIMAL, "human")
+        assert len(opt) == 6
+        assert all(w == pytest.approx(1.0) for w in opt)
+
+    def test_rare_codon_below_threshold(self):
+        opt = per_codon_optimality(RARE, "human")
+        # first is ATG (1.0), rest are rare Leu
+        assert opt[0] == pytest.approx(1.0)
+        assert all(w < RARE_THRESHOLD for w in opt[1:])
+
+    def test_stop_codons_excluded(self):
+        opt = per_codon_optimality("ATG" + "TAA", "human")  # M + stop
+        assert len(opt) == 1
+
+
+class TestMinMax:
+    def test_short_sequence_returns_empty(self):
+        pos, vals = min_max_profile("ATGCTGATC", "human", window=17)
+        assert pos == [] and vals == []
+
+    def test_optimal_run_is_positive(self):
+        pos, vals = min_max_profile(OPTIMAL * 5, "human", window=10)
+        assert vals and all(v > 0 for v in vals)
+
+    def test_rare_run_is_negative(self):
+        pos, vals = min_max_profile(RARE * 4, "human", window=10)
+        assert vals and min(vals) < 0
+
+
+class TestAnalyzeCodons:
+    def test_counts_and_cai(self):
+        a = analyze_codons(OPTIMAL, "human", include_optimized=False)
+        assert a.n_codons == 6
+        assert a.rare_count == 0
+        assert a.cai is not None and a.cai > 0.9
+
+    def test_rare_clusters_detected(self):
+        a = analyze_codons(RARE, "human", include_optimized=False)
+        assert a.rare_count == 6
+        assert a.rare_clusters and a.rare_clusters[0] == (1, 6)
+
+    def test_optimization_improves_rare_heavy_cds(self):
+        a = analyze_codons(RARE, "human", include_optimized=True)
+        assert a.optimized_cai is not None
+        assert a.optimized_cai >= (a.cai or 0)
+        assert a.optimized_rare_count is not None
+        assert a.optimized_rare_count <= a.rare_count

ui/components/candidate_view.py

@@ -194,9 +194,55 @@ class CandidateView(param.Parameterized):
         return pn.Column(
             pn.pane.Plotly(fig, sizing_mode="stretch_width"),
             render_liability_panel(report),
+            self._codon_panel(seq),
             sizing_mode="stretch_width",
         )
 
+    def _codon_panel(self, seq) -> pn.viewable.Viewable:
+        """Codon-optimization analysis: %MinMax profile + rare codons + optimize projection."""
+        if not seq.cds:
+            return pn.pane.HTML(
+                '<div style="color:#64748B;font-size:12px;margin-top:10px;">'
+                'No CDS available for codon analysis.</div>')
+        from core.analysis.codon_analysis import analyze_codons
+        ca = analyze_codons(seq.cds, organism="human")
+
+        fig = go.Figure()
+        if ca.minmax_positions:
+            fig.add_trace(go.Scatter(
+                x=ca.minmax_positions, y=ca.minmax_values, mode="lines",
+                line={"color": "#0F766E", "width": 1.4}, fill="tozeroy",
+                fillcolor="rgba(15,118,110,0.10)", name="%MinMax",
+                hovertemplate="codon %{x}<br>%MinMax %{y:.0f}<extra></extra>"))
+        fig.add_hline(y=0, line_color="#94A3B8", opacity=0.6)
+        for (s, e) in ca.rare_clusters:
+            fig.add_vrect(x0=s, x1=e, fillcolor="#DC2626", opacity=0.12, line_width=0)
+        fig.update_layout(
+            title={"text": "Codon usage (%MinMax: + common / − rare)", "font": {"size": 13}},
+            xaxis_title="codon position", yaxis_title="%MinMax",
+            height=260, margin={"l": 55, "r": 20, "t": 40, "b": 40},
+            plot_bgcolor="#F8FAFC", paper_bgcolor="white", showlegend=False)
+
+        cai_str = f"{ca.cai:.3f}" if ca.cai is not None else "—"
+        proj = ""
+        if ca.optimized_cai is not None:
+            d = ca.optimized_cai - (ca.cai or 0)
+            proj = (
+                f'<div style="font-size:12px;color:#475569;margin-top:6px;">'
+                f'If codon-optimized for human: CAI <b>{cai_str} → {ca.optimized_cai:.3f}</b> '
+                f'(<span style="color:{"#059669" if d>=0 else "#DC2626"};">{d:+.3f}</span>), '
+                f'rare codons <b>{ca.rare_count} → {ca.optimized_rare_count}</b>, '
+                f'{ca.codons_changed} codon(s) changed.</div>'
+            )
+        summary = pn.pane.HTML(
+            f'<div style="font-size:12px;color:#334155;margin-top:8px;">'
+            f'<b>CAI</b> {cai_str} · <b>{ca.rare_count}</b> rare codons '
+            f'({ca.rare_fraction*100:.0f}%) · <b>{len(ca.rare_clusters)}</b> rare cluster(s) '
+            f'over {ca.n_codons} codons.</div>{proj}'
+        )
+        return pn.Column(summary, pn.pane.Plotly(fig, sizing_mode="stretch_width"),
+                         sizing_mode="stretch_width")
+
     # ── panel ─────────────────────────────────────────────────────────────────
     @param.depends("_state.worklist")
     def panel(self) -> pn.Column: