Add tautomer filter (#760)

* add tautomer filter

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update openff/evaluator/datasets/curation/components/filtering.py

Co-authored-by: Matt Thompson <matt.thompson@openforcefield.org>

* rm try/except

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Matt Thompson <matt.thompson@openforcefield.org>

Author: 3 people

openff/evaluator/_tests/test_datasets/test_curation/test_filtering.py

@@ -38,6 +38,8 @@
     FilterByStereochemistrySchema,
     FilterBySubstances,
     FilterBySubstancesSchema,
+    FilterByTautomers,
+    FilterByTautomersSchema,
     FilterByTemperature,
     FilterByTemperatureSchema,
     FilterDuplicates,
@@ -1212,3 +1214,224 @@ def test_curation_does_not_alter_precision():
     )
 
     assert list(data_frame["Mole Fraction 1"]) == list(filtered["Mole Fraction 1"])
+
+
+def test_validate_filter_by_tautomers():
+    FilterByTautomersSchema()
+    FilterByTautomersSchema(categories_to_include=None, categories_to_exclude=[])
+    FilterByTautomersSchema(categories_to_include=["AMIDE_IMIDIC_ACID"])
+
+    with pytest.raises(ValidationError):
+        FilterByTautomersSchema(categories_to_include=None, categories_to_exclude=None)
+
+    with pytest.raises(ValidationError):
+        FilterByTautomersSchema(
+            categories_to_include=["AMIDE_IMIDIC_ACID"],
+            categories_to_exclude=["BETA_DIKETONE"],
+        )
+
+    with pytest.raises(ValidationError):
+        FilterByTautomersSchema(categories_to_include=["NOT_A_CATEGORY"])
+
+
+def test_filter_by_tautomers_schema_default_whitelist():
+    schema = FilterByTautomersSchema()
+
+    assert set(schema.categories_to_include) == {
+        "ALPHA_AMINO_ACID",
+        "AMIDE_ENOL",
+        "AMIDE_IMIDIC_ACID",
+        "CARBOXYLIC_ACID_ENOL",
+        "ESTER_ENOL",
+        "IMINE_ENAMINE_PRIMARY",
+        "IMINE_ENAMINE_SECONDARY",
+        "KETO_ENOL_ALIPHATIC",
+        "KETO_ENOL_CYCLIC",
+        "KETO_ENOL_AROMATIC",
+        "KETENE_YNOL",
+        "LACTAM_LACTIM",
+        "OXIME_NITROSO",
+    }
+
+
+def test_filter_by_tautomers_via_workflow():
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 1, "Component 1": "C"},
+            {
+                "N Components": 1,
+                "Component 1": "CC(=O)CC(=O)C",
+            },  # beta-diketone, not in whitelist
+        ]
+    )
+
+    schema = CurationWorkflowSchema(component_schemas=[FilterByTautomersSchema()])
+    filtered_frame = CurationWorkflow.apply(data_frame, schema)
+
+    assert len(filtered_frame) == 1
+    assert filtered_frame.iloc[0]["Component 1"] == "C"
+
+
+def test_filter_by_tautomers_no_match_removed_default():
+    data_frame = pandas.DataFrame(
+        # ensure we don't start picking anything up crazy like ethanol
+        [
+            {"N Components": 1, "Component 1": "C"},
+            {"N Components": 1, "Component 1": "CCO"},
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == len(data_frame)
+
+
+def test_filter_by_tautomers_whitelist_keto_enol_aliphatic_kept():
+    """Acetone (KETO_ENOL_ALIPHATIC) must survive the default filter."""
+    data_frame = pandas.DataFrame([{"N Components": 1, "Component 1": "CC(C)=O"}])
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == 1
+
+
+def test_filter_by_tautomers_default_whitelist_only():
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 1, "Component 1": "C"},
+            {"N Components": 1, "Component 1": "CC(=O)N"},  # amide → kept
+            {
+                "N Components": 1,
+                "Component 1": "CC(=O)CC(=O)C",
+            },  # beta-diketone → removed
+            {"N Components": 1, "Component 1": "O=C1CCCCC1"},  # cyclic keto/enol → kept
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == 3
+    assert set(filtered_frame["Component 1"]) == {"C", "CC(=O)N", "O=C1CCCCC1"}
+
+
+def test_filter_by_tautomers_explicit_include():
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 1, "Component 1": "C"},
+            {"N Components": 1, "Component 1": "CC(=O)N"},
+            {"N Components": 1, "Component 1": "CC(=O)CC(=O)C"},
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(
+        data_frame,
+        FilterByTautomersSchema(categories_to_include=["AMIDE_IMIDIC_ACID"]),
+    )
+
+    assert len(filtered_frame) == 2
+    assert set(filtered_frame["Component 1"]) == {"C", "CC(=O)N"}
+
+
+def test_filter_by_tautomers_explicit_exclude():
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 1, "Component 1": "CC(=O)N"},
+            {"N Components": 1, "Component 1": "C[N+](=O)[O-]"},
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(
+        data_frame,
+        FilterByTautomersSchema(
+            categories_to_include=None, categories_to_exclude=["AMIDE_IMIDIC_ACID"]
+        ),
+    )
+
+    assert len(filtered_frame) == 1
+    assert filtered_frame.iloc[0]["Component 1"] == "C[N+](=O)[O-]"
+
+
+def test_filter_by_tautomers_exclude_suppression_canonical():
+    """Acetylacetone is canonically BETA_DIKETONE (suppression hides KETO_ENOL_ALIPHATIC).
+    Excluding KETO_ENOL_ALIPHATIC should therefore keep it; excluding BETA_DIKETONE
+    should remove it."""
+    data_frame = pandas.DataFrame([{"N Components": 1, "Component 1": "CC(=O)CC(=O)C"}])
+
+    # KETO_ENOL_ALIPHATIC is suppressed → molecule is kept
+    kept = FilterByTautomers.apply(
+        data_frame,
+        FilterByTautomersSchema(
+            categories_to_include=None,
+            categories_to_exclude=["KETO_ENOL_ALIPHATIC"],
+        ),
+    )
+    assert len(kept) == 1
+
+    # BETA_DIKETONE is its canonical category → molecule is removed
+    removed = FilterByTautomers.apply(
+        data_frame,
+        FilterByTautomersSchema(
+            categories_to_include=None,
+            categories_to_exclude=["BETA_DIKETONE"],
+        ),
+    )
+    assert len(removed) == 0
+
+
+def test_filter_by_tautomers_include_suppression_applied():
+    """In include mode, suppression must apply: enol-acetylacetone matches both
+    BETA_DIKETONE and KETO_ENOL_ALIPHATIC, but BETA_DIKETONE suppresses the
+    latter, so specifying categories_to_include=["BETA_DIKETONE"] must keep it.
+    The enol form CC(O)=CC(=O)C is used because BETA_DIKETONE's dominant form
+    is the enol."""
+    data_frame = pandas.DataFrame([{"N Components": 1, "Component 1": "CC(O)=CC(=O)C"}])
+
+    filtered_frame = FilterByTautomers.apply(
+        data_frame,
+        FilterByTautomersSchema(categories_to_include=["BETA_DIKETONE"]),
+    )
+
+    assert len(filtered_frame) == 1
+
+
+def test_filter_by_tautomers_minor_form_rejected():
+    """A molecule in the minor tautomeric form must be rejected even if its
+    category is whitelisted. CC(=O)O (acetic acid) is the dominant form and
+    passes; C=C(O)O (the enol/minor form) must be removed."""
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 1, "Component 1": "CC(=O)O"},  # dominant — kept
+            {"N Components": 1, "Component 1": "C=C(O)O"},  # minor — removed
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == 1
+    assert filtered_frame.iloc[0]["Component 1"] == "CC(=O)O"
+
+
+def test_filter_by_tautomers_multi_component_row_removed():
+    data_frame = pandas.DataFrame(
+        [
+            {"N Components": 2, "Component 1": "C", "Component 2": "CCO"},
+            {
+                "N Components": 2,
+                "Component 1": "C",
+                "Component 2": "CC(=O)CC(=O)C",
+            },
+        ]
+    )
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == 1
+    assert filtered_frame.iloc[0]["Component 2"] == "CCO"
+
+
+def test_filter_by_tautomers_empty_frame_no_failure():
+    data_frame = pandas.DataFrame(columns=["N Components", "Component 1"])
+
+    filtered_frame = FilterByTautomers.apply(data_frame, FilterByTautomersSchema())
+
+    assert len(filtered_frame) == 0

