Replace matched-substructure SVG image output with completeSmiles

Remove the SVG depiction feature from substructure search: the func:withImages
input, func:matchedImage output, the with_images engine flag / matched_images
field, and the highlight_match_svg helper (plus its rdDepictor/rdMolDraw2D
imports).

Add a func:completeSmiles output instead: the original, complete SMILES string
of the matching compound as stored in the service (repeated per matched-fragment
row), complementing the per-match matchedSmiles/matchedSmarts.

Docs regenerated and tests updated accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: mpagni12

README.md

@@ -280,7 +280,6 @@ differently by RDKit:
 | `func:dbNames` | `UnionType[str, NoneType]` | `None` | Optional database name to limit the search. |
 | `func:minMatchCount` | `int` | `1` | Minimum number of substructure matches required. |
 | `func:useChirality` | `bool` | `False` | If true, both tetrahedral (R/S) and double-bond (E/Z) stereochemistry are enforced during matching. Defaults to false. Most meaningful for SMILES queries; SMARTS encodes its own stereo in the pattern. |
-| `func:withImages` | `bool` | `False` | If true, populate func:matchedImage with an SVG of the database molecule, matched substructure highlighted. Defaults to false (rendering is comparatively expensive). |
 
 **Outputs:**
 
@@ -290,7 +289,7 @@ differently by RDKit:
 | `func:matchCount` | `int` | Number of matches found (1 if boolean match). |
 | `func:matchedSmiles` | `str` | SMILES of the matched fragment, rendered from the target (stereo preserved). |
 | `func:matchedSmarts` | `str` | SMARTS of the matched fragment, rendered from the target (stereo preserved). |
-| `func:matchedImage` | `str` | SVG depiction of the database molecule with the matched substructure highlighted (empty unless func:withImages is true). |
+| `func:completeSmiles` | `str` | The original, complete SMILES string of the matching compound as stored in the service. |
 
 **Example 1:**
 
@@ -310,26 +309,13 @@ SELECT ?result ?matchCount ?matchedSmiles ?matchedSmarts WHERE {
 
 ```sparql
 PREFIX func: <urn:sparql-function:>
-SELECT ?result ?matchCount ?matchedSmiles ?matchedSmarts WHERE {
+SELECT ?result ?matchCount ?matchedSmiles ?completeSmiles WHERE {
     [] a func:SubstructureSearch ;
         func:smiles "c1ccccc1" ;
         func:result ?result ;
         func:matchCount ?matchCount ;
         func:matchedSmiles ?matchedSmiles ;
-        func:matchedSmarts ?matchedSmarts .
-}
-```
-
-**Example 3:**
-
-```sparql
-PREFIX func: <urn:sparql-function:>
-SELECT ?result ?matchedImage WHERE {
-    [] a func:SubstructureSearch ;
-        func:smiles "c1ccccc1" ;
-        func:withImages true ;
-        func:result ?result ;
-        func:matchedImage ?matchedImage .
+        func:completeSmiles ?completeSmiles .
 }
 ```
 

src/mol_search_sparql_service/rdkit_fingerprints.py

@@ -15,8 +15,6 @@
     MACCSkeys,
     PatternFingerprint,
 )
-from rdkit.Chem import rdDepictor
-from rdkit.Chem.Draw import rdMolDraw2D
 
 # NOTE: we need to silence RDKit warnings that magically poped up from nowhere
 # even if it was working before, and no libs version have been changed
@@ -138,10 +136,6 @@ class SubstructureResult:
     # rendered from the target molecule so its stereochemistry is preserved.
     matched_smiles: list[str] = field(default_factory=list)
     matched_smarts: list[str] = field(default_factory=list)
-    # Parallel SVG depiction per match, with the matched atoms/bonds highlighted.
-    # Only populated when the search is run with with_images=True (rendering is
-    # comparatively expensive); otherwise left empty.
-    matched_images: list[str] = field(default_factory=list)
 
 
 # ---------------------------------------------------------------------------
@@ -443,49 +437,6 @@ def safe_mol_from_smarts(smarts: str) -> Chem.Mol | None:
         return Chem.MolFromSmarts(smarts)
 
 
