Merge pull request #206 from echelonts/aroma-41-heads-and-map-key

Aroma model: 41 predictable odor heads + full map-key/tooltip sync

Author: rvnminers-A-and-N

README.md

@@ -17,15 +17,15 @@ running entirely on hardware you own.
 <p align="center">
   <img src="docs/assets/flavor-map.png" alt="Flavor-space map in 3D on MW × logP × TPSA axes, colored by taste and aroma" width="900">
 </p>
-<p align="center"><sub>The interactive flavor-space map in 3D on real <b>MW × logP × TPSA</b> axes, colored by <b>taste &amp; aroma</b> — every one of the 37 aroma + 6 taste classes labelled.</sub></p>
+<p align="center"><sub>The interactive flavor-space map in 3D on real <b>MW × logP × TPSA</b> axes, colored by <b>taste &amp; aroma</b> — every one of the 41 aroma + 6 taste classes labelled.</sub></p>
 
 > **8,393 unique molecules** across the open datasets · **taste + aroma** prediction from
 > structure · a **flavor library** (start from a flavor → its character-impact molecule) and
 > **flavor designer** (pick your notes → best food-safe molecules + drop-in swaps) · an
 > interactive 2D/3D **flavor-space map** · **2D & 3D** structure views. All on
 > commercial-clean public data.
 >
-> Per set (unique molecules): taste training **3,845** · aroma training **1034** · odor
+> Per set (unique molecules): taste training **3,845** · aroma training **1046** · odor
 > corpus **2,255** · documented taste **676** · GRAS reference **2,781** · sweetness
 > intensity **316** · curated character-impact flavors **95 flavors / 77 molecules** · public-domain aroma supplement **102 associations**.
 > Every one of the 8,393 is enriched with names + measured properties from public-domain PubChem.
@@ -59,7 +59,7 @@ is tagged by how it was derived**, so nothing reads as more certain than its sou
   **tasteless** (RandomForests on fingerprint + physicochemical features), plus a
   sweetness-**intensity** regressor. Sour and salty *also* keep a transparent chemistry
   rule (acid group / alkali-salt) as a deterministic cross-check alongside the model.
-- **Aroma** — **37 odor-descriptor heads** (citrus, floral, minty, almond, fatty,
+- **Aroma** — **41 odor-descriptor heads** (citrus, floral, minty, almond, fatty,
   petroleum, earthy, medicinal, sulfurous, camphor, fruity, fishy, garlic, ethereal,
   ammoniacal, pungent, pine, rose, rancid, alcoholic, woody, green, grassy, putrid)
   trained on **public-domain** HSDB odor text + curated character-impact facts, surfaced
@@ -154,7 +154,7 @@ Flavormancer ships as two editions of one method:
 | Edition | Commercial | Academic / open-source *(coming soon)* |
 | License | Apache-2.0 | open-source, **research / NonCommercial** |
 | Data | commercial-clean open data only | adds research odor datasets with **NonCommercial** terms |
-| Aroma | **37 presence/absence descriptor heads ship** (public-domain HSDB); scored **intensity** is trained on your data or a licensed set (PMP 2001) | full open model incl. **intensity** (research odor data) |
+| Aroma | **41 presence/absence descriptor heads ship** (public-domain HSDB); scored **intensity** is trained on your data or a licensed set (PMP 2001) | full open model incl. **intensity** (research odor data) |
 | Use | free to use, sell, run on-prem | research, teaching, advancing the method |
 
 The split is deliberate. The richest aroma data is licensed for research only, so

docs/AROMA-AUDIT.md

@@ -2,17 +2,19 @@
 
 > **Update — supplement applied.** `build_aroma_supplement.py` added a curated **public-domain**
 > character-impact set (`aroma_supplement.csv`, resolved via PubChem) for the sparse descriptors
-> below. Result: **24 → 37 heads** — **13 new**: `coconut` (0.89), `nutty` (0.94), `caramel` (0.91),
+> below. Result: **24 → 41 heads** — **17 new**: `coconut` (0.89), `nutty` (0.94), `caramel` (0.91),
 > `winey` (0.90), `onion` (0.87), `honey` (0.80), `herbal` (0.80), `vanilla` (0.93), `buttery` (0.87),
-> `balsamic` (0.93), `smoky` (0.99), `cinnamon` (1.00), `spicy` (0.71) — and `grassy` kept above the
+> `balsamic` (0.93), `smoky` (0.99), `cinnamon` (1.00), `spicy` (0.71), `banana` (0.95),
+> `fresh` (0.73), `musky` (1.00), `vegetable` (0.85) — and `grassy` kept above the
 > bar (0.80) with its classic green-leaf volatiles. `coconut` is now *predictable* (γ-nonalactone →
-> coconut 1.0), which closes its earlier data-gate. `spicy` finally crossed (0.71, borderline — it
-> shares character molecules with cinnamon/clove). **Only `sweet`-odor (0.637) remains unlearnable**
-> even with 185 examples — a genuine representation limit (revisit with a GNN).
+> coconut 1.0), which closes its earlier data-gate. `spicy`/`fresh` are borderline (0.71–0.73).
+> **Only `sweet`-odor (0.637) remains unlearnable** even with 185 examples — a genuine representation
+> limit (revisit with a GNN).
 >
 > **Small-n caveat (honest):** the *highest*-AUROC new heads are small, structurally-homogeneous
