feat: calibrate every head, unify the chip language, fix the modal layout

Closes #265, #266, #267, #268.

CALIBRATION EVERYWHERE (#265). Taste and Tox21 still ran on a flat 0.5 with only AUROC shown —
the exact reporting gap #261 closed for aroma and mouthfeel. Both now use the same out-of-fold
calibration with a 50% precision floor, and /api/heads publishes threshold, precision, recall and
confident_capable for all four modalities.

The taste heads were mildly shy, as expected with hundreds of positives each (sweet 0.33, umami
0.33, bitter 0.51), and all six clear the floor at 0.50-0.87. The Tox21 result is the one that
matters: every one of the twelve calibrated UPWARD — NR-AR to 0.69, NR-AR-LBD 0.65, NR-ER 0.63 —
which means a flat 0.5 had them OVER-flagging. That is the opposite direction from the thin aroma
heads and the more dangerous one, because a caution flag that cries wolf teaches people to ignore
the flags that matter.

CHIP LANGUAGE (#266). Flavor, note, taste and mouthfeel chips had each been given a different
border STYLE at a different time — dashed, dotted, thicker, plus per-taste text recolouring — so
they read as four accidents rather than one system. They now share a pill, a size and a border
weight, and carry identity in a leading dot in the family's own hue. Each studio section also
gained a plain-language paragraph on what that dimension IS and why it matters: a flavor is the
whole percept, a note is what the nose reads, taste is the basics the tongue reads, mouthfeel is
touch reported by the trigeminal nerve. Menthol is cold without a temperature change; that
distinction is load-bearing and nothing in the UI had ever said it.

ALL MODALITIES ON CARDS (#267). Substitute and neighbor cards showed taste and aroma but not
mouthfeel. Read straight off the profile matrix, whose mouthfeel columns were already there, so
it costs no extra inference — and each sensation must clear its own calibrated threshold, so a
card never shows something the modal would call indicative.

MODAL LAYOUT (#268). Two real bugs, both measured rather than guessed:

  - Mobile: the swap grid used `1fr`, which is minmax(auto,1fr), and `auto` will not shrink below
    min-content — so the substitutes and neighbors cards rendered 468px wide inside a 358px modal.
    minmax(0,1fr) fixes it; .modal-top already had this and .swap-grid did not.
  - Desktop: #results is a flex column whose 14px gap separates the cards, but the render path set
    an inline display:block on it, and block boxes ignore `gap`. The Heads card had been sitting
    flush against the Substitutes card below it. Clearing the inline style lets the stylesheet win.

Verified with a Playwright probe at 390px and 1440px: no card overflows its container at either
size, and no two cards are within 8px of each other on desktop.

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

Author: rvnminers-A-and-N

training/predict.py

@@ -1218,19 +1218,29 @@ def predict_mouthfeel(mol):
 }
 
 
-def predict_tox(mol, threshold=0.5):
+def predict_tox(mol, threshold=None):
     """Caution-only in-vitro tox-assay activity (Tox21 models). INDICATIVE flags for
-    review — NEVER a toxicity/safety determination. Honest/empty if heads untrained."""
+    review — NEVER a toxicity/safety determination. Honest/empty if heads untrained.
+
+    Each assay fires at its OWN calibrated threshold, and calibration matters more here than
+    anywhere else in the app: assay actives are rare, so a flat 0.5 made several heads
+    over-flag. Every one of the twelve calibrated UPWARD (NR-AR to 0.69, NR-ER to 0.63) — the
+    opposite direction from the thin aroma heads. A caution flag that cries wolf is worse than
+    no flag, because it teaches people to ignore the ones that matter.
+    """
     if not _TOX_MODELS:
         return {"available": False,
                 "note": "tox heads not trained — run train_tox.py (Tox21, public domain)"}
     x = _fp(mol)
     assays = []
     for name, clf in sorted(_TOX_MODELS.items()):
         p = round(float(clf.predict_proba(x)[0, 1]), 3)
+        thr = _head_threshold(_TOX_META, name, threshold)
         assays.append({"assay": name, "meaning": _TOX_MEANING.get(name, name), "probability": p,
+                       "threshold": thr, "flagged": p >= thr,
+                       "precision": _TOX_META.get(name, {}).get("cv_precision"),
                        "auroc": _TOX_META.get(name, {}).get("auroc")})
-    flags = [a["assay"] for a in assays if a["probability"] >= threshold]
+    flags = [a["assay"] for a in assays if a["flagged"]]
     return {"available": True, "assays": assays, "flags": flags,
             "note": "INDICATIVE in-vitro tox-assay activity (Tox21 RandomForest heads) — "
                     "caution-only, NOT a toxicity/safety determination; confirm with a toxicologist."}
@@ -1310,13 +1320,13 @@ def _aroma(a):
                    "desc": AROMA_DESC.get(h), **_cal(_MOUTHFEEL_META, h)}
                   for h in mouthfeel_heads]
     return {
-        # taste heads keep a flat 0.5: hundreds of positives each, so they were never shy
-        "taste": [{"head": t, "auroc": _taste_auroc(t), "threshold": 0.5,
-                   "confident_capable": True} for t in taste_heads],
+        "taste": [{"head": t, "auroc": _taste_auroc(t), **_cal(_TASTE_META, t)}
+                  for t in taste_heads],
         "aroma": [_aroma(a) for a in aroma_heads],
         "mouthfeel": mouthfeel,
         "safety": [{"head": t, "auroc": _TOX_META.get(t, {}).get("auroc"),
-                    "meaning": _TOX_MEANING.get(t, t)} for t in sorted(_TOX_MODELS)],
+                    "meaning": _TOX_MEANING.get(t, t), **_cal(_TOX_META, t)}
+                   for t in sorted(_TOX_MODELS)],
     }
 
 
@@ -1473,6 +1483,26 @@ def _predicted_tastes_at(profiles, i):
     return [t for s, t in scored[:3] if s >= 0.2]
 
 
+def _predicted_mouthfeel_at(profiles, i):
+    """The MOUTHFEEL read for reference-set row i, straight off the profile matrix — no extra
+    inference, the columns are already there. Each sensation must clear its OWN calibrated
+    threshold (and be confident-capable), so a card never shows a sensation the modal would
+    call indicative. Returns the firing sensations, strongest first."""
+    if profiles is None:
+        return []
+    taste_heads, aroma_heads, mouth_heads = _profile_heads()
+    base = len(taste_heads) + len(aroma_heads)   # mouthfeel columns follow taste then aroma
+    row, out = profiles[i], []
+    for j, name in enumerate(mouth_heads):
+        col = base + j
+        if col >= len(row):
+            break
+        score = float(row[col])
+        if score >= _head_threshold(_MOUTHFEEL_META, name) and _head_capable(_MOUTHFEEL_META, name):
+            out.append((score, name))
+    return [n for _, n in sorted(out, reverse=True)]
+
+
 def structural_neighbors(smiles: str, k: int = 8, min_similarity: float = 0.0) -> dict:
     """STRUCTURAL neighbors: the k labeled molecules most structurally similar to the query
     (Tanimoto over Morgan fingerprints), each with its known tastes. Structural look-alikes —
@@ -1504,6 +1534,7 @@ def structural_neighbors(smiles: str, k: int = 8, min_similarity: float = 0.0) -
         neighbors.append({"smiles": smis[i], "similarity": round(float(sims[i]), 3),
                           "known_tastes": tastes[i],
                           "predicted_tastes": _predicted_tastes_at(profiles, i),
+                          "mouthfeel": _predicted_mouthfeel_at(profiles, i),
                           # confident aromas precomputed once in the index — reused so the
                           # endpoint never re-runs the 24 aroma heads per neighbor (8x ~1.3s saved)
                           "aromas": _aromas[i] if i < len(_aromas) else []})
@@ -1545,6 +1576,7 @@ def substitutes(smiles: str, k: int = 8, min_match: float = 0.0) -> dict:
             continue
         subs.append({"smiles": smis[i], "profile_match": round(float(sims[i]), 3),
                      "known_tastes": tastes[i], "predicted_tastes": _predicted_tastes_at(profiles, i),
+                     "mouthfeel": _predicted_mouthfeel_at(profiles, i),
                      "aromas": aromas[i] if i < len(aromas) else []})
         if len(subs) >= k:
             break
@@ -1584,6 +1616,7 @@ def mixture_to_molecule(smiles_list: list, weights: list | None = None, k: int =
             continue
         out.append({"smiles": smis[i], "profile_match": round(float(sims[i]), 3),
                     "known_tastes": tastes[i], "predicted_tastes": _predicted_tastes_at(profiles, i),
+                     "mouthfeel": _predicted_mouthfeel_at(profiles, i),
                     "aromas": aromas[i] if i < len(aromas) else []})
         if len(out) >= k:
             break
@@ -1733,7 +1766,8 @@ def predict(smiles: str, include_aroma: bool = False) -> dict:
     # If two+ taste heads both fire high, surface that as a complex-taste note —
     # the model-side echo of ChemTastesDB's 'multitaste' class.
     strong = [t for t in ("sweet", "bitter", "umami")
-              if isinstance(out.get(t), float) and out[t] >= 0.5]
+              if isinstance(out.get(t), float)
+              and out[t] >= _head_threshold(_TASTE_META, t)]
     out["multitaste"] = len(strong) >= 2
     out["taste_profile"] = _taste_profile(out)
     out["physchem"] = physchem(mol)

training/train_taste.py

@@ -28,7 +28,10 @@
 from rdkit.Chem import DataStructs, rdFingerprintGenerator
 from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor
 from sklearn.metrics import r2_score, roc_auc_score
-from sklearn.model_selection import train_test_split
+from sklearn.model_selection import cross_val_predict, train_test_split
+from train_aroma import (
+    _calibrate,  # same out-of-fold threshold + precision floor as the aroma heads
+)
 
 BASIC = ["sweet", "bitter", "umami", "sour", "salty", "tasteless"]
 # Salty now ALSO trains as an INDICATIVE head (CV-AUROC ~0.96 once the PubChem documented-
@@ -102,9 +105,19 @@ def train_classifiers(master):
         clf = RandomForestClassifier(n_estimators=500, n_jobs=-1, random_state=42)
         clf.fit(Xtr, ytr)
         auc = roc_auc_score(yte, clf.predict_proba(Xte)[:, 1])
-        print(f"  {taste:7s} AUROC={auc:.3f}  (pos={pos}, neg={neg})")
+        # Per-head decision threshold + measured precision, same instrument as the aroma heads
+        # (train_aroma._calibrate). These heads have hundreds of positives each and were never
+        # expected to be shy — but "we measured and 0.5 was right" is a result, not a reason to
+        # skip measuring. See docs/ACCURACY.md.
+        oof = cross_val_predict(RandomForestClassifier(n_estimators=500, n_jobs=-1, random_state=42),
+                                Xv, yv, cv=5, method="predict_proba")[:, 1]
+        thr, prec, rec, f1, capable = _calibrate(yv, oof)
+        tag = "" if capable else "  INDICATIVE (never reaches 50% precision)"
+        print(f"  {taste:7s} AUROC={auc:.3f}  thr={thr:.2f} prec={prec:.2f}{tag}  (pos={pos}, neg={neg})")
         joblib.dump(clf, OUT / f"{taste}_rf.joblib")
-        manifest[taste] = {"auroc": round(float(auc), 3), "n_pos": pos, "n_neg": neg}
+        manifest[taste] = {"auroc": round(float(auc), 3), "n_pos": pos, "n_neg": neg,
+                           "threshold": thr, "cv_precision": prec, "cv_recall": rec,
+                           "cv_f1": f1, "confident_capable": capable}
     return manifest
 
 

training/train_tox.py

@@ -18,7 +18,10 @@
 from rdkit import Chem
 from rdkit.Chem import DataStructs, rdFingerprintGenerator
 from sklearn.ensemble import RandomForestClassifier
-from sklearn.model_selection import cross_val_score
+from sklearn.model_selection import cross_val_predict, cross_val_score
+from train_aroma import (
+    _calibrate,  # same out-of-fold threshold + precision floor as the aroma heads
+)
 
 FP_BITS, FP_RADIUS = 2048, 2
 _MORGAN = rdFingerprintGenerator.GetMorganGenerator(radius=FP_RADIUS, fpSize=FP_BITS)
@@ -62,9 +65,19 @@ def fp(smiles):
         continue
     clf_args = {"n_estimators": 200, "n_jobs": -1, "random_state": 42, "class_weight": "balanced"}
     auc = cross_val_score(RandomForestClassifier(**clf_args), Xd, yd, cv=5, scoring="roc_auc").mean()
+    # Calibration matters MORE here than anywhere else in the app. Assay actives are rare, so a
+    # high AUROC can sit on top of terrible precision — and a safety flag that is wrong most of
+    # the time is worse than no flag, because it teaches people to ignore the ones that matter.
+    oof = cross_val_predict(RandomForestClassifier(**clf_args), Xd, yd, cv=5,
+                            method="predict_proba")[:, 1]
+    thr, prec, rec, f1, capable = _calibrate(yd, oof)
     joblib.dump(RandomForestClassifier(**clf_args).fit(Xd, yd), OUT / f"{t}_rf.joblib")
-    manifest[t] = {"auroc": round(float(auc), 3), "n_pos": int(yd.sum()), "n": int(mask.sum())}
+    manifest[t] = {"auroc": round(float(auc), 3), "n_pos": int(yd.sum()), "n": int(mask.sum()),
+                   "threshold": thr, "cv_precision": prec, "cv_recall": rec, "cv_f1": f1,
+                   "confident_capable": capable}
     kept += 1
-    print(f"  {t:14s} n={int(mask.sum()):5d} pos={int(yd.sum()):4d}  CV-AUROC={auc:.3f}")
+    tag = "" if capable else "  INDICATIVE (never reaches 50% precision)"
+    print(f"  {t:14s} n={int(mask.sum()):5d} pos={int(yd.sum()):4d}  CV-AUROC={auc:.3f} "
+          f"thr={thr:.2f} prec={prec:.2f}{tag}")
 (OUT / "manifest.json").write_text(json.dumps({"assays": manifest}, indent=2))
 print(f"\nkept {kept}/{len(TASKS)} tox heads -> tox_models/  (caution-only, Tox21 public domain)")