feat: no head looks empty on the map; cap the shareable card; pin safety across stereoisomers (#249)

#238 — five assertions pin that food-use status, structural alerts, per-assay tox probabilities and
the assembled safety block are identical across enantiomer pairs (carvone/limonene/menthol), since
all three key on connectivity rather than stereochemistry. Verified the test fails if the lookup is
made stereo-aware. Sensory reads may legitimately differ between enantiomers; safety must not.

#233 — GET /api/map_members returns true membership (head >= 0.5) from the profile index, so heads
that never win the map's winner-take-all colour no longer highlight nothing. clarysage 25 members,
violetleaf 21, blackpepper 14. Zero-count legend entries are clickable; one mapHit() predicate now
serves the 2D, properties and 3D views.

#236 — the shareable PNG rendered all 164 aroma cells and omitted mouthfeel/safety. Now the 6 tastes
always render and everything else shows only what fires (aroma capped at 18, Tox21 only when
flagged, caution-only wording), with labels stating the subset honestly. Layout adapts: vanillin
692px, menthol 766px, capsaicin 840px.

Closes #238. Closes #233. Closes #236.

Author: rvnminers-A-and-N

tests/test_stereo_safety.py

@@ -0,0 +1,76 @@
+"""Safety calls must be IDENTICAL across stereoisomers.
+
+Food-use status, the structural-alert screen and the Tox21 heads all key on the molecule's
+CONNECTIVITY, not its stereochemistry — food-use listings key on the InChIKey skeleton (first
+block), and the Morgan fingerprint the tox heads read is generated without chirality. So a food-use
+listing or a tox flag on carvone necessarily covers BOTH (R)- and (S)-carvone.
+
+That is the correct and intended behaviour — a regulator lists the substance, not one enantiomer —
+but it rests on implementation details that nothing else pins down. Chirality-aware reads (#218)
+would touch exactly this machinery, so these tests exist to make any future change that silently
+splits safety by stereochemistry fail loudly instead of quietly under-reporting a hazard.
+
+Note the deliberate asymmetry: *sensory* reads MAY legitimately differ between enantiomers
+((R)-carvone is spearmint, (S)-carvone is caraway) — that difference is documented, not predicted.
+Safety must not.
+"""
+import predict
+from rdkit import Chem
+
+# (name, R-enantiomer SMILES, S-enantiomer SMILES) — classic flavor enantiomer pairs
+PAIRS = [
+    ("carvone", "CC(=C)[C@@H]1CC=C(C)C(=O)C1", "CC(=C)[C@H]1CC=C(C)C(=O)C1"),
+    ("limonene", "CC(=C)[C@@H]1CCC(C)=CC1", "CC(=C)[C@H]1CCC(C)=CC1"),
+    ("menthol", "C[C@@H]1CC[C@H](C(C)C)[C@@H](O)C1", "C[C@H]1CC[C@@H](C(C)C)[C@H](O)C1"),
+]
+
+
+def _both(pair):
+    _, a, b = pair
+    return Chem.MolFromSmiles(a), Chem.MolFromSmiles(b)
+
+
+def test_enantiomers_share_an_inchikey_skeleton():
+    """The whole guarantee rests on this: stereoisomers differ only past the first InChIKey block."""
+    for pair in PAIRS:
+        ma, mb = _both(pair)
+        assert ma is not None and mb is not None, f"{pair[0]}: unparseable test SMILES"
+        # genuinely different molecules...
+        assert Chem.MolToSmiles(ma) != Chem.MolToSmiles(mb), f"{pair[0]}: SMILES are not distinct"
+        # ...that nonetheless share a connectivity skeleton
+        ska = Chem.MolToInchiKey(ma).split("-")[0]
+        skb = Chem.MolToInchiKey(mb).split("-")[0]
+        assert ska == skb, f"{pair[0]}: skeletons differ ({ska} vs {skb})"
+
+
+def test_food_use_status_is_identical_across_stereoisomers():
+    for pair in PAIRS:
+        ma, mb = _both(pair)
+        assert predict._gras_status(ma) == predict._gras_status(mb), (
+            f"{pair[0]}: food-use status differs between enantiomers — a listing must cover both")
+
+
+def test_structural_alerts_are_identical_across_stereoisomers():
+    for pair in PAIRS:
+        ma, mb = _both(pair)
+        assert predict._tox_alerts(ma) == predict._tox_alerts(mb), (
+            f"{pair[0]}: structural alerts differ between enantiomers")
+
+
+def test_tox_screen_is_identical_across_stereoisomers():
+    """Skipped when the Tox21 heads aren't present (CI has no model artifacts)."""
+    if not predict._TOX_MODELS:
+        return
+    for pair in PAIRS:
+        ma, mb = _both(pair)
+        pa = {a["assay"]: a["probability"] for a in predict.predict_tox(ma)["assays"]}
+        pb = {a["assay"]: a["probability"] for a in predict.predict_tox(mb)["assays"]}
+        assert pa == pb, f"{pair[0]}: tox-assay probabilities differ between enantiomers"
+
+
+def test_safety_block_is_identical_across_stereoisomers():
+    """The assembled safety payload, not just its parts — catches a future field that splits."""
+    for pair in PAIRS:
+        ma, mb = _both(pair)
+        assert predict._safety(ma) == predict._safety(mb), (
+            f"{pair[0]}: assembled safety block differs between enantiomers")

training/app.py

@@ -583,9 +583,25 @@ def font(path, size):
                  "tasteless": out.get("tasteless")}
     taste_cells = sorted(((t, float(v) if isinstance(v, (int, float)) else 0.0)
                           for t, v in taste_src.items()), key=lambda kv: -kv[1])