-> classes — e.g. `cinnamon` reaches CV-AUROC **1.00** only because all 10 positives are one
-> cinnamaldehyde-family scaffold the fingerprint separates trivially. That is memorising a scaffold,
+> classes — e.g. `cinnamon` and `musky` reach CV-AUROC **~1.00** only because their ~10 positives
+> are one scaffold (cinnamaldehyde family; macrocyclic musks) the fingerprint separates trivially.
+> That is memorising a scaffold,
 > not a superb general model: these heads are **narrow and high-variance** (like `grassy`/`coffee`)
 > and will sharpen — or get honestly re-scored — with more diverse examples. Treat AUROC on n≈10
 > heads as indicative, not gospel. The numbers

docs/AROMA.md

@@ -18,7 +18,7 @@ enumerable via the annotations API. Pipeline:
   physicochemical descriptor block** (`chemfeatures.py`: MW, logP, TPSA, H-bond donors/
   acceptors, rotatable bonds, ring counts, fraction sp3, heteroatoms — the global properties
   bare bits miss). After broadening the vocabulary, folding the curated `flavors.csv` molecules
-  in (825 → **1034** molecules, incl. a curated public-domain supplement), and adding those features, **37 heads clear CV-AUROC ≥ 0.70**
+  in (825 → **1034** molecules, incl. a curated public-domain supplement), and adding those features, **41 heads clear CV-AUROC ≥ 0.70**
   (each score is that descriptor's own held-out AUROC): medicinal 0.97, ammoniacal 0.96,
   petroleum 0.96, citrus 0.94, camphor 0.93, almond 0.92, fatty 0.89, minty 0.88, ethereal 0.87,
   fruity 0.87, fishy 0.86, sulfurous 0.85, garlic 0.84, floral 0.83, pungent 0.81, earthy 0.73.

docs/CAPABILITIES.md

@@ -32,7 +32,7 @@ by how it's derived, and nothing claims more certainty than its source supports.
 - Multitaste — fires when 2+ taste heads are high (**trained**-derived).
 - Known-taste ground truth — verified labels override predictions (**lookup**).
 
-**Aroma** — **37 odor-descriptor heads ship** (**trained**)
+**Aroma** — **41 odor-descriptor heads ship** (**trained**)
 - Presence/absence per descriptor (citrus, floral, minty, almond, fatty, petroleum, earthy,
   medicinal, sulfurous, camphor, fruity, fishy, garlic, ethereal, ammoniacal, pungent) —
   RandomForests on fingerprint + physicochemical features, over public-domain HSDB odor text +

docs/HOW-IT-WORKS.md

@@ -62,7 +62,7 @@ features (trained on SweetenersDB).
 
 ---
 
-## 3. Aroma — 37 descriptor heads from public odor text
+## 3. Aroma — 41 descriptor heads from public odor text
 
 Odor is the hard, licensed part of this field — most rich odor datasets are NonCommercial. Our
 clean route:
@@ -75,7 +75,7 @@ clean route:
    `minty`), producing a presence/absence label per descriptor. We also fold in the curated
    character-impact facts from `flavors.csv`.
 3. **`train_aroma.py`** trains one RandomForest per descriptor (on fingerprint + descriptors) and
