Overhaul the flavor map: UMAP, 2D zoom/pan + rotatable 3D, legend + key (#93)

- build_flavor_map.py now uses UMAP with the Jaccard metric (the right similarity for
  binary Morgan fingerprints — same family as Tanimoto) and embeds to BOTH 2D and 3D.
- /api/map serves normalized 2D (x,y) + 3D (x3,y3,z3) coordinates with names.
- Map UI: a 2D/3D toggle. 2D scatter with scroll-to-zoom + drag-to-pan; 3D is a
  drag-to-rotate, depth-shaded point cloud. Richer hover (name + colored taste + SMILES),
  a color legend with counts, a Reset view button, and a 'how to read it' key explaining
  that position = structural similarity, color = dominant taste, axes are unitless.

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

Author: rvnminers-A-and-N

training/app.py

@@ -389,18 +389,25 @@ def api_top(category: str = "", limit: int = 24):
 
 
 def _load_flavor_map():
-    """The 2D flavor-space embedding (flavor_map.parquet, built by build_flavor_map.py),
-    coordinates normalized to 0..1 with names attached — served as an interactive scatter."""
+    """The flavor-space embedding (flavor_map.parquet, built by build_flavor_map.py): 2D (x,y)
+    + 3D (x3,y3,z3) coordinates normalized to 0..1 with names — an interactive scatter / cloud."""
     try:
         import pandas as pd
         df = pd.read_parquet("flavor_map.parquet")
-        xs, ys = df["x"], df["y"]
-        x0, xr = xs.min(), (xs.max() - xs.min()) or 1.0
-        y0, yr = ys.min(), (ys.max() - ys.min()) or 1.0
+
+        def norm(col):
+            v = df[col]
+            lo, rng = v.min(), (v.max() - v.min()) or 1.0
+            return ((v - lo) / rng).round(4)
+
+        cols = {c: norm(c).tolist() for c in ("x", "y", "x3", "y3", "z3") if c in df.columns}
+        smis, labs = df["smiles"].tolist(), df["label"].tolist()
         pts = []
-        for smi, lab, x, y in zip(df["smiles"], df["label"], xs, ys):
-            pts.append({"x": round((x - x0) / xr, 4), "y": round((y - y0) / yr, 4),
-                        "label": lab, "smiles": smi, "name": _table_name(smi) or ""})
+        for i in range(len(smis)):
+            p = {"label": labs[i], "smiles": smis[i], "name": _table_name(smis[i]) or ""}
+            for c, v in cols.items():
+                p[c] = v[i]
+            pts.append(p)
         return pts
     except Exception:  # noqa: BLE001 — no map built yet
         return []

training/build_flavor_map.py

@@ -1,10 +1,14 @@
 """
-build_flavor_map.py — a 2D "flavor-space" embedding of the labeled molecules.
+build_flavor_map.py — a flavor-space embedding of the labeled molecules (2D + 3D).
 
-Projects each molecule's 2048-bit Morgan fingerprint to 2D (PCA -> t-SNE) and labels it by
-its dominant known taste, so structurally similar molecules land near each other and the taste
-classes separate visually. Output flavor_map.parquet (smiles, label, x, y); the app normalizes
-+ serves it as an interactive scatter (hover = name, click = full read).
+Projects each molecule's 2048-bit Morgan fingerprint into 2D and 3D with UMAP (Jaccard metric,
+which is the right similarity for binary fingerprints — same family as Tanimoto), and labels it
+by its dominant known taste. Structurally similar molecules land near each other and the taste
+classes separate visually. Output flavor_map.parquet (smiles, label, x, y, x3, y3, z3); the app
+normalizes + serves it as an interactive scatter (2D zoom/pan, or a rotatable 3D point cloud).
+
+Needs `pip install umap-learn` (a build-time dependency only — the server just reads the
+resulting parquet, so UMAP is not required to run the demo).
 
 Usage: python build_flavor_map.py            # taste_master.parquet -> flavor_map.parquet
 """
@@ -13,22 +17,26 @@
 
 import numpy as np
 import pandas as pd
+import umap
 from rdkit import Chem
 from rdkit.Chem import DataStructs, rdFingerprintGenerator
-from sklearn.decomposition import PCA
-from sklearn.manifold import TSNE
 
 TASTES = ["sweet", "bitter", "umami", "sour", "salty"]
 _MORGAN = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
 
 
 def _fp(m):
     bv = _MORGAN.GetFingerprint(m)
-    a = np.zeros((2048,), dtype=np.int8)
+    a = np.zeros((2048,), dtype=np.float32)  # float for UMAP's jaccard metric
     DataStructs.ConvertToNumpyArray(bv, a)
     return a
 
 
+def _umap(X, n):
+    return umap.UMAP(n_components=n, n_neighbors=15, min_dist=0.15,
+                     metric="jaccard", random_state=42).fit_transform(X)
+
+
 if __name__ == "__main__":
     src = "taste_master.parquet"
     if not Path(src).exists():
@@ -44,12 +52,14 @@ def _fp(m):
         labels.append(next((t for t in TASTES if r.get(t) == 1), "other"))
         feats.append(_fp(m))
     X = np.array(feats)
-    print(f"embedding {len(X)} molecules (PCA-50 -> t-SNE 2D)...", flush=True)
-    x50 = PCA(n_components=50, random_state=42).fit_transform(X)
-    xy = TSNE(n_components=2, random_state=42, perplexity=30, init="pca").fit_transform(x50)
+    print(f"embedding {len(X)} molecules with UMAP (Jaccard) — 2D then 3D...", flush=True)
+    xy = _umap(X, 2)
+    xyz = _umap(X, 3)
     out = pd.DataFrame({"smiles": smiles, "label": labels,
-                        "x": xy[:, 0].astype(float), "y": xy[:, 1].astype(float)})
+                        "x": xy[:, 0].astype(float), "y": xy[:, 1].astype(float),
+                        "x3": xyz[:, 0].astype(float), "y3": xyz[:, 1].astype(float),
+                        "z3": xyz[:, 2].astype(float)})
     out.to_parquet("flavor_map.parquet")
     print(f"flavor_map.parquet: {len(out)} points  "
-          f"({', '.join(f'{t}={int((out.label==t).sum())}' for t in TASTES)}, "
-          f"other={int((out.label=='other').sum())})")
+          f"({', '.join(f'{t}={int((out.label == t).sum())}' for t in TASTES)}, "
+          f"other={int((out.label == 'other').sum())})")