+    # The card is a shareable SNAPSHOT — a PNG can't scroll, and there are 187 heads. So: the 6
+    # tastes ALWAYS render (a complete, fixed row you can compare across cards), while aroma,
+    # mouthfeel and safety show only what actually FIRES, capped. The labels say "N of M" so a
+    # reader knows they're seeing the firing subset, not the whole model.
+    AROMA_CAP = 18                                   # 3 rows of 6 — keeps the card readable
     pa = P.predict_aroma(smi)
-    aroma_cells = sorted(((d["odor"], d["score"]) for d in pa.get("descriptors", [])),
-                         key=lambda kv: -kv[1])
+    _all_aroma = sorted(((d["odor"], d["score"]) for d in pa.get("descriptors", [])),
+                        key=lambda kv: -kv[1])
+    _fired = [c for c in _all_aroma if c[1] >= 0.5]
+    aroma_cells = (_fired or _all_aroma[:3])[:AROMA_CAP]   # nothing firing -> top 3, never a blank card
+    aroma_total, aroma_fired = len(_all_aroma), len(_fired)
+
+    _mol = Chem.MolFromSmiles(smi)
+    mouth_cells = [(d["sensation"], d["score"])
+                   for d in (P.predict_mouthfeel(_mol).get("descriptors", []) if _mol else [])
+                   if d["score"] >= 0.5]
+    tox_cells = [(a["assay"], a["probability"])
+                 for a in ((out.get("safety") or {}).get("tox_screen") or {}).get("assays", [])
+                 if (a.get("probability") or 0) >= 0.5]
 
     pill_items = ([(fl, cream) for fl in tags.get("flavors", [])[:3]]
                   + [(t, _TASTE_RGB.get(t, teal)) for t in tags.get("tastes", [])]
@@ -611,6 +627,15 @@ def font(path, size):
     aroma_grid_y = aroma_label_y + 22
     aroma_rows = (len(aroma_cells) + COLS - 1) // COLS
     content_bottom = aroma_grid_y + aroma_rows * ROW_H
+    # mouthfeel + safety only take space when something actually fires
+    mouth_label_y = content_bottom + 12 if mouth_cells else None
+    mouth_row_y = (mouth_label_y + 22) if mouth_cells else None
+    if mouth_cells:
+        content_bottom = mouth_row_y + ((len(mouth_cells) + COLS - 1) // COLS) * ROW_H
+    tox_label_y = content_bottom + 12 if tox_cells else None
+    tox_row_y = (tox_label_y + 22) if tox_cells else None
+    if tox_cells:
+        content_bottom = tox_row_y + ((len(tox_cells) + COLS - 1) // COLS) * ROW_H
     H = max(560, content_bottom + 56)
 
     img = Image.new("RGB", (W, H), (15, 19, 25))
@@ -678,11 +703,29 @@ def cell(col, cy, label, v, color):
     for i, (t, v) in enumerate(taste_cells):
         cell(i, taste_row_y, t, v, _TASTE_RGB.get(t, teal))
 
-    # AROMA MODEL — all 24 heads in a 6-wide grid
-    dr.text((GX0, aroma_label_y), f"AROMA MODEL · all {len(aroma_cells)} heads", font=f_lab, fill=muted)
+    # AROMA MODEL — only the heads that fire, capped; label states the subset honestly
+    _shown = len(aroma_cells)
+    _alab = (f"AROMA MODEL · {_shown} of {aroma_total} heads firing"
+             + (f" (top {_shown} shown)" if aroma_fired > _shown else "")
+             if aroma_fired else f"AROMA MODEL · none of {aroma_total} heads firing · strongest {_shown}")
+    dr.text((GX0, aroma_label_y), _alab, font=f_lab, fill=muted)
     for i, (a, v) in enumerate(aroma_cells):
         cell(i % COLS, aroma_grid_y + (i // COLS) * ROW_H, a, v, teal)
 
+    # MOUTHFEEL — trigeminal sensations, only what fires
+    if mouth_cells:
+        dr.text((GX0, mouth_label_y), f"MOUTHFEEL · {len(mouth_cells)} of 5 sensations firing",
+                font=f_lab, fill=muted)
+        for i, (m, v) in enumerate(mouth_cells):
+            cell(i % COLS, mouth_row_y + (i // COLS) * ROW_H, m, v, cream)
+
+    # SAFETY — Tox21 assays, only when flagged; caution-only, never a determination
+    if tox_cells:
+        dr.text((GX0, tox_label_y), f"SAFETY · {len(tox_cells)} Tox21 assay(s) flagged — caution-only, "
+                "indicative in-vitro activity, NOT a toxicity determination", font=f_lab, fill=muted)
+        for i, (a, v) in enumerate(tox_cells):
+            cell(i % COLS, tox_row_y + (i // COLS) * ROW_H, a, v, (192, 85, 58))
+
     # footer
     fy = H - 54
     dr.line([40, fy, W - 40, fy], fill=(42, 50, 60), width=1)
@@ -1907,6 +1950,40 @@ def _svg_cell(smi):
     return _svg(smi, 104, 62)
 
 
+@app.get("/api/map_members")
+@lru_cache(maxsize=512)
+def api_map_members(term: str = "", threshold: float = 0.5):
+    """Every molecule whose head `term` fires >= threshold — not just the ones where it happens to
+    be the DOMINANT label.
+
+    The map colours each molecule by a single winning label, so a head can read "0" in the legend
+    while still being trained on plenty of molecules — they're simply displayed under a rarer
+    co-occurring label. Highlighting from the legend used to match that winner-take-all label, so
+    those heads lit up nothing and looked broken. This returns true membership from the profile
+    index (which carries every head score for every molecule), so no head can ever look empty.
+
+    `term` may be bare ("clarysage") or dimension-qualified ("aroma:clarysage", "mouthfeel:cooling")
+    — bare names resolve to aroma first, matching how the map legend labels them.
+    """
+    t = (term or "").strip().lower()
+    if not t:
+        return {"term": term, "smiles": [], "n": 0}
+    P._ensure_sub_index()
+    smis, profiles, dims = P._SUB_INDEX[1], P._SUB_INDEX[4], P._SUB_INDEX[5]
+    if profiles is None or not smis:
+        return {"term": term, "smiles": [], "n": 0, "note": "profile index not built"}
+    dims = [str(d) for d in dims]
+    col = None
+    for cand in ([t] if ":" in t else [f"aroma:{t}", f"taste:{t}", f"mouthfeel:{t}"]):
+        if cand in dims:
+            col = dims.index(cand)
+            break
+    if col is None:
+        return {"term": term, "smiles": [], "n": 0, "note": "no such head"}
+    hits = [smis[i] for i in range(len(smis)) if float(profiles[i][col]) >= threshold]
+    return {"term": term, "dim": dims[col], "threshold": threshold, "n": len(hits), "smiles": hits}
+
+
 @lru_cache(maxsize=8192)
 def _tox_flags(smiles):
     """Tox21 assays this molecule is predicted active in (>=0.5), as a tuple. Caution-only: assay

training/workbench.html

@@ -219,7 +219,9 @@
   .map-legend span{display:inline-flex;align-items:center;gap:5px;cursor:pointer;padding:2px 8px;border-radius:20px;border:1px solid transparent;transition:all .12s}
   .map-legend span:hover{border-color:var(--line)}
   .map-legend span.on{border-color:var(--brand-2);background:rgba(43,196,196,.10);color:var(--ink)}
-  .map-legend span.leg-zero{opacity:.42;cursor:default}
+  /* a (0) head is dimmed but still CLICKABLE — it has molecules, it just never wins the colour */
+  .map-legend span.leg-zero{opacity:.55;cursor:pointer}
+  .map-legend span.leg-zero:hover{opacity:.9}
   .map-legend span.leg-zero:hover{border-color:transparent}
   .map-legend i{width:10px;height:10px;border-radius:50%;display:inline-block}
   .map-controls{display:flex;flex-wrap:wrap;align-items:center;gap:12px;margin:10px 0 8px}
@@ -2086,6 +2088,15 @@ <h4>Software &amp; type</h4>
   mapLegendRender(); drawMap();
 }
 let _mapHi = new Set();  // classes highlighted from the legend (empty = show all evenly)
+const _mapMembers = new Map();  // class -> Set(smiles) of TRUE members (head >= 0.5), from /api/map_members
+// A point is spotlit if its dominant label is picked OR the head actually fires on it. Without the
+// second test, heads that never win the winner-take-all colour highlight nothing and look broken.
+function mapHit(p){
+  if(!_mapHi.size) return true;
+  if(_mapHi.has(mapLabel(p))) return true;
+  for(const l of _mapHi){ const m=_mapMembers.get(l); if(m && m.has(p.smiles)) return true; }
+  return false;
+}
 function mapLegendRender(){
   const counts={}; _mapPts.forEach(p=>counts[mapLabel(p)]=(counts[mapLabel(p)]||0)+1);
   // COMPLETE key: EVERY canonical class for the mode (all 6 taste heads / all 164 aroma heads /
@@ -2097,10 +2108,24 @@ <h4>Software &amp; type</h4>
   const labs=present.concat(empty); if(counts.other) labs.push('other');
   $('mapLegend').innerHTML=labs.map(l=>{
     const n=counts[l]||0, zero=n===0;
-    return `<span class="leg${_mapHi.has(l)?' on':''}${zero?' leg-zero':''}" data-l="${l.replace(/"/g,'&quot;')}"><i style="background:${legendColor(l)}"></i>${l} (${n})</span>`;
+    // A "(0)" head isn't empty — it just never WINS the winner-take-all colour. Clicking it
+    // fetches true membership (every molecule the head predicts >=0.5), so no head looks broken.
+    const t = zero ? `${l}: no molecule shows this as its dominant note — click to highlight every molecule the head predicts`
+                   : `${n} molecule${n===1?'':'s'} show ${l} as their dominant note — click to spotlight`;
+    return `<span class="leg${_mapHi.has(l)?' on':''}${zero?' leg-zero':''}" data-l="${l.replace(/"/g,'&quot;')}" title="${t.replace(/"/g,'&quot;')}"><i style="background:${legendColor(l)}"></i>${l} (${n})</span>`;
   }).join('');
-  $('mapLegend').querySelectorAll('.leg:not(.leg-zero)').forEach(s=> s.addEventListener('click', ()=>{
-    const l=s.dataset.l; if(_mapHi.has(l)) _mapHi.delete(l); else _mapHi.add(l); mapLegendRender(); drawMap();
+  $('mapLegend').querySelectorAll('.leg').forEach(s=> s.addEventListener('click', async ()=>{
+    const l=s.dataset.l;
+    if(_mapHi.has(l)){ _mapHi.delete(l); _mapMembers.delete(l); }
+    else {
+      _mapHi.add(l);
+      // pull true membership so a zero-count (or merely under-represented) head still lights up
+      if(l!=='other' && !_mapMembers.has(l)){
+        try{ const d=await getJSON('/api/map_members?term='+encodeURIComponent(l));
+             _mapMembers.set(l, new Set(d.smiles||[])); }catch(_){ _mapMembers.set(l, new Set()); }
+      }
+    }
+    mapLegendRender(); drawMap();
   }));
 }
 
@@ -2132,7 +2157,7 @@ <h4>Software &amp; type</h4>
   ctx.save(); ctx.globalCompositeOperation='lighter';
   for(const p of _mapPts){
     const l=mapLabel(p); if(!l||l==='other') continue;
-    if(hl && !_mapHi.has(l)) continue;
+    if(hl && !mapHit(p)) continue;
     const s=screenOf(p); if(!s||s.x<-9000||!isFinite(s.x)||!isFinite(s.y)) continue;
     ctx.fillStyle=mapColor(p); ctx.globalAlpha=A;
     ctx.beginPath(); ctx.arc(s.x,s.y,R,0,7); ctx.fill();
@@ -2172,10 +2197,10 @@ <h4>Software &amp; type</h4>
   drawDensity(ctx, p=>({x:px(p),y:py(p)}));
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';  // glow only on shown/highlighted points (subtle by default)
-  for(const p of _mapPts){ if(hl && !_mapHi.has(mapLabel(p))) continue; const x=px(p),y=py(p); ctx.fillStyle=mapColor(p);
+  for(const p of _mapPts){ if(hl && !mapHit(p)) continue; const x=px(p),y=py(p); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(x,y,hl?5.2:3.2,0,7); ctx.globalAlpha=hl?.16:.045; ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const p of _mapPts){ const on=!hl||_mapHi.has(mapLabel(p)),x=px(p),y=py(p);
+  for(const p of _mapPts){ const on=!hl||mapHit(p),x=px(p),y=py(p);
     ctx.fillStyle=on?mapColor(p):'#39424C'; ctx.beginPath(); ctx.arc(x,y,on?2.4:1.4,0,7); ctx.globalAlpha=on?(hl?.96:.82):.16; ctx.fill(); }
   ctx.globalAlpha=1;
   ctx.globalAlpha=1; _mapProj={px,py};
@@ -2221,10 +2246,10 @@ <h4>Software &amp; type</h4>
   // points
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';
-  for(const p of _mapPts){ if(p.mw==null||p.logp==null||(hl&&!_mapHi.has(mapLabel(p)))) continue; const x=bx(p.mw),y=by(p.logp); ctx.fillStyle=mapColor(p);
+  for(const p of _mapPts){ if(p.mw==null||p.logp==null||(hl&&!mapHit(p))) continue; const x=bx(p.mw),y=by(p.logp); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(x,y,hl?5:3,0,7); ctx.globalAlpha=hl?.15:.04; ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const p of _mapPts){ if(p.mw==null||p.logp==null) continue; const on=!hl||_mapHi.has(mapLabel(p)),x=bx(p.mw),y=by(p.logp);
+  for(const p of _mapPts){ if(p.mw==null||p.logp==null) continue; const on=!hl||mapHit(p),x=bx(p.mw),y=by(p.logp);
     ctx.fillStyle=on?mapColor(p):'#39424C'; ctx.beginPath(); ctx.arc(x,y,on?2.4:1.4,0,7); ctx.globalAlpha=on?(hl?.95:.8):.15; ctx.fill(); }
   ctx.globalAlpha=1;
   ctx.globalAlpha=1;
@@ -2283,10 +2308,10 @@ <h4>Software &amp; type</h4>
   drawDensity(ctx, p=>{ const s=proj(p); return {x:s.sx,y:s.sy}; });
   const hl=_mapHi.size;
   ctx.globalCompositeOperation='lighter';  // glow with depth; subtle by default, strong when highlighting
-  for(const {p,pr} of all){ if(hl && !_mapHi.has(mapLabel(p))) continue; const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=mapColor(p);
+  for(const {p,pr} of all){ if(hl && !mapHit(p)) continue; const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=mapColor(p);
     ctx.beginPath(); ctx.arc(pr.sx,pr.sy,rr*(hl?2.1:1.5),0,7); ctx.globalAlpha=a*(hl?.2:.07); ctx.fill(); }
   ctx.globalCompositeOperation='source-over';
-  for(const {p,pr} of all){ const on=!hl||_mapHi.has(mapLabel(p)); const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=on?mapColor(p):'#39424C';
+  for(const {p,pr} of all){ const on=!hl||mapHit(p); const t=pr.d+0.5, rr=1.7+2.1*t, a=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fillStyle=on?mapColor(p):'#39424C';
     ctx.beginPath(); ctx.arc(pr.sx,pr.sy,on?rr:rr*.7,0,7); ctx.globalAlpha=on?a:a*.28; ctx.fill(); }
   ctx.globalAlpha=1; _mapProj={px:p=>proj(p).sx, py:p=>proj(p).sy};
 }