-   **keeps only the heads that clear CV-AUROC ≥ 0.70** — an honest bar. **37 heads** survive
+   **keeps only the heads that clear CV-AUROC ≥ 0.70** — an honest bar. **41 heads** survive
    (citrus, floral, minty, almond, fatty, petroleum, earthy, medicinal, sulfurous, camphor,
    fruity, fishy, garlic, ethereal, ammoniacal, pungent, pine, rose, rancid, alcoholic,
    woody, green, grassy, putrid), 0.71–0.98. The lower-population heads (≈10–20 documented

training/aroma_supplement.csv

@@ -57,6 +57,9 @@ banana,isoamyl isovalerate,CC(C)CCOC(=O)CC(C)C,aroma-supplement
 banana,isoamyl propionate,CCC(=O)OCCC(C)C,aroma-supplement
 banana,isobutyl acetate,CC(=O)OCC(C)C,aroma-supplement
 banana,isoamyl formate,CC(C)CCOC=O,aroma-supplement
+banana,amyl butyrate,CCCCCOC(=O)CCC,aroma-supplement
+banana,2-methylbutyl acetate,CCC(C)COC(C)=O,aroma-supplement
+banana,isoamyl hexanoate,CCCCCC(=O)OCCC(C)C,aroma-supplement
 nutty,"2,3-dimethylpyrazine",Cc1nccnc1C,aroma-supplement
 nutty,"2,5-dimethylpyrazine",Cc1cnc(C)cn1,aroma-supplement
 nutty,2-ethylpyrazine,CCc1cnccn1,aroma-supplement
@@ -85,6 +88,7 @@ smoky,"2,6-dimethylphenol",Cc1cccc(C)c1O,aroma-supplement
 anise,anethole,CC=Cc1ccc(OC)cc1,aroma-supplement
 anise,estragole,C=CCc1ccc(OC)cc1,aroma-supplement
 anise,anisaldehyde,COc1ccc(C=O)cc1,aroma-supplement
+anise,fenchone,CC12CCC(C1)C(C)(C)C2=O,aroma-supplement
 balsamic,benzyl benzoate,O=C(OCc1ccccc1)c1ccccc1,aroma-supplement
 balsamic,benzyl cinnamate,O=C(C=Cc1ccccc1)OCc1ccccc1,aroma-supplement
 balsamic,benzoic acid,O=C(O)c1ccccc1,aroma-supplement
@@ -105,6 +109,18 @@ winey,"2,3-butanediol",CC(O)C(C)O,aroma-supplement
 onion,dipropyl disulfide,CCCSSCCC,aroma-supplement
 onion,methyl propyl disulfide,CCCSSC,aroma-supplement
 onion,allyl propyl disulfide,C=CCSSCCC,aroma-supplement
+fresh,melonal,CC(C)=CCCC(C)C=O,aroma-supplement
+fresh,dihydromyrcenol,C=CC(C)CCCC(C)(C)O,aroma-supplement
+fresh,cis-3-hexenyl acetate,CCC=CCCOC(C)=O,aroma-supplement
+fresh,hexanal,CCCCCC=O,aroma-supplement
+musky,muscone,CC1CCCCCCCCCCCCC(=O)C1,aroma-supplement
+musky,ethylene brassylate,O=C1CCCCCCCCCCCC(=O)OCCO1,aroma-supplement
+musky,ambrettolide,O=C1CCCCCC=CCCCCCCCCO1,aroma-supplement
+musky,habanolide,O=C1CCCCCCCCCC=CCCCO1,aroma-supplement
+vegetable,2-isobutyl-3-methoxypyrazine,COc1nccnc1CC(C)C,aroma-supplement
+vegetable,2-isopropyl-3-methoxypyrazine,COc1nccnc1C(C)C,aroma-supplement
+vegetable,dimethyl sulfide,CSC,aroma-supplement
+vegetable,2-acetylpyrrole,CC(=O)c1ccc[nH]1,aroma-supplement
 grassy,cis-3-hexenal,CCC=CCC=O,aroma-supplement
 grassy,cis-3-hexen-1-ol,CCC=CCCO,aroma-supplement
 grassy,trans-2-hexenal,CCCC=CC=O,aroma-supplement

training/build_aroma_supplement.py

@@ -38,7 +38,7 @@
     "cinnamon": ["cinnamaldehyde", "cinnamyl alcohol", "cinnamic acid", "methyl cinnamate",
                  "ethyl cinnamate", "cinnamyl acetate", "alpha-methylcinnamaldehyde", "cinnamyl formate", "hydrocinnamaldehyde", "cinnamyl butyrate"],
     "spicy":    ["eugenol", "cinnamaldehyde", "zingerone", "piperonal", "carvacrol"],
-    "banana":   ["isoamyl acetate", "amyl acetate", "isoamyl butyrate", "isoamyl isovalerate", "isoamyl propionate", "isobutyl acetate", "isoamyl formate", "amyl butyrate"],
+    "banana":   ["isoamyl acetate", "amyl acetate", "isoamyl butyrate", "isoamyl isovalerate", "isoamyl propionate", "isobutyl acetate", "isoamyl formate", "amyl butyrate", "2-methylbutyl acetate", "isoamyl hexanoate"],
     "nutty":    ["2,3-dimethylpyrazine", "2,5-dimethylpyrazine", "2-ethylpyrazine",
                  "2-acetylpyrazine", "5-methylfurfural", "2-ethyl-3-methylpyrazine",
                  "2-acetylthiazole", "2,3-diethylpyrazine"],
@@ -47,14 +47,17 @@
     "coffee":   ["furfuryl mercaptan", "guaiacol", "2-acetylpyrazine", "5-methylfurfural"],
     "smoky":    ["guaiacol", "2,6-dimethoxyphenol", "4-methylguaiacol", "4-ethylguaiacol",
                  "4-vinylguaiacol", "creosol", "phenol", "p-cresol", "o-cresol", "2,6-dimethylphenol"],
-    "anise":    ["anethole", "estragole", "anisaldehyde", "p-anisaldehyde"],
+    "anise":    ["anethole", "estragole", "anisaldehyde", "p-anisaldehyde", "fenchone", "methyl chavicol"],
     "balsamic": ["benzyl benzoate", "benzyl cinnamate", "benzoic acid", "benzyl salicylate", "cinnamyl cinnamate"],
     "herbal":   ["thymol", "carvacrol", "eucalyptol", "1,8-cineole", "menthone", "isomenthone"],
     "meaty":    ["methional", "2-methyl-3-furanthiol", "furfuryl mercaptan"],
     "cherry":   ["benzaldehyde", "p-tolualdehyde"],
     "winey":    ["ethyl lactate", "ethyl hexanoate", "2,3-butanediol"],
     "onion":    ["dipropyl disulfide", "methyl propyl disulfide", "allyl propyl disulfide"],
     # keep the fragile grassy head above the bar with its classic green-leaf volatiles
+    "fresh":    ["melonal", "dihydromyrcenol", "cis-3-hexenyl acetate", "hexanal"],
+    "musky":    ["muscone", "ethylene brassylate", "ambrettolide", "habanolide"],
+    "vegetable":["2-isobutyl-3-methoxypyrazine", "2-isopropyl-3-methoxypyrazine", "dimethyl sulfide", "2-acetylpyrrole"],
     "grassy":   ["cis-3-hexenal", "cis-3-hexen-1-ol", "trans-2-hexenal", "hexanal",
                  "trans-2-hexen-1-ol", "cis-3-hexenyl acetate"],
     "green":    ["cis-3-hexenal", "trans-2-hexenal", "cis-3-hexen-1-ol", "hexanal"],

training/workbench.html

@@ -714,7 +714,7 @@ <h1>Flavormancer</h1>
       <div class="how-grid">
         <div class="how-card"><h4>1 · Structure → numbers</h4><p>Every molecule becomes a <b>2,048-bit Morgan fingerprint</b> (which substructures it contains) plus a block of <b>physicochemical descriptors</b> (logP, MW, TPSA, H-bonding…). That one shared vector feeds every model — the same structure-to-property representation QSAR has leaned on for decades.</p></div>
         <div class="how-card"><h4>2 · Taste — 6 trained heads + 2 rules</h4><p>Six <b>random-forest</b> classifiers (sweet, bitter, umami…) each return a probability, scored by an honest held-out <b>CV-AUROC</b>. Sour and salty are solution / ionic effects, not molecule-shape ones, so they're transparent <b>rules</b> — not faked models. A sweetness-intensity regressor estimates relative-to-sucrose potency.</p></div>
-        <div class="how-card"><h4>3 · Aroma — 37 odor heads</h4><p>One random forest per descriptor (citrus, floral, woody…), trained on <b>public-domain odor text</b>. A head ships only if it clears <b>CV-AUROC ≥ 0.70</b> — 37 survive, each shown with its own score. It reads <b>presence, not intensity</b> (free text carries none) — an honest ceiling, stated in the UI.</p></div>
+        <div class="how-card"><h4>3 · Aroma — 41 odor heads</h4><p>One random forest per descriptor (citrus, floral, woody…), trained on <b>public-domain odor text</b>. A head ships only if it clears <b>CV-AUROC ≥ 0.70</b> — 41 survive, each shown with its own score. It reads <b>presence, not intensity</b> (free text carries none) — an honest ceiling, stated in the UI.</p></div>
         <div class="how-card"><h4>4 · Honest by design</h4><p>Every value is tagged <b>measured / predicted / estimate</b>, so nothing reads as more precise than it is. Where a quantitative feature needs data we can't ship free-commercially (odor thresholds, panel intensities), the UI <b>says so</b> — and it lights up with <b>your</b> data.</p></div>
         <div class="how-card"><h4>5 · Formulation, not just molecules</h4><p>The <b>Formulation Studio</b> reads a whole recipe before you pour — weighting each ingredient by odor impact, aggregating the blend's note-profile, flagging the overpowering component, and closing the gap to your target. That's single-molecule ML turned into a bench tool.</p></div>
         <div class="how-card"><h4>6 · On-prem &amp; commercial-clean</h4><p>Nothing leaves the box — a read makes <b>no cloud calls</b>. The shipped models train only on <b>public-domain or permissively-licensed</b> data, so the commercial edition stays clean (provenance tracked in the repo).</p></div>
@@ -871,7 +871,7 @@ <h1>Flavormancer</h1>
           the trend, exactly the kind of lead worth a closer look.</p>
           <p><b>Two flavor dimensions.</b> Flip the color toggle between <b>taste</b> (sweet /
           bitter / umami / sour / salty / tasteless) and <b>aroma</b> (= odor — the same thing;
-          the 37 documented descriptor classes like citrus, floral, sulfurous). Same molecules,
+          the 41 documented descriptor classes like citrus, floral, sulfurous). Same molecules,
           same structural layout — you're overlaying a different sense. The <b>both</b> toggle merges
           them into one full-flavor view: each dot takes its <b>taste</b> color where a taste is known,
           otherwise its <b>aroma</b> color — so nearly every molecule is colored by its dominant known
