Source code for qsarkit.sar._cliff_drawing

"""Draw an activity cliff: the two structures, with what differs highlighted.

A SAS map says how many cliffs a dataset contains and where they sit; it
cannot say *what changed*. That question is answered by putting the two
structures side by side with their common core greyed out and the differing
atoms picked out, which is the form a medicinal chemist reads directly.

The common core is the maximum common substructure, so the highlight is the
part of each molecule the other one lacks. For a pair the fingerprint cannot
tell apart at all -- stereoisomers, or homologues differing only in chain
length -- the MCS covers everything and nothing is highlighted, which is
itself the finding: the difference is invisible to a topological
representation, and no model reading one can separate the pair.

References
----------
- Stumpfe, D. & Bajorath, J. (2012). "Exploring Activity Cliffs in Medicinal
  Chemistry." J. Med. Chem., 55(7), 2932-2942.
  https://doi.org/10.1021/jm201706b
- Wassermann, A. M., Wawer, M. & Bajorath, J. (2010). "Activity Landscape
  Representations for Structure-Activity Relationship Analysis."
  J. Med. Chem., 53(23), 8209-8223. https://doi.org/10.1021/jm100933w
"""

from __future__ import annotations

from typing import Any, List, Literal, Optional, Sequence, Tuple

import numpy as np

__all__ = ["cliff_difference_atoms", "draw_activity_cliff", "draw_activity_cliffs"]

_CORE_COLOUR = (0.85, 0.85, 0.85)
_GAINED_COLOUR = (0.30, 0.69, 0.49)
_LOST_COLOUR = (0.90, 0.35, 0.35)