-def highlight_match_svg(
-    mol: Chem.Mol, atoms: list[int], width: int = 400, height: int = 400
-) -> str:
-    """Render ``mol`` to an SVG string with ``atoms`` AND the bonds among them
-    highlighted — used to depict a matched substructure on the database molecule.
-
-    Generates fresh 2D coordinates with the CoordGen algorithm: the legacy
-    depiction can produce distorted/overlapping layouts on complex molecules
-    (rings that look "unclosed"), whereas CoordGen yields clean, properly closed
-    rings. Returns an empty string on any drawing failure so a single bad
-    depiction never aborts a search.
-    """
-    try:
-        atom_set = set(atoms)
-        # Highlight every bond whose both endpoints are in the matched atom set.
-        bonds = [
-            b.GetIdx()
-            for b in mol.GetBonds()
-            if b.GetBeginAtomIdx() in atom_set and b.GetEndAtomIdx() in atom_set
-        ]
-        # Lay the molecule out cleanly. Compute once per molecule (reused across
-        # this molecule's matches); CoordGen gives publication-quality 2D coords.
-        if mol.GetNumConformers() == 0:
-            with _silence_stderr():
-                rdDepictor.SetPreferCoordGen(True)
-                rdDepictor.Compute2DCoords(mol)
-        drawer = rdMolDraw2D.MolDraw2DSVG(width, height)
-        with _silence_stderr():
-            rdMolDraw2D.PrepareAndDrawMolecule(
-                drawer, mol, highlightAtoms=list(atoms), highlightBonds=bonds
-            )
-        drawer.FinishDrawing()
-        svg = drawer.GetDrawingText()
-        # Strip the leading XML declaration (e.g.
-        # "<?xml version='1.0' encoding='iso-8859-1'?>\n") so the result is a
-        # bare <svg> element, easier to embed inline.
-        if svg.startswith("<?xml"):
-            svg = svg[svg.index("?>") + 2 :].lstrip("\n")
-        return svg
-    except Exception:
-        return ""
-
-
 # ---------------------------------------------------------------------------
 # Search engine
 # ---------------------------------------------------------------------------
@@ -593,15 +544,10 @@ def search_substructure(
         min_match_count: int = 1,
         use_chirality: bool = False,
         query_type: str = "smiles",
-        with_images: bool = False,
     ) -> list[SubstructureResult]:
         """Executes a substructure search (Screening + Verification).
 
         Args:
-            with_images: If True, render an SVG depiction of each matched
-                fragment (highlighted on the database molecule) into
-                ``matched_images``. Off by default as rendering is comparatively
-                expensive.
             query: The query pattern, interpreted according to ``query_type``.
             query_type: ``"smiles"`` (default) parses ``query`` with
                 ``MolFromSmiles`` — sanitized, aromatized, stereo perceived.
@@ -668,7 +614,6 @@ def search_substructure(
                     seen: set[tuple[str, str]] = set()
                     matched_smiles: list[str] = []
                     matched_smarts: list[str] = []
-                    matched_images: list[str] = []
                     for atom_ids in matches:
                         atoms = list(atom_ids)
                         try:
@@ -684,10 +629,6 @@ def search_substructure(
                         seen.add(key)
                         matched_smiles.append(smi)
                         matched_smarts.append(sma)
-                        if with_images:
-                            matched_images.append(
-                                highlight_match_svg(target_mol, atoms)
-                            )
 
                     results.append(
                         SubstructureResult(
@@ -698,7 +639,6 @@ def search_substructure(
                             match_count=len(matches),
                             matched_smiles=matched_smiles,
                             matched_smarts=matched_smarts,
-                            matched_images=matched_images,
                         )
                     )
 

src/mol_search_sparql_service/sparql_service.py

@@ -23,8 +23,8 @@ class SubstructureSearchResult:
     """SMILES of the matched fragment, rendered from the target (stereo preserved)."""
     matchedSmarts: str
     """SMARTS of the matched fragment, rendered from the target (stereo preserved)."""
-    matchedImage: str
-    """SVG depiction of the database molecule with the matched substructure highlighted (empty unless func:withImages is true)."""
+    completeSmiles: str
+    """The original, complete SMILES string of the matching compound as stored in the service."""
 
 
 @dataclass
@@ -178,7 +178,6 @@ def substructure_search(
     db_names: str | None = None,
     min_match_count: int = 1,
     use_chirality: bool = False,
-    with_images: bool = False,
 ) -> list[SubstructureSearchResult]:
     """Perform substructure search using a SMARTS or SMILES query pattern.
 