@@ -1087,7 +1087,8 @@ <h4>Software &amp; type</h4>
   cheesy:'#D9B84D',creamy:'#E3CE9A',waxy:'#C4BE96',fresh:'#4FC0B0',grassy:'#7DAF3A',
   rancid:'#9A8B5A',tarry:'#4A4038',winey:'#8E4B6E',honey:'#E0A83C',apple:'#8DBF4A',
   cherry:'#C0392B',pine:'#3FA06B',banana:'#E6C84D',fatty:'#C9B27A',petroleum:'#6E7B8B',
-  alcoholic:'#9FB6C4',musky:'#8B7BA5',putrid:'#6E7A4A',soapy:'#B9C6D0',vegetable:'#6FA36B',bready:'#C7A06A'};
+  alcoholic:'#9FB6C4',musky:'#8B7BA5',putrid:'#6E7A4A',soapy:'#B9C6D0',vegetable:'#6FA36B',bready:'#C7A06A',
+  onion:'#B7A64B'};
 const aromaColor = n => AROMA_COLORS[n] || 'var(--aroma)';
 
 const $ = id => document.getElementById(id);
@@ -1132,6 +1133,10 @@ <h4>Software &amp; type</h4>
   smoky:'smoke / phenolic — guaiacol &amp; alkylphenols',
   cinnamon:'cinnamon — cinnamaldehyde &amp; esters',
   spicy:'warm spice — eugenol / cinnamaldehyde / capsaicinoid family',
