From 2893efd4e0683ca0c7759a7c32caf4fac5833142 Mon Sep 17 00:00:00 2001 From: "Austin L." <86896075+rvnminers-A-and-N@users.noreply.github.com> Date: Tue, 30 Jun 2026 18:52:53 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20METHODS.md=20=E2=80=94=20every=20rule,?= =?UTF-8?q?=20threshold,=20heuristic=20and=20trick?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A single reference for all the non-obvious tricks: the sour/salty rules, the sweetness-intensity logP<2 gate, the no-carbon applicability domain, the curated structural-alert SMARTS set (and why it's small), the BP atmospheric-preference parser (Joback rejected), the documented mixture-hazard roles (nitrite vs nitrate), the palette Jaccard match, Tox21 thresholds, etc. — each with its rationale and its ceiling. Ends with the honest note that deeper flavor description (vanilla/fruity/minty) is aroma, not taste, and needs the deferred odor model. Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com> --- docs/METHODS.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 1 + 2 files changed, 95 insertions(+) create mode 100644 docs/METHODS.md diff --git a/docs/METHODS.md b/docs/METHODS.md new file mode 100644 index 0000000..4d2ce05 --- /dev/null +++ b/docs/METHODS.md @@ -0,0 +1,94 @@ +# Methods, Rules & Heuristics + +Every non-obvious rule, threshold, and trick Flavormancer uses — with its rationale and +its ceiling. The discipline throughout: each output is tagged by **how** it's derived, +and a rule is used only where it's *more honest* than a model. Companion to +[`CAPABILITIES.md`](CAPABILITIES.md) (what it does) and [`SOURCES.md`](SOURCES.md) (the data). + +**Confidence tiers:** `computed` (exact from structure) · `trained` (ML on open data) · +`rule` (deterministic structural rule) · `estimate` (published QSPR, known error) · +`lookup` (loaded reference table) · `qualitative` (a class/flag, not a number). + +--- + +## Taste +- **Sweet / bitter / umami** — `trained`. RandomForest on 2048-bit Morgan radius-2 fingerprints. +- **Sweetness intensity** — `trained`, est. RandomForest regressor on **log₁₀(relative-to-sucrose)** + sweetness (SweetenersDB). Shown as a multiplier (10^value). **Gate:** displayed only when + sweet ≥ 0.5 **and logP < 2** — sweeteners are hydrophilic, so the logP cutoff suppresses + lipophilic false-positives (the classifier wrongly calling limonene "sweet") while keeping + real sweeteners (sugars, aspartame). Tagged "(est.)"; the value is the model's, not literature. +- **Sour** — `rule`. SMARTS for acidic groups (carboxylic / sulfonic / phosphonic) matching + **both protonated and deprotonated** forms (this lifted recall 0.57 → 0.93). Sourness is a + solution/pH property, so a structural proxy is the honest move, not a per-molecule ML target. +- **Salty** — `rule`. Fires only for a salt-forming cation (alkali metal Li/Na/K/Rb/Cs or + ammonium) **+ a simple INORGANIC anion**. **Defers** when the anion carries carbon — so MSG + (umami), Na-saccharin (sweet), Na-benzoate (preservative) are NOT called salty. Refuses the + naive "has sodium → salty" mistake. +- **Known-taste override** — `lookup`. A verified dataset label beats the rule/model and is + marked "verified." +- **taste_profile / multitaste** — trained heads ranked by probability; multitaste flag when ≥2 fire. + +## Applicability domain +- **No-carbon → out of domain.** The trained taste/tox heads are fit on *organic* molecules; + for carbon-free inputs (water, O₂, N₂, NaCl) their output is meaningless, so the UI suppresses + them with a banner. Rules (sour/salty), structure, and computed properties stay valid. + +## Physicochemical +- **logP / MW / TPSA / H-bond donors-acceptors / rings / heavy atoms** — `computed` (RDKit, exact). +- **Water solubility, logS** — `estimate` (ESOL, Delaney 2004; ~0.7 log RMSE). +- **Volatility tier** — `qualitative`. Heuristic from MW + H-bond donors + TPSA → top/middle/base note. +- **Boiling point / vapor pressure** — `lookup`. Measured values from PubChem (public domain). + **Structure-based BP (Joback) was evaluated and rejected** (33 °C mean / 89 °C max error across + 12 flavor molecules). The BP parser **prefers atmospheric (~760 mmHg) readings**; when only + reduced/elevated-pressure data exists it reports the value **with its pressure**, not a bare + misleading number. +- **pKa** — `qualitative`. Typical ranges for detected ionizable groups, not a per-molecule value. + +## Stability +- **Oxidation / hydrolysis / photo watch-flags** — `rule`/`qualitative`. SMARTS for reactive + motifs (e.g. phenol/aldehyde → oxidation). "Watch for," not a shelf-life prediction. + +## Chemesthesis (trigeminal — a dimension beyond taste) +- **Cooling / pungent / astringent** — `rule`/`lookup`. SMARTS (isothiocyanate → pungent; + ≥3 phenols → astringent) + InChIKey lookups (menthol → cooling/TRPM8; capsaicin & piperine → + pungent/TRPV1). + +## Safety (all defensive, caution-only — never a clearance) +- **Structural tox-alerts** — `rule`. A SMALL curated SMARTS set: aromatic nitro, N-nitroso, + aromatic azo, epoxide. Deliberately limited to motifs **rare in the GRAS flavor palette** to + avoid alert fatigue — we do NOT flag aldehydes or Michael acceptors (too many GRAS flavors + carry them). Prompts for review; **not a comprehensive carcinogen detector** (e.g. furan isn't flagged). +- **GRAS / food-use cross-check** — `lookup`. InChIKey-skeleton match against FDA "Substances + Added to Food" (public domain). +- **TTC / Cramer tier** — `qualitative`. Preliminary concern tier; Toxtree for the validated call. +- **Tox21 assay flags** — `trained`, caution-only. 12 RandomForest heads (genotoxic-stress, AhR, + mitochondrial, endocrine); flagged at probability ≥ 0.5; indicative in-vitro signals, never a + determination. Suppressed for out-of-domain molecules. +- **EU declarable-allergen labeling** — `lookup`. InChIKey match against a curated EU allergen subset. + +## Mixtures +- **check_mixture** — `lookup`/`rule`. Detect molecular **roles** (benzoate, nitrite, secondary + amine, urea, ascorbate, ethanol, asparagine, citrulline, reducing sugar, …) via SMARTS + + InChIKey, then fire **documented** precursor→product hazards (benzene, nitrosamine, ethyl + carbamate, acrylamide, furan, 3-MCPD, 4-MEI, biogenic amines) when the required roles co-occur, + **gated on declared process** (high heat / refining / fermentation) → active vs conditional. + A **curated documented-hazard screen, NOT a reaction predictor** — and precise: it distinguishes + **nitrite** (forms nitrosamines) from **nitrate** (does not). +- **Palette match** — `rule`. Jaccard similarity over the 5-basic-taste label sets: union the + mixture's ingredient tastes, find single labeled molecules with the closest set. NOT blend + perception — a blend ≠ the sum of its parts (suppression/synergy needs formulation data). + +## Search & resolution +- **Substitution** — Tanimoto over Morgan fingerprints (self excluded), each neighbor with its known tastes. +- **Names / structure** — PubChem name/CAS→SMILES resolution; common (Title) + IUPAC names (cached); + RDKit 2D depiction (graceful without libXrender); typeahead over the curated flavor-volatile list. + +--- + +## The honest ceiling on "deeper flavor description" +Taste tops out at the **5 basics + intensity + chemesthesis** on public data. The rich +descriptors people mean by "flavor" — *vanilla, fruity, green, woody, minty, caramel…* — are +**aroma**, not taste: a separate odor model that needs expert-labeled odor data (licensed or +customer; deferred — see [`AROMA.md`](AROMA.md)). That model is the real route to deeper flavor +language, and it's exactly the "comes with your data" piece. diff --git a/docs/README.md b/docs/README.md index 6369c1a..93662cb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,6 +5,7 @@ Architecture, capability catalogue, and design decisions. - `ARCHITECTURE.md` — the locked stack and the reasoning behind each choice - `CAPABILITIES.md` — what the tool does, what's buildable on open data, and the honest limits of public-data prediction +- `METHODS.md` — every rule, threshold, heuristic, and trick the system uses, with rationale and ceiling - `SOURCES.md` — data sources, libraries, research, and license attribution - `API-CONTRACT.md` — the fixed JSON contract the .NET API exposes and the React UI consumes - `DATA-SOURCES.md` — data acquisition tracker: what each source unlocks and how to get it