training/workbench.html

@@ -99,6 +99,13 @@
   .map-legend{display:flex;flex-wrap:wrap;gap:10px;margin:10px 0 6px;font-size:12px}
   .map-legend span{display:inline-flex;align-items:center;gap:5px}
   .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}
+  .map-toggle3d{display:inline-flex}
+  .map-toggle3d .st-tab{padding:3px 12px}
+  .map-reset{font:inherit;font-size:12px;padding:3px 10px;border:1px solid var(--line);border-radius:6px;background:#fff;color:var(--muted);cursor:pointer;margin-left:auto}
+  .map-reset:hover{border-color:var(--aroma)}
+  .map-key{font-size:12px;color:var(--muted);line-height:1.55;margin-top:8px;max-width:900px}
+  .map-key b{color:var(--ink)}
   .map-canvas-wrap{position:relative;width:100%;overflow-x:auto}
   #flavorMap{max-width:100%;border:1px solid var(--line);border-radius:8px;background:#fff;cursor:crosshair}
   .map-tip{position:absolute;pointer-events:none;background:#1c2620;color:#fff;font-size:11px;padding:3px 7px;border-radius:5px;white-space:nowrap;transform:translate(-50%,-140%)}
@@ -211,11 +218,20 @@ <h1>Flavormancer</h1>
 
   <div class="map-section">
     <div class="map-head" id="mapToggle"><span id="mapCaret">▸</span> Flavor-space map
-      <span class="mapsub">— every labeled molecule placed by structural similarity; taste classes separate. Hover a point, click to read.</span></div>
+      <span class="mapsub">— molecules placed by structural similarity; taste classes cluster</span></div>
     <div id="mapWrap" style="display:none">
-      <div id="mapLegend" class="map-legend"></div>
-      <div class="map-canvas-wrap"><canvas id="flavorMap" width="920" height="520"></canvas>
+      <div class="map-controls">
+        <span class="map-toggle3d"><button type="button" id="map2d" class="st-tab on">2D</button><button type="button" id="map3d" class="st-tab">3D</button></span>
+        <span id="mapLegend" class="map-legend"></span>
+        <button type="button" id="mapReset" class="map-reset">Reset view</button>
+      </div>
+      <div class="map-canvas-wrap"><canvas id="flavorMap" width="960" height="560"></canvas>
         <div id="mapTip" class="map-tip" style="display:none"></div></div>
+      <div class="map-key">Each dot is a molecule; <b>nearby dots are structurally similar</b>
+        (UMAP over Morgan fingerprints, Jaccard/Tanimoto). Color = <b>dominant taste</b>; tight
+        groups are structural families. Axes have no units — only <i>relative</i> position matters.
+        <b>2D:</b> scroll to zoom, drag to pan. <b>3D:</b> drag to rotate. Hover for the molecule,
+        click to open its read.</div>
     </div>
   </div>
 
@@ -624,43 +640,78 @@ <h2>Aroma</h2>
 }
 initBrowse();
 
-// --- flavor-space map (t-SNE of fingerprints, colored by taste) ---
+// --- flavor-space map: 2D (zoom/pan) + rotatable 3D point cloud, colored by taste ---
 const MAP_COLORS = {sweet:'#E0972E',bitter:'#6B4E9E',umami:'#C0563B',sour:'#9FB024',salty:'#4E84B0',other:'#C3C9C0'};
-let _mapPts=null, _mapDrawn=false;
+let _mapPts=null, _mapReady=false, _mapMode='2d', _mapProj=null;
+let _v2={s:1,ox:0,oy:0}, _v3={rx:-0.45,ry:0.6}, _drag=null, _dragged=false;
+
 $('mapToggle').addEventListener('click', async ()=>{
-  const w=$('mapWrap'); const open = w.style.display==='none';
-  w.style.display = open?'block':'none'; $('mapCaret').textContent = open?'▾':'▸';
-  if(open && !_mapDrawn){ await drawMap(); }
+  const w=$('mapWrap'); const open=w.style.display==='none';
+  w.style.display=open?'block':'none'; $('mapCaret').textContent=open?'▾':'▸';
+  if(open && !_mapReady) await loadMap();
 });
-async function drawMap(){
-  const cv=$('flavorMap'); const ctx=cv.getContext('2d');
-  ctx.clearRect(0,0,cv.width,cv.height);
+$('map2d').addEventListener('click', ()=>setMapMode('2d'));
+$('map3d').addEventListener('click', ()=>setMapMode('3d'));
+$('mapReset').addEventListener('click', ()=>{ _v2={s:1,ox:0,oy:0}; _v3={rx:-0.45,ry:0.6}; drawMap(); });
+function setMapMode(m){ _mapMode=m; $('map2d').classList.toggle('on',m==='2d'); $('map3d').classList.toggle('on',m==='3d'); drawMap(); }
+
+async function loadMap(){
+  const cv=$('flavorMap'), ctx=cv.getContext('2d');
   ctx.fillStyle='#8a938c'; ctx.font='13px sans-serif'; ctx.fillText('Loading…',12,22);
-  const d = await getJSON('/api/map'); _mapPts = d.points||[];
-  if(!_mapPts.length){ ctx.clearRect(0,0,cv.width,cv.height); ctx.fillStyle='#8a938c'; ctx.fillText('Map not built yet (build_flavor_map.py).',12,22); return; }
-  const pad=14, W=cv.width, H=cv.height;
-  const px = p => pad + p.x*(W-2*pad), py = p => H-pad - p.y*(H-2*pad);
-  ctx.clearRect(0,0,W,H);
-  for(const p of _mapPts){ ctx.beginPath(); ctx.arc(px(p),py(p),2.6,0,7); ctx.fillStyle=MAP_COLORS[p.label]||MAP_COLORS.other; ctx.globalAlpha=.82; ctx.fill(); }
-  ctx.globalAlpha=1;
-  // legend
+  const d=await getJSON('/api/map'); _mapPts=d.points||[];
+  if(!_mapPts.length){ ctx.clearRect(0,0,cv.width,cv.height); ctx.fillText('Map not built yet (build_flavor_map.py).',12,22); return; }
   const counts={}; _mapPts.forEach(p=>counts[p.label]=(counts[p.label]||0)+1);
-  $('mapLegend').innerHTML = Object.keys(MAP_COLORS).filter(l=>counts[l]).map(l=>
+  $('mapLegend').innerHTML=Object.keys(MAP_COLORS).filter(l=>counts[l]).map(l=>
     `<span><i style="background:${MAP_COLORS[l]}"></i>${l} (${counts[l]})</span>`).join('');
-  _mapDrawn=true;
-  // interactivity: nearest point in canvas space
-  const nearest = ev=>{
-    const r=cv.getBoundingClientRect(), sx=cv.width/r.width, sy=cv.height/r.height;
-    const mx=(ev.clientX-r.left)*sx, my=(ev.clientY-r.top)*sy;
-    let best=null,bd=100;
-    for(const p of _mapPts){ const dx=px(p)-mx, dy=py(p)-my, dd=dx*dx+dy*dy; if(dd<bd){bd=dd;best=p;} }
-    return best;
-  };
+  _mapReady=true; attachMapEvents(cv); drawMap();
+}
+function drawMap(){ _mapMode==='3d'?draw3D():draw2D(); }
+
+function draw2D(){
+  const cv=$('flavorMap'), ctx=cv.getContext('2d'), W=cv.width, H=cv.height, pad=18;
+  ctx.clearRect(0,0,W,H);
+  const px=p=>(pad+p.x*(W-2*pad))*_v2.s+_v2.ox, py=p=>(H-pad-p.y*(H-2*pad))*_v2.s+_v2.oy;
+  for(const p of _mapPts){ ctx.beginPath(); ctx.arc(px(p),py(p),2.6,0,7); ctx.fillStyle=MAP_COLORS[p.label]||MAP_COLORS.other; ctx.globalAlpha=.8; ctx.fill(); }
+  ctx.globalAlpha=1; _mapProj={px,py};
+}
+function draw3D(){
+  const cv=$('flavorMap'), ctx=cv.getContext('2d'), W=cv.width, H=cv.height;
+  ctx.clearRect(0,0,W,H);
+  const cx=W/2, cy=H/2, R=Math.min(W,H)*0.66, cY=Math.cos(_v3.ry),sY=Math.sin(_v3.ry),cX=Math.cos(_v3.rx),sX=Math.sin(_v3.rx);
+  const proj=p=>{ const X=(p.x3||0)-.5,Y=(p.y3||0)-.5,Z=(p.z3||0)-.5;
+    const x1=X*cY-Z*sY, z1=X*sY+Z*cY, y1=Y*cX-z1*sX, z2=Y*sX+z1*cX;
+    return {sx:cx+x1*R, sy:cy-y1*R, d:z2}; };
+  const all=_mapPts.map(p=>({p,pr:proj(p)})).sort((a,b)=>a.pr.d-b.pr.d);  // far first
+  for(const {p,pr} of all){ const t=pr.d+0.5; ctx.beginPath(); ctx.arc(pr.sx,pr.sy,1.7+2.1*t,0,7); ctx.fillStyle=MAP_COLORS[p.label]||MAP_COLORS.other; ctx.globalAlpha=Math.max(.22,Math.min(1,.35+.6*t)); ctx.fill(); }
+  ctx.globalAlpha=1; _mapProj={px:p=>proj(p).sx, py:p=>proj(p).sy};
+}
+function nearestMapPt(ev){
+  if(!_mapProj) return null;
+  const cv=$('flavorMap'), r=cv.getBoundingClientRect(), sx=cv.width/r.width, sy=cv.height/r.height;
+  const mx=(ev.clientX-r.left)*sx, my=(ev.clientY-r.top)*sy;
+  let best=null,bd=130;
+  for(const p of _mapPts){ const dx=_mapProj.px(p)-mx, dy=_mapProj.py(p)-my, dd=dx*dx+dy*dy; if(dd<bd){bd=dd;best=p;} }
+  return best;
+}
+function attachMapEvents(cv){
   const tip=$('mapTip');
-  cv.onmousemove = ev=>{ const p=nearest(ev); if(p){ const r=cv.getBoundingClientRect(); tip.style.display='block'; tip.style.left=(ev.clientX-r.left)+'px'; tip.style.top=(ev.clientY-r.top)+'px'; tip.textContent=(p.name||p.smiles)+' · '+p.label; } else tip.style.display='none'; };
-  cv.onmouseleave = ()=> tip.style.display='none';
-  cv.onclick = ev=>{ const p=nearest(ev); if(p){ q.value=p.smiles; window.scrollTo({top:0,behavior:'smooth'}); run(); } };
+  cv.addEventListener('mousedown', ev=>{ _drag={x:ev.clientX,y:ev.clientY,v2:{..._v2},v3:{..._v3}}; _dragged=false; });
+  window.addEventListener('mouseup', ()=>{ _drag=null; });
+  cv.addEventListener('mousemove', ev=>{
+    if(_drag){ _dragged=true; const dx=ev.clientX-_drag.x, dy=ev.clientY-_drag.y;
+      if(_mapMode==='2d'){ _v2.ox=_drag.v2.ox+dx; _v2.oy=_drag.v2.oy+dy; }
+      else { _v3.ry=_drag.v3.ry+dx*0.008; _v3.rx=_drag.v3.rx+dy*0.008; }
+      drawMap(); tip.style.display='none'; return; }
+    const p=nearestMapPt(ev); _mapLastHover=p;
+    if(p){ const r=cv.getBoundingClientRect(); tip.style.display='block'; tip.style.left=(ev.clientX-r.left)+'px'; tip.style.top=(ev.clientY-r.top)+'px';
+      tip.innerHTML=`<b>${p.name||p.smiles}</b><br><span style="color:${MAP_COLORS[p.label]}">●</span> ${p.label} · <span style="opacity:.8">${p.smiles}</span>`; }
+    else tip.style.display='none';
+  });
+  cv.addEventListener('mouseleave', ()=>{ tip.style.display='none'; });
+  cv.addEventListener('wheel', ev=>{ if(_mapMode!=='2d')return; ev.preventDefault(); _v2.s*=(ev.deltaY<0?1.12:0.89); drawMap(); }, {passive:false});
+  cv.addEventListener('click', ()=>{ if(_dragged){ _dragged=false; return; } const p=_mapLastHover; if(p){ q.value=p.smiles; window.scrollTo({top:0,behavior:'smooth'}); run(); } });
 }
+let _mapLastHover=null;
 
 // --- mixture mode ---
 function mixAddRow(val){