hs_predict/smiles/
detector.rs

1//! Organic / inorganic detection and functional group detection from SMILES.
2//!
3//! Detection is based on substring pattern matching against canonical SMILES
4//! (as returned by PubChem). It is intentionally approximate — results carry
5//! a confidence of ≤ 0.70 and are used only as heading-level hints.
6//!
7//! # Priority order
8//! Groups are checked in decreasing specificity so that more specific patterns
9//! take precedence (e.g. anhydride before ester before carboxylic acid).
10
11use crate::types::OrganicInorganic;
12use serde::{Deserialize, Serialize};
13
14// ─────────────────────────────────────────────────────────────────────────────
15// FunctionalGroup enum
16// ─────────────────────────────────────────────────────────────────────────────
17
18/// Functional group category detectable from a SMILES string.
19///
20/// The 20 groups cover the main HS Chapter 29 classification criteria
21/// for organic chemicals plus the organic/inorganic distinction used
22/// for Chapter 28.
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
24#[serde(rename_all = "snake_case")]
25pub enum FunctionalGroup {
26    /// –C(=O)–O–C(=O)– (acid anhydride).
27    Anhydride,
28    /// –N=C=O (isocyanate or isothiocyanate N=C=S).
29    Isocyanate,
30    /// –C≡N (nitrile / cyanide).
31    Nitrile,
32    /// –[N+](=O)[O–] nitro group.
33    Nitro,
34    /// Three-membered ring containing O (epoxide).
35    Epoxide,
36    /// –S(=O)(=O)–OH sulphonic acid.
37    SulphonicAcid,
38    /// P=O or P–O (phosphate / phosphonate ester).
39    Phosphate,
40    /// –C(=O)–NH₂ / –NHC(=O)– amide.
41    Amide,
42    /// –C(=O)–O–C ester (not anhydride).
43    Ester,
44    /// –C(=O)–OH carboxylic acid.
45    CarboxylicAcid,
46    /// –CHO terminal aldehyde.
47    Aldehyde,
48    /// –C(=O)– flanked by two C atoms (ketone).
49    Ketone,
50    /// Phenolic –OH on aromatic ring.
51    Phenol,
52    /// –SH thiol (mercaptan).
53    Thiol,
54    /// C–S–C thioether / sulphide.
55    Sulphide,
56    /// Aliphatic –C–OH alcohol.
57    Alcohol,
58    /// C–O–C ether (not ester, not epoxide).
59    Ether,
60    /// Primary, secondary, or tertiary amine –NHₓ (not amide).
61    Amine,
62    /// C–F / C–Cl / C–Br / C–I organic halide.
63    Halide,
64    /// Aromatic ring (any aromatic atom present).
65    AromaticRing,
66}
67
68impl FunctionalGroup {
69    /// Short display label for notes and logging.
70    pub fn label(self) -> &'static str {
71        match self {
72            Self::Anhydride => "Anhydride",
73            Self::Isocyanate => "Isocyanate",
74            Self::Nitrile => "Nitrile",
75            Self::Nitro => "Nitro",
76            Self::Epoxide => "Epoxide",
77            Self::SulphonicAcid => "SulphonicAcid",
78            Self::Phosphate => "Phosphate",
79            Self::Amide => "Amide",
80            Self::Ester => "Ester",
81            Self::CarboxylicAcid => "CarboxylicAcid",
82            Self::Aldehyde => "Aldehyde",
83            Self::Ketone => "Ketone",
84            Self::Phenol => "Phenol",
85            Self::Thiol => "Thiol",
86            Self::Sulphide => "Sulphide",
87            Self::Alcohol => "Alcohol",
88            Self::Ether => "Ether",
89            Self::Amine => "Amine",
90            Self::Halide => "Halide",
91            Self::AromaticRing => "AromaticRing",
92        }
93    }
94}
95
96// ─────────────────────────────────────────────────────────────────────────────
97// Organic / inorganic classification
98// ─────────────────────────────────────────────────────────────────────────────
99
100/// Determine whether a SMILES string represents an organic, inorganic,
101/// or organometallic compound.
102///
103/// Uses the chemical definition: *organic* = contains at least one carbon atom
104/// that is not in a purely inorganic context (CO₂, CO, CS₂, carbonate, cyanide
105/// as free ion).
106pub fn classify_organic(smiles: &str) -> OrganicInorganic {
107    // No carbon → definitely inorganic
108    if !smiles.chars().any(|c| c == 'C' || c == 'c') {
109        return OrganicInorganic::Inorganic;
110    }
111
112    // Exact-match known simple inorganic carbon compounds
113    let normalised = smiles.replace(' ', "");
114    let inorganic_exact: &[&str] = &[
115        "O=C=O",       // CO₂
116        "[O-]C(=O)[O-]", // carbonate ion
117        "[O-]C([O-])=O",
118        "[C-]#[O+]",   // CO
119        "[C+]#[O-]",
120        "S=C=S",       // CS₂
121        "[C-]#N",      // cyanide ion
122        "[N+]#[C-]",
123        "C(=O)([O-])[O-]", // carbonate
124    ];
125    if inorganic_exact.iter().any(|p| normalised == *p) {
126        return OrganicInorganic::Inorganic;
127    }
128
129    // Check multi-component SMILES (dot-separated): each fragment independently
130    // A compound is organometallic if any fragment has a direct metal–C bond.
131    let metal_symbols: &[&str] = &[
132        "[Fe]", "[Co]", "[Ni]", "[Cr]", "[Mn]", "[Mo]", "[W]",
133        "[Ti]", "[V]",  "[Ru]", "[Rh]", "[Pd]", "[Os]", "[Ir]",
134        "[Pt]", "[Zn]", "[Al]", "[Pb]", "[Sn]", "[Hg]", "[Tl]",
135    ];
136    // Organometallic: metal atom directly bonded to carbon in SMILES notation
137    // i.e. the metal symbol is followed or preceded by C/c (with no space or [)
138    for metal in metal_symbols {
139        if smiles.contains(metal) {
140            // Check if this metal is bonded to C in the SMILES graph.
141            // Heuristic: metal symbol immediately adjacent to C or c in the string.
142            let idx = smiles.find(metal).unwrap_or(usize::MAX);
143            let after = smiles.get(idx + metal.len()..).unwrap_or("");
144            let before = smiles.get(..idx).unwrap_or("");
145            let bonded = after.starts_with('C')
146                || after.starts_with('c')
147                || before.ends_with('C')
148                || before.ends_with('c');
149            if bonded {
150                return OrganicInorganic::Organometallic;
151            }
152        }
153    }
154
155    OrganicInorganic::Organic
156}
157
158// ─────────────────────────────────────────────────────────────────────────────
159// Functional group detection
160// ─────────────────────────────────────────────────────────────────────────────
161
162/// Detect functional groups present in a SMILES string.
163///
164/// The detection uses substring pattern matching against both the
165/// canonical and common alternative SMILES representations.
166/// Groups are returned in detection priority order (most specific first).
167///
168/// # Limitations
169/// - Does not perform full SMILES parsing; edge cases may be missed.
170/// - Designed primarily for PubChem canonical SMILES.
171/// - Confidences are capped at ≤ 0.70 due to these limitations.
172pub fn detect_functional_groups(smiles: &str) -> Vec<FunctionalGroup> {
173    let mut groups: Vec<FunctionalGroup> = Vec::new();
174
175    // Helper: returns true if any of `patterns` is a substring of `smiles`.
176    let any = |patterns: &[&str]| -> bool { patterns.iter().any(|p| smiles.contains(p)) };
177
178    // ── 1. Anhydride (check before ester and acid) ────────────────────────
179    // Linear anhydride: C(=O)OC(=O) (e.g. acetic anhydride: CC(=O)OC(=O)C)
180    // Cyclic anhydride: O=C[digit]OC(=O) (e.g. phthalic: O=C1OC(=O)c2ccccc21)
181    let cyclic_anhydride = (1u8..=9).any(|n| {
182        smiles.contains(&format!("O=C{}OC(=O)", n))
183    });
184    if smiles.contains("C(=O)OC(=O)") || cyclic_anhydride {
185        groups.push(FunctionalGroup::Anhydride);
186    }
187
188    // ── 2. Isocyanate ─────────────────────────────────────────────────────
189    if any(&["N=C=O", "O=C=N"]) {
190        groups.push(FunctionalGroup::Isocyanate);
191    }
192
193    // ── 3. Nitrile ────────────────────────────────────────────────────────
194    if any(&["C#N", "N#C"]) {
195        groups.push(FunctionalGroup::Nitrile);
196    }
197
198    // ── 4. Nitro ──────────────────────────────────────────────────────────
199    // PubChem canonical writes the double-bond O before N: O=[N+]([O-])
200    if any(&[
201        "O=[N+]([O-])", // PubChem canonical (nitrobenzene, TNT, etc.)
202        "[N+](=O)[O-]", // alternative bracket form
203        "N(=O)=O",
204        "[N+]([O-])=O",
205        "[N+](=O)([O-])",
206    ]) {
207        groups.push(FunctionalGroup::Nitro);
208    }
209
210    // ── 5. Epoxide (3-membered ring with O) ───────────────────────────────
211    // PubChem canonical for ethylene oxide: C1CO1 (C-C-O ring).
212    // Also handle C1OC1 (alternative) and stereocentres.
213    if any(&[
214        "C1CO1",           // ethylene oxide / PubChem canonical
215        "C1OC1",           // alternative ring ordering
216        "[C@@H]1O[C@H]1",  // stereo epoxide
217        "[C@H]1O[C@@H]1",
218    ]) {
219        groups.push(FunctionalGroup::Epoxide);
220    }
221
222    // ── 6. Sulphonic acid ─────────────────────────────────────────────────
223    if any(&["S(=O)(=O)O", "S(=O)(=O)[OH]", "S(O)(=O)=O", "[S](=O)(=O)O"]) {
224        groups.push(FunctionalGroup::SulphonicAcid);
225    }
226
227    // ── 7. Phosphate / phosphonate ────────────────────────────────────────
228    if smiles.contains('P')
229        && any(&["P(=O)(O)", "P(=O)([O", "P(O)(O)", "P([OH])", "OP(=O)", "P(=O)O"])
230    {
231        groups.push(FunctionalGroup::Phosphate);
232    }
233
234    // ── 8. Amide (before amine) ───────────────────────────────────────────
235    // Canonical: NC(=O), NC(C...)=O, C(N)=O, C(=O)N, C(=O)[NH
236    if any(&[
237        "NC(=O)", "NC(C", // NC(C...)=O  — amide N before carbonyl-C
238        "C(N)=O", "C(=O)N", "C(=O)[NH", "[NH]C(=O)", "[NH2]C(=O)",
239        "N)=O",   // -N)=O terminal amide
240    ]) {
241        // Exclude isocyanate and nitrile (already tagged)
242        let has_iso = groups.contains(&FunctionalGroup::Isocyanate);
243        let has_nitrile = groups.contains(&FunctionalGroup::Nitrile);
244        if !has_iso && !has_nitrile {
245            groups.push(FunctionalGroup::Amide);
246        }
247    }
248
249    // ── 9. Ester (before carboxylic acid) ─────────────────────────────────
250    // Canonical: OC(C...)=O (ester O before carbonyl-C), C(=O)OC
251    let has_anhydride = groups.contains(&FunctionalGroup::Anhydride);
252    if !has_anhydride
253        && any(&[
254            "OC(C)=O", "OC(=O)C", "C(=O)OC", "C(=O)Oc",  // common ester patterns
255            "OC(CC", "OC(c",  // aromatic/branched esters
256        ])
257    {
258        groups.push(FunctionalGroup::Ester);
259    }
260
261    // ── 10. Carboxylic acid ────────────────────────────────────────────────
262    // After ester to avoid false positives
263    let has_ester = groups.contains(&FunctionalGroup::Ester);
264    if !has_ester && !has_anhydride {
265        // Acid patterns: C(=O)O terminal, C(O)=O, OC(=O) at boundaries
266        // In canonical SMILES: acetic acid = CC(=O)O (O is terminal)
267        let has_acid_pattern = any(&[
268            "C(=O)O",    // acetic acid: CC(=O)O — O terminal
269            "C(O)=O",    // alternative writing
270            "C(=O)[OH]", // explicit H on O
271        ]);
272        // Exclude if the pattern belongs to carbonate or similar
273        if has_acid_pattern {
274            groups.push(FunctionalGroup::CarboxylicAcid);
275        }
276    }
277
278    // ── 11. Aldehyde ──────────────────────────────────────────────────────
279    // Terminal C=O with no second C on the carbonyl C
280    // Canonical: CC=O, O=Cc..., [CH]=O
281    let has_higher_carbonyl = groups.iter().any(|g| {
282        matches!(
283            g,
284            FunctionalGroup::Amide
285                | FunctionalGroup::Ester
286                | FunctionalGroup::CarboxylicAcid
287                | FunctionalGroup::Anhydride
288        )
289    });
290    if !has_higher_carbonyl {
291        let aldehyde = smiles.ends_with("C=O")
292            || smiles.ends_with("[CH]=O")
293            || smiles.starts_with("O=C")  // e.g. O=Cc1ccccc1 (benzaldehyde)
294            || any(&["[CH]=O", "[CHO]"]);
295        if aldehyde {
296            groups.push(FunctionalGroup::Aldehyde);
297        }
298    }
299
300    // ── 12. Ketone ────────────────────────────────────────────────────────
301    // Carbonyl C with C on both sides; canonical: CC(C)=O, CC(CC)=O
302    if !has_higher_carbonyl {
303        let has_aldehyde = groups.contains(&FunctionalGroup::Aldehyde);
304        if !has_aldehyde
305            && any(&[
306                "C(C)=O",  // CC(C)=O acetone, CC(CC)=O 2-butanone
307                "C(CC)=O", "C(CCC)=O",
308                "C(c)=O",  // aryl ketone: C(c1...)=O
309                "c(=O)C",  // aromatic ketone
310                "C(=O)C",  // alternative form: CC(=O)CC
311            ])
312        {
313            groups.push(FunctionalGroup::Ketone);
314        }
315    }
316
317    // ── 13. Phenol ────────────────────────────────────────────────────────
318    if any(&[
319        "c1ccccc1O", "Oc1ccccc1",
320        "c(O)",      // aromatic C-OH inline
321        "c([OH])",   // explicit
322        "Oc1cc", "Oc1ccc", "c1cc(O)", "c1ccc(O)",
323    ]) {
324        groups.push(FunctionalGroup::Phenol);
325    }
326
327    // ── 14. Thiol ─────────────────────────────────────────────────────────
328    // Canonical: [SH] explicit, or CS at end of string
329    if any(&["[SH]", "C[SH]", "c[SH]"])
330        || smiles.ends_with("CS")
331        || smiles.ends_with("cS")
332    {
333        groups.push(FunctionalGroup::Thiol);
334    }
335
336    // ── 15. Sulphide (after thiol and sulphonic acid) ──────────────────────
337    let has_sulphonic = groups.contains(&FunctionalGroup::SulphonicAcid);
338    let has_thiol = groups.contains(&FunctionalGroup::Thiol);
339    if !has_sulphonic
340        && !has_thiol
341        && smiles.contains('S')
342        && any(&["CSC", "cSC", "CSc", "cSc", "C(S)C"])
343    {
344        groups.push(FunctionalGroup::Sulphide);
345    }
346
347    // ── 16. Alcohol ───────────────────────────────────────────────────────
348    // Aliphatic C-OH: [OH] explicit, terminal O in chain, or (O) pendant
349    let has_phenol = groups.contains(&FunctionalGroup::Phenol);
350    let has_acid = groups.contains(&FunctionalGroup::CarboxylicAcid);
351    let has_ester2 = groups.contains(&FunctionalGroup::Ester);
352    let has_anhydride2 = groups.contains(&FunctionalGroup::Anhydride);
353    if !has_phenol && !has_acid && !has_ester2 && !has_anhydride2 {
354        let alcohol = any(&["[OH]", "C[OH]"])
355            || smiles.ends_with("CO")
356            || smiles.ends_with("CCO")
357            || smiles.ends_with("O")  // generic terminal O (e.g. CCO = ethanol)
358            || any(&["C(O)", "C([OH])"]);
359        if alcohol {
360            groups.push(FunctionalGroup::Alcohol);
361        }
362    }
363
364    // ── 17. Ether ─────────────────────────────────────────────────────────
365    // C-O-C not ester, not epoxide, not acid anhydride
366    let has_epoxide = groups.contains(&FunctionalGroup::Epoxide);
367    let has_ester3 = groups.contains(&FunctionalGroup::Ester);
368    let has_acid2 = groups.contains(&FunctionalGroup::CarboxylicAcid);
369    if !has_epoxide && !has_ester3 && !has_acid2 && !has_anhydride {
370        if any(&["COC", "cOC", "COc", "cOc"]) {
371            groups.push(FunctionalGroup::Ether);
372        }
373    }
374
375    // ── 18. Amine ─────────────────────────────────────────────────────────
376    // N not in amide, nitrile, nitro
377    let has_amide = groups.contains(&FunctionalGroup::Amide);
378    let has_nitrile = groups.contains(&FunctionalGroup::Nitrile);
379    let has_nitro = groups.contains(&FunctionalGroup::Nitro);
380    if smiles.contains('N')
381        && !has_nitrile
382        && !has_nitro
383    {
384        // Look for amine patterns not adjacent to a carbonyl
385        let amine = any(&[
386            "CN", "NC", "[NH2]", "[NH3+]", "[NH]", "cN", "Nc",
387        ]);
388        // If amide already detected, only add amine if there's a free amine too
389        if amine && (!has_amide || any(&["[NH2]", "[NH3+]", "CN(", "N(C)C"])) {
390            groups.push(FunctionalGroup::Amine);
391        }
392    }
393
394    // ── 19. Halide ────────────────────────────────────────────────────────
395    if any(&[
396        "CF", "CCl", "CBr", "CI",
397        "Fc", "Clc", "Brc", "Ic",
398        "[F]", "[Cl]", "[Br]", "[I]",
399        "c[F]", "c[Cl]", "c[Br]", "c[I]",
400        "CF3", "CCl3", "CHF", "CHCl", "CHBr",
401    ]) {
402        groups.push(FunctionalGroup::Halide);
403    }
404
405    // ── 20. Aromatic ring (last — lowest priority) ────────────────────────
406    if smiles.chars().any(|c| matches!(c, 'c' | 'n' | 'o' | 's' | 'p')) {
407        groups.push(FunctionalGroup::AromaticRing);
408    }
409
410    groups
411}
412
413// ─────────────────────────────────────────────────────────────────────────────
414// Tests
415// ─────────────────────────────────────────────────────────────────────────────
416
417#[cfg(test)]
418mod tests {
419    use super::*;
420
421    fn fg(smiles: &str) -> Vec<FunctionalGroup> {
422        detect_functional_groups(smiles)
423    }
424
425    fn has(smiles: &str, g: FunctionalGroup) -> bool {
426        fg(smiles).contains(&g)
427    }
428
429    // ── Organic / inorganic ───────────────────────────────────────────────
430
431    #[test]
432    fn co2_is_inorganic() {
433        assert_eq!(classify_organic("O=C=O"), OrganicInorganic::Inorganic);
434    }
435
436    #[test]
437    fn water_is_inorganic() {
438        assert_eq!(classify_organic("O"), OrganicInorganic::Inorganic);
439    }
440
441    #[test]
442    fn ethanol_is_organic() {
443        assert_eq!(classify_organic("CCO"), OrganicInorganic::Organic);
444    }
445
446    #[test]
447    fn benzene_is_organic() {
448        assert_eq!(classify_organic("c1ccccc1"), OrganicInorganic::Organic);
449    }
450
451    // ── Functional group detection ────────────────────────────────────────
452
453    #[test]
454    fn acetic_acid_detected() {
455        // CC(=O)O — acetic acid (PubChem canonical)
456        assert!(has("CC(=O)O", FunctionalGroup::CarboxylicAcid));
457        assert!(!has("CC(=O)O", FunctionalGroup::Ester));
458    }
459
460    #[test]
461    fn ethyl_acetate_detected_as_ester() {
462        // CCOC(C)=O — ethyl acetate (PubChem canonical)
463        assert!(has("CCOC(C)=O", FunctionalGroup::Ester));
464        assert!(!has("CCOC(C)=O", FunctionalGroup::CarboxylicAcid));
465    }
466
467    #[test]
468    fn phthalic_anhydride_detected() {
469        // O=C1OC(=O)c2ccccc21
470        let groups = fg("O=C1OC(=O)c2ccccc21");
471        assert!(groups.contains(&FunctionalGroup::Anhydride));
472        assert!(!groups.contains(&FunctionalGroup::Ester));
473    }
474
475    #[test]
476    fn acetaldehyde_detected() {
477        // CC=O
478        assert!(has("CC=O", FunctionalGroup::Aldehyde));
479        assert!(!has("CC=O", FunctionalGroup::Ketone));
480    }
481
482    #[test]
483    fn acetone_detected_as_ketone() {
484        // CC(C)=O — PubChem canonical
485        assert!(has("CC(C)=O", FunctionalGroup::Ketone));
486        assert!(!has("CC(C)=O", FunctionalGroup::Aldehyde));
487    }
488
489    #[test]
490    fn ethanol_detected_as_alcohol() {
491        // CCO
492        assert!(has("CCO", FunctionalGroup::Alcohol));
493        assert!(!has("CCO", FunctionalGroup::Ether));
494    }
495
496    #[test]
497    fn dimethyl_ether_detected() {
498        // COC
499        assert!(has("COC", FunctionalGroup::Ether));
500        assert!(!has("COC", FunctionalGroup::Alcohol));
501    }
502
503    #[test]
504    fn methylamine_detected() {
505        // CN — methylamine
506        assert!(has("CN", FunctionalGroup::Amine));
507    }
508
509    #[test]
510    fn acetamide_detected() {
511        // CC(N)=O — acetamide (PubChem canonical)
512        assert!(has("CC(N)=O", FunctionalGroup::Amide));
513        assert!(!has("CC(N)=O", FunctionalGroup::Ketone));
514    }
515
516    #[test]
517    fn acetonitrile_detected() {
518        // CC#N
519        assert!(has("CC#N", FunctionalGroup::Nitrile));
520    }
521
522    #[test]
523    fn chloromethane_detected() {
524        // CCl
525        assert!(has("CCl", FunctionalGroup::Halide));
526    }
527
528    #[test]
529    fn ethylene_oxide_detected() {
530        // C1CO1 — ethylene oxide (PubChem canonical)
531        assert!(has("C1CO1", FunctionalGroup::Epoxide));
532    }
533
534    #[test]
535    fn benzene_detected_as_aromatic() {
536        assert!(has("c1ccccc1", FunctionalGroup::AromaticRing));
537    }
538
539    #[test]
540    fn phenol_detected() {
541        // Oc1ccccc1
542        assert!(has("Oc1ccccc1", FunctionalGroup::Phenol));
543    }
544
545    #[test]
546    fn nitrobenzene_detected() {
547        // O=[N+]([O-])c1ccccc1
548        assert!(has("O=[N+]([O-])c1ccccc1", FunctionalGroup::Nitro));
549    }
550
551    #[test]
552    fn ethanesulfonic_acid_detected() {
553        // CCS(=O)(=O)O
554        assert!(has("CCS(=O)(=O)O", FunctionalGroup::SulphonicAcid));
555    }
556
557    #[test]
558    fn dimethyl_sulfide_detected() {
559        // CSC
560        assert!(has("CSC", FunctionalGroup::Sulphide));
561    }
562
563    #[test]
564    fn methanethiol_detected() {
565        // C[SH]
566        assert!(has("C[SH]", FunctionalGroup::Thiol));
567    }
568
569    #[test]
570    fn isocyanate_detected() {
571        // CN=C=O — methyl isocyanate
572        assert!(has("CN=C=O", FunctionalGroup::Isocyanate));
573    }
574
575    #[test]
576    fn trimethyl_phosphate_detected() {
577        // COP(=O)(OC)OC
578        assert!(has("COP(=O)(OC)OC", FunctionalGroup::Phosphate));
579    }
580}
hs_predict/smiles/detector.rs

hs_predict/smiles/
detector.rs