@@ -199,7 +198,6 @@ def substructure_search(
         db_names: Optional database name to limit the search.
         min_match_count: Minimum number of substructure matches required.
         use_chirality: If true, both tetrahedral (R/S) and double-bond (E/Z) stereochemistry are enforced during matching. Defaults to false. Most meaningful for SMILES queries; SMARTS encodes its own stereo in the pattern.
-        with_images: If true, populate func:matchedImage with an SVG of the database molecule, matched substructure highlighted. Defaults to false (rendering is comparatively expensive).
 
     Example (SMARTS):
         ```sparql
@@ -214,28 +212,16 @@ def substructure_search(
         }
         ```
 
-    Example (SMILES):
+    Example (SMILES, with the complete molecule SMILES):
         ```sparql
         PREFIX func: <urn:sparql-function:>
-        SELECT ?result ?matchCount ?matchedSmiles ?matchedSmarts WHERE {
+        SELECT ?result ?matchCount ?matchedSmiles ?completeSmiles WHERE {
             [] a func:SubstructureSearch ;
                 func:smiles "c1ccccc1" ;
                 func:result ?result ;
                 func:matchCount ?matchCount ;
                 func:matchedSmiles ?matchedSmiles ;
-                func:matchedSmarts ?matchedSmarts .
-        }
-        ```
-
-    Example (with highlighted SVG image):
-        ```sparql
-        PREFIX func: <urn:sparql-function:>
-        SELECT ?result ?matchedImage WHERE {
-            [] a func:SubstructureSearch ;
-                func:smiles "c1ccccc1" ;
-                func:withImages true ;
-                func:result ?result ;
-                func:matchedImage ?matchedImage .
+                func:completeSmiles ?completeSmiles .
         }
         ```
     """
@@ -259,27 +245,22 @@ def substructure_search(
             min_match_count=min_match_count,
             use_chirality=use_chirality,
             query_type=query_type,
-            with_images=with_images,
         )
-        # Emit one row per distinct matched fragment so each match's SMILES,
-        # SMARTS and image are individually bindable. Compounds with no
-        # renderable fragment still surface once with empty fragment strings.
+        # Emit one row per distinct matched fragment so each match's SMILES and
+        # SMARTS are individually bindable. completeSmiles is the full original
+        # molecule SMILES, repeated on every row for that compound. Compounds
+        # with no renderable fragment still surface once with empty fragments.
         rows = []
         for r in results:
-            # matched_images is parallel to the fragment lists when with_images
-            # was requested, and empty otherwise.
-            images = r.matched_images or [""] * len(r.matched_smiles)
-            fragments = list(zip(r.matched_smiles, r.matched_smarts, images)) or [
-                ("", "", "")
-            ]
-            for smi, sma, img in fragments:
+            fragments = list(zip(r.matched_smiles, r.matched_smarts)) or [("", "")]
+            for smi, sma in fragments:
                 rows.append(
                     SubstructureSearchResult(
                         result=URIRef(r.id),
                         matchCount=int(r.match_count),
                         matchedSmiles=smi,
                         matchedSmarts=sma,
-                        matchedImage=img,
+                        completeSmiles=r.smiles,
                     )
                 )
         return rows

tests/test_parameters.py

@@ -302,39 +302,6 @@ def test_matched_fragments_deduplicated():
         os.unlink(path)
 
 
-def test_matched_images_opt_in():
-    """SVG depictions are produced only when with_images=True, parallel to the
-    matched fragments and highlighting the match."""
-    import tempfile, os
-    from mol_search_sparql_service.rdkit_fingerprints import MolSearchEngine
-
-    tsv = "?chem\t?smiles\t?db\n<http://ex.org/toluene>\tCc1ccccc1\ttest\n"
-    with tempfile.NamedTemporaryFile(mode="w", suffix=".tsv", delete=False) as f:
-        f.write(tsv)
-        path = f.name
-
-    try:
-        eng = MolSearchEngine()
-        eng.load_file(path)
-
-        # Default: no images rendered.
-        r = eng.search_substructure("c1ccccc1")[0]
-        assert r.matched_images == []
-
-        # Opt in: one SVG per matched fragment, each a valid highlighted SVG.
-        r = eng.search_substructure("c1ccccc1", with_images=True)[0]
-        assert len(r.matched_images) == len(r.matched_smiles) >= 1
-        svg = r.matched_images[0]
-        assert "<svg" in svg
-        # The XML declaration is stripped; the SVG starts at the root element.
-        assert not svg.startswith("<?xml")
-        assert svg.lstrip().startswith("<")
-        # PrepareAndDrawMolecule emits highlight markers (ellipse / fill colour).
-        assert "ellipse" in svg or "fill:#" in svg
-    finally:
-        os.unlink(path)
-
-
 def test_query_type_smiles_vs_smarts():
     """SMILES and SMARTS queries are parsed differently: a Kekulé string is
     aromatized as SMILES but stays literal/aliphatic as SMARTS."""

tests/test_sparql.py

@@ -228,21 +228,23 @@ def test_substructure_search_by_smiles():
     assert int(bindings[0]["matchCount"]["value"]) >= 1
 
 
-def test_substructure_search_with_image():
-    # func:withImages true populates func:matchedImage with a highlighted SVG.
+def test_substructure_search_complete_smiles():
+    # func:completeSmiles returns the full original SMILES of the matching
+    # compound (a superset of, and generally different from, the matched fragment).
     bindings = sparql_query("""
         PREFIX func: <urn:sparql-function:>
-        SELECT ?result ?matchedImage WHERE {
+        SELECT ?result ?matchedSmiles ?completeSmiles WHERE {
             [] a func:SubstructureSearch ;
                 func:smiles "c1ccccc1" ;
                 func:limit 5 ;
-                func:withImages true ;
                 func:result ?result ;
-                func:matchedImage ?matchedImage .
+                func:matchedSmiles ?matchedSmiles ;
+                func:completeSmiles ?completeSmiles .
         }
     """)
     assert len(bindings) > 0
-    assert "<svg" in bindings[0]["matchedImage"]["value"]
+    # Every row carries a non-empty complete SMILES string.
+    assert all(b["completeSmiles"]["value"] for b in bindings)
 
 
 def test_list_fingerprints():