openff/evaluator/_tests/test_datasets/test_curation/test_tautomers.py

@@ -0,0 +1,140 @@
+import pytest
+from openff.toolkit.topology import Molecule
+
+from openff.evaluator.datasets.curation.components.tautomers import (
+    TAUTOMER_RULES,
+    TautomerCategory,
+    _enumerate_tautomers_cached,
+    match_tautomer_categories,
+)
+
+
+def test_tautomer_category_table():
+    assert set(TAUTOMER_RULES).issubset(set(TautomerCategory))
+
+
+@pytest.mark.parametrize(
+    "category,dominant_smiles,minor_smiles",
+    [
+        # Dominant and minor SMILES are known molecules that each SMARTS must
+        # directly match (no tautomer enumeration needed).  This proves the
+        # SMARTS are chemically meaningful, not merely syntactically valid.
+        (TautomerCategory.AMIDE_IMIDIC_ACID, "CC(=O)N", "CC(=N)O"),
+        (TautomerCategory.BETA_DIKETONE, "CC(O)=CC(=O)C", "CC(=O)CC(=O)C"),
+        (TautomerCategory.KETO_ENOL_ALIPHATIC, "CCC(C)=O", "CCC(O)=C"),
+        (TautomerCategory.KETO_ENOL_CYCLIC, "O=C1CCCCC1", "OC1=CCCCC1"),
+        (TautomerCategory.THIOKETONE_THIOL_ALIPHATIC, "CC(=S)C", "CC(S)=C"),
+        (TautomerCategory.KETO_ENOL_AROMATIC, "Oc1ccccc1", "O=C1C=CC=CC1"),
+        (TautomerCategory.IMINE_ENAMINE_SECONDARY, "CCNC=C", "CCN=CC"),
+        (TautomerCategory.IMINE_ENAMINE_PRIMARY, "CC=N", "CC(N)=C"),
+        (TautomerCategory.ALPHA_AMINO_ACID, "NCC(=O)O", "N=CC(O)O"),
+        # 4-methylimidazole: the two N-H tautomers have distinct SMILES, so each
+        # SMARTS is tested against a different molecule and a swap bug is detectable.
+        (TautomerCategory.ANNULAR_AZOLE, "Cc1c[nH]cn1", "Cc1cnc[nH]1"),
+        (TautomerCategory.LACTAM_LACTIM, "O=C1CCCCN1", "OC1=NCCCC1"),
+        (TautomerCategory.OXIME_NITROSO, "CC=NO", "CC(N=O)"),
+        (TautomerCategory.KETENE_YNOL, "CC=C=O", "CC#CO"),
+        (TautomerCategory.CARBOXYLIC_ACID_ENOL, "CC(=O)O", "C=C(O)O"),
+        (TautomerCategory.ESTER_ENOL, "CC(=O)OC", "C=C(O)OC"),
+        (TautomerCategory.AMIDE_ENOL, "CC(=O)NC", "C=C(O)NC"),
+    ],
+)
+def test_smarts_match_known_forms(category, dominant_smiles, minor_smiles):
+    """Each SMARTS must match a known molecule, not merely parse without error."""
+    rule = TAUTOMER_RULES[category]
+    dom_mol = Molecule.from_smiles(dominant_smiles, allow_undefined_stereo=True)
+    min_mol = Molecule.from_smiles(minor_smiles, allow_undefined_stereo=True)
+    assert dom_mol.chemical_environment_matches(
+        rule.dominant_smarts
+    ), f"{category} dominant_smarts did not match {dominant_smiles!r}"
+    assert min_mol.chemical_environment_matches(
+        rule.minor_smarts
+    ), f"{category} minor_smarts did not match {minor_smiles!r}"
+
+
+@pytest.mark.parametrize(
+    "smiles,expected_category",
+    [
+        ("CC(=O)N", TautomerCategory.AMIDE_IMIDIC_ACID),  # acetamide
+        ("CC(=O)CC(=O)C", TautomerCategory.BETA_DIKETONE),  # acetylacetone
+        ("O=C1CCCCC1", TautomerCategory.KETO_ENOL_CYCLIC),  # cyclohexanone
+        ("CC(C)=O", TautomerCategory.KETO_ENOL_ALIPHATIC),  # acetone
+        ("c1ccccc1O", TautomerCategory.KETO_ENOL_AROMATIC),  # phenol
+        ("Cc1ccc(O)cc1", TautomerCategory.KETO_ENOL_AROMATIC),  # para-cresol
+        ("c1cnc[nH]1", TautomerCategory.ANNULAR_AZOLE),  # imidazole
+        ("NCC(=O)O", TautomerCategory.ALPHA_AMINO_ACID),  # glycine
+        ("O=C1CCCCN1", TautomerCategory.LACTAM_LACTIM),  # 2-piperidinone
+        ("CC=NO", TautomerCategory.OXIME_NITROSO),  # acetaldoxime
+        (
+            "CC=N",
+            TautomerCategory.IMINE_ENAMINE_PRIMARY,
+        ),  # ethylideneamine (acetaldehyde primary imine)
+        ("CCNC=C", TautomerCategory.IMINE_ENAMINE_SECONDARY),  # secondary enamine
+        ("CC(=S)C", TautomerCategory.THIOKETONE_THIOL_ALIPHATIC),  # thioacetone
+        ("CC=C=O", TautomerCategory.KETENE_YNOL),  # methylketene
+        ("CC(=O)O", TautomerCategory.CARBOXYLIC_ACID_ENOL),  # acetic acid
+        ("CC(=O)OC", TautomerCategory.ESTER_ENOL),  # methyl acetate
+    ],
+)
+def test_match_tautomer_categories(smiles, expected_category):
+    categories = match_tautomer_categories(smiles)
+    assert expected_category in categories
+
+
+@pytest.mark.parametrize(
+    "smiles",
+    [
+        "C",  # methane
+        "CC",  # ethane
+        "CCO",  # ethanol
+        "c1ccccc1",  # benzene
+        "C1CCCCC1",  # cyclohexane
+        "CCOCC",  # diethyl ether
+    ],
+)
+def test_match_tautomer_categories_no_match(smiles):
+    assert match_tautomer_categories(smiles) == frozenset()
+
+
+def test_amide_enol_secondary_amide():
+    """N-methyl acetamide (CC(=O)NC) triggers AMIDE_ENOL in raw SMARTS but is
+    suppressed because AMIDE_IMIDIC_ACID co-fires and takes priority for amides."""
+    raw = match_tautomer_categories("CC(=O)NC", suppress=False)
+    assert TautomerCategory.AMIDE_ENOL in raw
+    suppressed = match_tautomer_categories("CC(=O)NC")
+    assert TautomerCategory.AMIDE_IMIDIC_ACID in suppressed
+    assert TautomerCategory.AMIDE_ENOL not in suppressed
+
+
+@pytest.mark.parametrize(
+    "category,smiles,expect_dominant,expect_minor",
+    [
+        # AMIDE_ENOL: both dominant and minor are reachable from a single seed.
+        (TautomerCategory.AMIDE_ENOL, "CC(=O)NC", True, True),
+        # Plot uses an alternate lactam seed to make the lactam/lactim pair
+        # visually distinct while still matching both sides.
+        (TautomerCategory.LACTAM_LACTIM, "O=C1NCCC=C1", True, True),
+    ],
+)
+def test_plot_example_tautomer_coverage(
+    category,
+    smiles,
+    expect_dominant,
+    expect_minor,
+):
+    Molecule.from_smiles(smiles, allow_undefined_stereo=True)
+
+    rule = TAUTOMER_RULES[category]
+    tautomers = _enumerate_tautomers_cached(smiles)
+
+    has_dominant = any(
+        tautomer.chemical_environment_matches(rule.dominant_smarts)
+        for tautomer in tautomers
+    )
+    has_minor = any(
+        tautomer.chemical_environment_matches(rule.minor_smarts)
+        for tautomer in tautomers
+    )
+
+    assert has_dominant is expect_dominant
+    assert has_minor is expect_minor