+  banana:'ripe banana — isoamyl acetate &amp; branched esters',
+  fresh:'clean / airy — light aldehydes &amp; dihydromyrcenol',
+  musky:'musk — macrocyclic ketones / lactones',
+  vegetable:'green vegetable — methoxypyrazines &amp; sulfides',
   caramel:'burnt-sugar / toffee — maltol, furaneol, cyclotene',
   honey:'sweet honey / beeswax — phenylacetic acid &amp; esters',
   nutty:'roasted nut / hazelnut — alkylpyrazines',
@@ -1621,7 +1626,8 @@ <h4>Software &amp; type</h4>
 // canonical class sets so the legend is a COMPLETE key — every taste head and every
 // aroma head shows, even if the current map has few or zero of one (e.g. salty).
 const TASTE_CLASSES = ['sweet','bitter','umami','sour','salty','tasteless'];
-const AROMA_HEADS = ['citrus','floral','minty','almond','fatty','petroleum','earthy','medicinal','sulfurous','camphor','fruity','fishy','garlic','ethereal','ammoniacal','pungent','pine','rose','rancid','alcoholic','woody','green','grassy','putrid'];
+// all trained aroma heads — keep in sync with aroma_models/ (see docs/AROMA-AUDIT.md)
+const AROMA_HEADS = ['citrus','floral','minty','almond','fatty','petroleum','earthy','medicinal','sulfurous','camphor','fruity','fishy','garlic','ethereal','ammoniacal','pungent','pine','rose','rancid','alcoholic','woody','green','grassy','putrid','coconut','nutty','caramel','honey','herbal','winey','onion','vanilla','buttery','balsamic','smoky','cinnamon','spicy','banana','fresh','musky','vegetable'];
 function legendClasses(){
   if(_mapColorBy==='aroma') return AROMA_HEADS;
   if(_mapColorBy==='both')  return TASTE_CLASSES.concat(AROMA_HEADS);
@@ -1685,7 +1691,7 @@ <h4>Software &amp; type</h4>
 let _mapHi = new Set();  // classes highlighted from the legend (empty = show all evenly)
 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 37 aroma heads /
+  // COMPLETE key: EVERY canonical class for the mode (all 6 taste heads / all 41 aroma heads /
   // both), plus 'other' last. Present classes are ordered by count; any with zero points still
   // appear (dimmed) so the legend is a full reference — never hide a real head.
   const canon=legendClasses();
@@ -1733,7 +1739,7 @@ <h4>Software &amp; type</h4>
   const cv=$('flavorMap'), ctx=cv.getContext('2d'), groups={};
   for(const p of _mapPts){ const l=mapLabel(p); if(!l||l==='other') continue; (groups[l]=groups[l]||[]).push(p); }
   ctx.save(); ctx.font='700 14px "Cinzel Decorative",Georgia,serif'; ctx.textAlign='center'; ctx.textBaseline='middle';
-  // label EVERY class that has points (all 37 aroma / 6 taste heads), not just the big ones
+  // label EVERY class that has points (all 41 aroma / 6 taste heads), not just the big ones
   for(const l in groups){ const pts=groups[l]; if(pts.length<3) continue;
     let sx=0,sy=0,n=0; for(const p of pts){ const x=_mapProj.px(p),y=_mapProj.py(p); if(x<-9000||!isFinite(x)) continue; sx+=x; sy+=y; n++; }
     if(!n) continue; sx/=n; sy/=n;