[docs] def cliff_difference_atoms( mol_a: Any, mol_b: Any, timeout: int = 5 ) -> Tuple[List[int], List[int]]: """Atoms of each molecule that lie outside their common core. Parameters ---------- mol_a, mol_b : Mol timeout : int, default 5 Seconds allowed for the maximum-common-substructure search. The MCS problem is NP-hard, so a pathological pair is cut off rather than allowed to hang; on a timeout every atom is reported as differing, which is honest about having failed to find the core. Returns ------- (list of int, list of int) Indices into ``mol_a`` and ``mol_b``. Both are empty when the two molecules are identical under the MCS -- the case where a topological representation cannot distinguish them. Examples -------- >>> from rdkit import Chem >>> from qsarkit.sar import cliff_difference_atoms >>> a = Chem.MolFromSmiles("c1ccccc1O") >>> b = Chem.MolFromSmiles("c1ccccc1N") >>> in_a, in_b = cliff_difference_atoms(a, b) >>> len(in_a), len(in_b) (1, 1) """ from rdkit import Chem from rdkit.Chem import rdFMCS result = rdFMCS.FindMCS( [mol_a, mol_b], timeout=timeout, ringMatchesRingOnly=True, completeRingsOnly=False, ) if not result.smartsString: return list(range(mol_a.GetNumAtoms())), list(range(mol_b.GetNumAtoms())) core = Chem.MolFromSmarts(result.smartsString) if core is None: # pragma: no cover - malformed SMARTS from RDKit return list(range(mol_a.GetNumAtoms())), list(range(mol_b.GetNumAtoms())) def _outside(mol: Any) -> List[int]: match = mol.GetSubstructMatch(core) matched = set(match) return [i for i in range(mol.GetNumAtoms()) if i not in matched] return _outside(mol_a), _outside(mol_b)
def _draw_pair( mol_a: Any, mol_b: Any, legends: Sequence[str], size: Tuple[int, int], fmt: str, timeout: int, ) -> Any: from rdkit import Chem from rdkit.Chem import Draw from rdkit.Chem.Draw import rdMolDraw2D diff_a, diff_b = cliff_difference_atoms(mol_a, mol_b, timeout=timeout) copies = [] highlights: List[List[int]] = [] colours: List[dict] = [] for mol, differing, colour in ( (mol_a, diff_a, _LOST_COLOUR), (mol_b, diff_b, _GAINED_COLOUR), ): copy = Chem.Mol(mol) Chem.rdDepictor.Compute2DCoords(copy) copies.append(copy) highlights.append(list(differing)) colours.append({int(i): colour for i in differing}) width, height = size drawer = ( rdMolDraw2D.MolDraw2DSVG(width * 2, height, width, height) if fmt == "svg" else rdMolDraw2D.MolDraw2DCairo(width * 2, height, width, height) ) # The bundled RDKit stubs type drawOptions() too loosely to accept these # assignments; see the note on typings/ in the README. options: Any = drawer.drawOptions() options.legendFontSize = 15 options.highlightBondWidthMultiplier = 16 drawer.DrawMolecules( copies, legends=list(legends), highlightAtoms=highlights, highlightAtomColors=colours, ) drawer.FinishDrawing() text = drawer.GetDrawingText() return text if fmt == "svg" else text
[docs] def draw_activity_cliff( cliff: Any = None, mol_a: Any = None, mol_b: Any = None, activity_a: Optional[float] = None, activity_b: Optional[float] = None, similarity: Optional[float] = None, size: Tuple[int, int] = (360, 300), fmt: Literal["svg", "png"] = "svg", timeout: int = 5, ) -> Any: """Render one activity cliff as a labelled pair of structures. Pass either an :class:`~qsarkit.sar.ActivityCliff` as ``cliff``, or the two molecules and their activities directly. Parameters ---------- cliff : ActivityCliff, optional As returned by :class:`~qsarkit.sar.ActivityCliffDetector`. mol_a, mol_b : Mol, optional Used when ``cliff`` is not given. activity_a, activity_b : float, optional Shown in the legends. similarity : float, optional Shown in the legend of the second structure. size : tuple of int, default (360, 300) Size of *each* panel; the image is twice this wide. fmt : {"svg", "png"}, default "svg" timeout : int, default 5 Seconds for the MCS search. Returns ------- str or bytes SVG text, or PNG bytes. Raises ------ ValueError If neither a cliff nor a pair of molecules is given. Examples -------- >>> from rdkit import Chem >>> from qsarkit.sar import draw_activity_cliff >>> a, b = Chem.MolFromSmiles("c1ccccc1O"), Chem.MolFromSmiles("c1ccccc1N") >>> svg = draw_activity_cliff( ... mol_a=a, mol_b=b, activity_a=8.1, activity_b=5.2, similarity=0.86) >>> svg.startswith("<?xml") or svg.lstrip().startswith("<svg") True """ if cliff is not None: mol_a = getattr(cliff, "mol_a", mol_a) mol_b = getattr(cliff, "mol_b", mol_b) activity_a = getattr(cliff, "activity_a", activity_a) activity_b = getattr(cliff, "activity_b", activity_b) similarity = getattr(cliff, "similarity", similarity) if mol_a is None or mol_b is None: raise ValueError( "Pass either `cliff=` an ActivityCliff, or both `mol_a=` and " "`mol_b=`." ) left = "A" if activity_a is None else f"A: activity {activity_a:g}" right = "B" if activity_b is None else f"B: activity {activity_b:g}" if activity_a is not None and activity_b is not None: # "delta", not the Greek letter: RDKit's drawing font has no glyph for # it and silently renders a blank. right += f" (delta {abs(float(activity_b) - float(activity_a)):g})" if similarity is not None: right += f" sim {float(similarity):.2f}" return _draw_pair(mol_a, mol_b, (left, right), size, fmt, timeout)
[docs] def draw_activity_cliffs( cliffs: Sequence[Any], n: int = 4, size: Tuple[int, int] = (320, 260), fmt: Literal["svg", "png"] = "svg", timeout: int = 5, ) -> List[Any]: """Render the first ``n`` cliffs, each as its own image. Returned separately rather than tiled into one grid, so a notebook can display them inline and a report can lay them out as it likes. Parameters ---------- cliffs : sequence of ActivityCliff n : int, default 4 size : tuple of int, default (320, 260) fmt : {"svg", "png"}, default "svg" timeout : int, default 5 Returns ------- list One drawing per cliff, at most ``n``. Examples -------- >>> import numpy as np >>> from rdkit import Chem >>> from qsarkit.sar import ActivityCliffDetector, draw_activity_cliffs >>> smiles = ["c1ccccc1O", "c1ccccc1N", "c1ccccc1C", "c1ccccc1Cl"] >>> mols = [Chem.MolFromSmiles(s) for s in smiles] >>> cliffs = ActivityCliffDetector( ... similarity_threshold=0.3, activity_threshold=1.0 ... ).detect(mols, [8.0, 5.0, 8.2, 5.1]) >>> drawings = draw_activity_cliffs(cliffs, n=2) >>> len(drawings) <= 2 True """ return [ draw_activity_cliff(cliff=c, size=size, fmt=fmt, timeout=timeout) for c in list(cliffs)[:n] ]