r"""Project per-feature attributions back onto atoms, and draw them.
SHAP and LIME attribute a prediction to *features*. For a fingerprint
model those features are hash buckets, and "bit 1743 contributed +0.21" is
not an explanation a chemist can act on. What they need is the same
information on the structure.
The bridge is the fingerprint's bit-provenance map: RDKit can report,
for each bit a molecule sets, which atom environments set it. Distributing
each bit's attribution over the atoms in its environments turns a vector of
feature attributions into a vector of atom weights, which RDKit then draws
as a similarity map.
Two caveats that the arithmetic cannot remove:
* **Bit collisions.** A hashed fingerprint folds many environments into
each bit, so a bit's attribution may belong to an environment other than
the one present in this molecule. Larger fingerprints collide less;
:meth:`AttributionAtomMapper.collision_rate` reports how much of a given
molecule's signal is affected.
* **Shared credit.** An atom appearing in several environments accumulates
weight from each. That is usually what you want -- an atom central to
many substructures really is more implicated -- but it means weights are
not a partition of the prediction and do not sum to it.
References
----------
- Riniker, S. & Landrum, G. A. (2013). "Similarity Maps -- A Visualization
Strategy for Molecular Fingerprints and Machine-Learning Methods."
J. Cheminform., 5, 43. https://doi.org/10.1186/1758-2946-5-43
- Lundberg, S. M. & Lee, S.-I. (2017). "A Unified Approach to Interpreting
Model Predictions." NeurIPS 2017, 4765-4774.
https://papers.nips.cc/paper/7062
- Ribeiro, M. T., Singh, S. & Guestrin, C. (2016). "Why Should I Trust
You?: Explaining the Predictions of Any Classifier." KDD 2016,
1135-1144. https://doi.org/10.1145/2939672.2939778
- Rogers, D. & Hahn, M. (2010). "Extended-Connectivity Fingerprints."
J. Chem. Inf. Model., 50(5), 742-754. https://doi.org/10.1021/ci100050t
- Polishchuk, P. (2017). "Interpretation of Quantitative
Structure-Activity Relationship Models: Past, Present, and Future."
J. Chem. Inf. Model., 57(11), 2618-2639.
https://doi.org/10.1021/acs.jcim.7b00274
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Any, Dict, List, Literal, Mapping, Optional, Sequence, Tuple
import numpy as np
import numpy.typing as npt
if TYPE_CHECKING: # pragma: no cover
import plotly.graph_objects as go
from rdkit.Chem import Mol
__all__ = [
"bit_atom_environments",
"bit_weights_to_atom_weights",
"AttributionAtomMapper",
"draw_atom_weights",
]
_Distribution = Literal["uniform", "center", "radius_weighted"]
[docs]
def bit_atom_environments(
mol: Any, radius: int = 2, n_bits: int = 2048, use_features: bool = False
) -> Dict[int, Tuple[Tuple[int, int], ...]]:
"""Which atom environments set each bit of a molecule's Morgan fingerprint.
Parameters
----------
mol : Mol
The molecule.
radius : int, default 2
Morgan radius. Must match the fingerprint the attributions came
from, or the bit numbering will not correspond.
n_bits : int, default 2048
Fingerprint length. Must likewise match.
use_features : bool, default False
Use the feature-based (FCFP) invariants rather than connectivity.
Returns
-------
dict
Bit index -> tuple of ``(central_atom_index, radius)`` pairs, one
per environment in this molecule that sets that bit.
Examples
--------
>>> from rdkit import Chem
>>> from qsarkit.explainability import bit_atom_environments
>>> mol = Chem.MolFromSmiles("CCO")
>>> environments = bit_atom_environments(mol, n_bits=256)
>>> len(environments) > 0
True
>>> all(isinstance(bit, int) for bit in environments)
True
Every reported central atom is a real atom of the molecule:
>>> centres = {atom for envs in environments.values() for atom, _ in envs}
>>> max(centres) < mol.GetNumAtoms()
True
References
----------
- RDKit, "Explaining bits from Morgan fingerprints":
https://www.rdkit.org/docs/GettingStartedInPython.html#explaining-bits-from-morgan-fingerprints
"""
from rdkit.Chem import rdFingerprintGenerator
generator = rdFingerprintGenerator.GetMorganGenerator(
radius=radius,
fpSize=n_bits,
atomInvariantsGenerator=(
rdFingerprintGenerator.GetMorganFeatureAtomInvGen()
if use_features
else None
),
)
output = rdFingerprintGenerator.AdditionalOutput()
output.AllocateBitInfoMap()
generator.GetFingerprint(mol, additionalOutput=output)
return {int(bit): tuple(envs) for bit, envs in output.GetBitInfoMap().items()}
def _environment_atoms(mol: Any, centre: int, radius: int) -> List[int]:
"""Atoms inside the circular environment of ``centre`` at ``radius``."""
from rdkit import Chem
if radius == 0:
return [centre]
bonds = Chem.FindAtomEnvironmentOfRadiusN(mol, radius, centre)
if not bonds:
return [centre]
atoms = {centre}
for bond_index in bonds:
bond = mol.GetBondWithIdx(bond_index)
atoms.add(bond.GetBeginAtomIdx())
atoms.add(bond.GetEndAtomIdx())
return sorted(atoms)
[docs]
def bit_weights_to_atom_weights(
mol: Any,
bit_weights: npt.ArrayLike,
radius: int = 2,
n_bits: int = 2048,
use_features: bool = False,
distribution: _Distribution = "uniform",
) -> "npt.NDArray[np.float64]":
"""Spread per-bit attributions over the atoms that produced each bit.
Parameters
----------
mol : Mol
The molecule the attributions were computed for.
bit_weights : array-like of shape (n_bits,)
One attribution per fingerprint bit -- a row of SHAP values, a LIME
coefficient vector, or any per-feature importance.
radius : int, default 2
Morgan radius used to compute ``bit_weights``.
n_bits : int, default 2048
Fingerprint length used to compute ``bit_weights``.
use_features : bool, default False
Whether those were FCFP rather than ECFP bits.
distribution : {"uniform", "center", "radius_weighted"}, default "uniform"
How a bit's weight is divided among its environment's atoms:
``"uniform"``
Split equally. Neutral, and the right default.
``"center"``
All of it to the central atom. Sharper pictures, but it
overstates the centre of a large environment.
``"radius_weighted"``
Split equally, then divide by ``radius + 1``, so a bit
describing a tight environment carries more weight per atom
than one describing a diffuse environment.
Returns
-------
ndarray of shape (n_atoms,)
Per-atom weight, ready for :func:`draw_atom_weights`.
Raises
------
ValueError
If ``bit_weights`` is not one-dimensional of length ``n_bits``.
Examples
--------
>>> import numpy as np
>>> from rdkit import Chem
>>> from qsarkit.explainability import (
... bit_atom_environments, bit_weights_to_atom_weights)
>>> mol = Chem.MolFromSmiles("CC(=O)Nc1ccc(Cl)cc1")
>>> weights = np.zeros(256)
>>> environments = bit_atom_environments(mol, n_bits=256)
>>> chlorine = [a.GetIdx() for a in mol.GetAtoms() if a.GetSymbol() == "Cl"][0]
>>> # Attribute to one bit centred on the chlorine, radius 0.
>>> for bit, envs in environments.items():
... if (chlorine, 0) in envs:
... weights[bit] = 1.0
>>> atom_weights = bit_weights_to_atom_weights(mol, weights, n_bits=256)
>>> int(np.argmax(atom_weights)) == chlorine
True
Only the atoms in that environment receive weight:
>>> int((atom_weights != 0).sum())
1
References
----------
- Riniker, S. & Landrum, G. A. (2013). J. Cheminform., 5, 43.
https://doi.org/10.1186/1758-2946-5-43
"""
values = np.asarray(bit_weights, dtype=np.float64).ravel()
if values.size != n_bits:
raise ValueError(
f"bit_weights has {values.size} entries but n_bits is {n_bits}. "
"These must match, or bit indices will not line up with the "
"attributions -- check that the fingerprint used for the "
"explanation is the one named here."
)
if distribution not in ("uniform", "center", "radius_weighted"):
raise ValueError(
f"distribution must be 'uniform', 'center' or 'radius_weighted', "
f"got {distribution!r}."
)
environments = bit_atom_environments(
mol, radius=radius, n_bits=n_bits, use_features=use_features
)
return _atom_weights_from_environments(
mol, values, environments, distribution=distribution
)
def _atom_weights_from_environments(
mol: Any,
values: "npt.NDArray[np.float64]",
environments: Dict[int, Tuple[Tuple[int, int], ...]],
distribution: _Distribution = "uniform",
) -> "npt.NDArray[np.float64]":
"""Spread per-bit weights over the atoms of the environments that set them.
Split out so the bit provenance can come either from a standalone
recomputation (:func:`bit_atom_environments`) or from the fingerprint
object itself, without the distribution logic existing twice.
"""
if distribution not in ("uniform", "center", "radius_weighted"):
raise ValueError(
f"distribution must be 'uniform', 'center' or 'radius_weighted', "
f"got {distribution!r}."
)
atom_weights = np.zeros(mol.GetNumAtoms(), dtype=np.float64)
for bit, envs in environments.items():
weight = values[bit]
if weight == 0.0:
continue
for centre, env_radius in envs:
if distribution == "center":
atom_weights[centre] += weight
continue
atoms = _environment_atoms(mol, centre, env_radius)
share = weight / len(atoms)
if distribution == "radius_weighted":
share /= env_radius + 1
for atom in atoms:
atom_weights[atom] += share
return atom_weights
def _bit_index(feature: Any) -> int:
"""Read a bit index out of whatever LIME called the feature.
LIME labels features ``"x0"``, ``"x1"``, ... when it is given no names,
which is how :class:`~qsarkit.explainability.LIMEExplainer` runs it. A
caller who supplied their own ``feature_names`` gets those back instead,
and names that are not bit indices cannot be placed on atoms.
"""
if isinstance(feature, (int, np.integer)):
return int(feature)
text = str(feature).strip()
if text.startswith("x") and text[1:].isdigit():
return int(text[1:])
if text.isdigit():
return int(text)
raise ValueError(
f"cannot read a fingerprint bit index from the feature label "
f"{feature!r}. Atom mapping needs the explanation to refer to bits by "
"index; leave `feature_names` unset on LIMEExplainer so the labels "
"stay in the form 'x123'."
)
def _lime_contributions(explanation: Any) -> List[Tuple[Any, float]]:
"""Normalise the shapes a LIME explanation arrives in to (feature, weight)."""
# The frame LIMEExplainer.explain_one returns.
columns = getattr(explanation, "columns", None)
if columns is not None and "feature" in columns and "weight" in columns:
return [
(row.feature, float(row.weight))
for row in explanation.itertuples(index=False)
]
# A LIME Explanation object.
if hasattr(explanation, "as_map"):
return [
(feature, float(weight))
for pairs in explanation.as_map().values()
for feature, weight in pairs
]
if isinstance(explanation, Mapping):
return [(feature, float(weight)) for feature, weight in explanation.items()]
try:
return [(feature, float(weight)) for feature, weight in explanation]
except (TypeError, ValueError):
raise TypeError(
f"cannot read a LIME explanation from {type(explanation).__name__}. "
"Pass the frame from LIMEExplainer.explain_one, a LIME Explanation, "
"a {bit: weight} mapping, or (bit, weight) pairs."
) from None
[docs]
class AttributionAtomMapper:
"""Turn a SHAP or LIME explainer's output into atom-level weights.
Wraps any per-feature attribution and the fingerprint that produced
those features, so a model explanation can be shown on the structure
rather than as bit indices.
Parameters
----------
fingerprint : object
The transformer whose bits the attributions refer to. Its
``radius``, ``n_bits`` and (where present) ``use_features``
attributes are read so the bit numbering matches -- typically a
:class:`~qsarkit.representation.MorganFingerprint`.
distribution : {"uniform", "center", "radius_weighted"}, default "uniform"
Passed to :func:`bit_weights_to_atom_weights`.
Attributes
----------
radius : int
n_bits : int
use_features : bool
Examples
--------
>>> import numpy as np
>>> from qsarkit.explainability import AttributionAtomMapper
>>> from qsarkit.models import QSARRegressor
>>> from qsarkit.representation import MorganFingerprint
>>> from rdkit import Chem
>>> mols = [Chem.MolFromSmiles(s) for s in
... ("CC(=O)Nc1ccccc1", "CC(=O)Nc1ccc(Cl)cc1", "CCO", "CCN")]
>>> fingerprint = MorganFingerprint(radius=2, n_bits=256)
>>> X = fingerprint.transform(mols)
>>> model = QSARRegressor("rf", random_state=0).fit(X, [6.2, 6.7, 5.0, 5.1])
>>> mapper = AttributionAtomMapper(fingerprint)
Any per-bit vector maps onto atoms. Here we use permutation
importance, which works for every backend and needs no optional
dependency:
>>> from qsarkit.explainability import PermutationImportance
>>> importance = PermutationImportance(n_repeats=2, random_state=0).fit(
... model, X, [6.2, 6.7, 5.0, 5.1])
>>> weights = mapper.atom_weights(mols[1], importance.importances_mean_)
>>> weights.shape == (mols[1].GetNumAtoms(),)
True
Symmetry-equivalent atoms receive identical weight, which is a useful
correctness check on the mapping:
>>> chlorobenzene = Chem.MolFromSmiles("Clc1ccccc1")
>>> import numpy as np
>>> bits = np.ones(256)
>>> symmetric = mapper.atom_weights(chlorobenzene, bits)
>>> bool(np.isclose(symmetric[2], symmetric[6]))
True
The collision rate says how much to trust the picture:
>>> rate = mapper.collision_rate(mols[1])
>>> 0.0 <= rate <= 1.0
True
References
----------
- Riniker, S. & Landrum, G. A. (2013). J. Cheminform., 5, 43.
https://doi.org/10.1186/1758-2946-5-43
- Polishchuk, P. (2017). J. Chem. Inf. Model., 57(11), 2618-2639.
https://doi.org/10.1021/acs.jcim.7b00274
"""
def __init__(
self, fingerprint: Any, distribution: _Distribution = "uniform"
) -> None:
if not hasattr(fingerprint, "bit_info"):
raise TypeError(
f"{type(fingerprint).__name__} cannot report which atoms set "
"each bit, so per-bit attributions cannot be placed on atoms. "
"Atom mapping needs a fingerprint whose bits correspond to "
"local atom environments and that exposes bit_info(mol) -- "
"MorganFingerprint and FeatureMorganFingerprint do. A MACCS "
"or path-based fingerprint has no such correspondence."
)
self.fingerprint = fingerprint
self.distribution = distribution
self.n_bits = int(getattr(fingerprint, "n_bits", 2048))
# Kept for `repr` and for callers that read them; the mapping itself
# no longer derives from these, because re-deriving the bit numbering
# from loose parameters disagrees with the transformer whenever a
# setting such as `use_chirality` changes the hashing.
self.radius = int(getattr(fingerprint, "radius", 2))
self.use_features = bool(getattr(fingerprint, "use_features", False))
[docs]
def atom_weights(
self, mol: Any, bit_weights: npt.ArrayLike
) -> "npt.NDArray[np.float64]":
"""Map one molecule's per-bit attributions onto its atoms.
The bit provenance comes from the fingerprint object itself, so the
bit numbering is the one the model was fitted on whatever the
fingerprint's settings.
Parameters
----------
mol : Mol
bit_weights : array-like of shape (n_bits,)
Returns
-------
ndarray of shape (n_atoms,)
Raises
------
ValueError
If ``bit_weights`` is not one-dimensional of length ``n_bits``.
"""
weights = np.asarray(bit_weights, dtype=np.float64).ravel()
if weights.size != self.n_bits:
raise ValueError(
f"bit_weights has {weights.size} entries but the fingerprint "
f"has {self.n_bits} bits. They must describe the same feature "
"matrix."
)
return _atom_weights_from_environments(
mol,
weights,
self.fingerprint.bit_info(mol),
distribution=self.distribution,
)
[docs]
def from_shap(
self, mol: Any, explainer: Any, X: npt.ArrayLike, index: int = 0
) -> "npt.NDArray[np.float64]":
"""Atom weights from a :class:`~qsarkit.explainability.SHAPExplainer`.
Parameters
----------
mol : Mol
The molecule corresponding to row ``index`` of ``X``.
explainer : SHAPExplainer
A fitted explainer.
X : array-like of shape (n_samples, n_bits)
The feature matrix the explanation is computed on.
index : int, default 0
Which row of ``X`` to explain.
Returns
-------
ndarray of shape (n_atoms,)
Raises
------
OptionalDependencyError
If ``shap`` is not installed.
"""
values = explainer.shap_values(X)
# Reduce the class axis before picking the sample, so that a raw shap
# explainer -- which returns one array per class -- does not have its
# classes read as samples. SHAPExplainer already reduces both forms.
if isinstance(values, list):
values = values[-1]
values = np.asarray(values, dtype=np.float64)
if values.ndim == 3:
# (n_samples, n_features, n_classes); attribute to the positive
# class, the one being asked about.
values = values[:, :, -1]
return self.atom_weights(mol, values[index])
[docs]
def from_lime(
self, mol: Any, explanation: Any
) -> "npt.NDArray[np.float64]":
"""Atom weights from a LIME explanation of one molecule.
Parameters
----------
mol : Mol
explanation : DataFrame, Explanation, mapping or pairs
Any of the forms LIME explanations arrive in:
* the ``feature``/``weight`` frame returned by
:meth:`~qsarkit.explainability.LIMEExplainer.explain_one`,
whose feature labels are of the form ``"x123"``;
* a LIME ``Explanation`` object, whose ``as_map()`` is read;
* a mapping of bit index to weight;
* a sequence of ``(bit index, weight)`` pairs.
Returns
-------
ndarray of shape (n_atoms,)
Raises
------
ValueError
If a feature label cannot be read as a bit index, or an index
falls outside the fingerprint.
Examples
--------
>>> import numpy as np
>>> from rdkit import Chem
>>> from qsarkit.explainability import AttributionAtomMapper
>>> from qsarkit.representation import MorganFingerprint
>>> mol = Chem.MolFromSmiles("CC(=O)Nc1ccc(Cl)cc1")
>>> fingerprint = MorganFingerprint(radius=2, n_bits=256)
>>> mapper = AttributionAtomMapper(fingerprint)
>>> some_bit = next(iter(fingerprint.bit_info(mol)))
>>> weights = mapper.from_lime(mol, {some_bit: 1.0})
>>> weights.shape == (mol.GetNumAtoms(),)
True
>>> bool(weights.sum() > 0)
True
"""
weights = np.zeros(self.n_bits, dtype=np.float64)
for feature, weight in _lime_contributions(explanation):
index = _bit_index(feature)
if not 0 <= index < self.n_bits:
raise ValueError(
f"LIME reported feature {feature!r} (bit {index}), which "
f"is outside the {self.n_bits}-bit fingerprint this "
"mapper was built with. The explanation and the mapper "
"must describe the same feature matrix."
)
weights[index] += float(weight)
return self.atom_weights(mol, weights)
[docs]
def collision_rate(self, mol: Any) -> float:
"""Fraction of this molecule's set bits shared by several environments.
A bit set by more than one environment carries attribution that
cannot be assigned to a single substructure, so a high rate means
the atom-level picture is blurred. Widening the fingerprint lowers
it.
Parameters
----------
mol : Mol
Returns
-------
float
In [0, 1]. ``0.0`` when the molecule sets no bits.
"""
environments = self.fingerprint.bit_info(mol)
if not environments:
return 0.0
collided = sum(1 for envs in environments.values() if len(envs) > 1)
return collided / len(environments)
def __repr__(self) -> str:
return (
f"<AttributionAtomMapper radius={self.radius} "
f"n_bits={self.n_bits} distribution={self.distribution!r}>"
)
[docs]
def draw_atom_weights(
mol: Any,
atom_weights: npt.ArrayLike,
size: Tuple[int, int] = (400, 400),
fmt: Literal["svg", "png"] = "svg",
normalize: bool = True,
contour_lines: int = 10,
) -> Any:
"""Render atom weights on the structure as an RDKit similarity map.
The standard cheminformatics depiction: a green-to-pink field over the
2D structure, positive contributions in one colour and negative in the
other.
Parameters
----------
mol : Mol
The molecule. A 2D conformer is computed if it has none.
atom_weights : array-like of shape (n_atoms,)
Per-atom weight, e.g. from :class:`AttributionAtomMapper`.
size : tuple of int, default (400, 400)
Image size in pixels.
fmt : {"svg", "png"}, default "svg"
``"svg"`` returns a string, which renders inline in a notebook and
embeds in HTML. ``"png"`` returns bytes.
normalize : bool, default True
Scale the weights so the largest absolute value maps to the end of
the colour scale. Keeps the picture readable regardless of the
attribution's units; turn it off to compare two molecules on one
absolute scale.
contour_lines : int, default 10
Number of contour lines drawn.
Returns
-------
str or bytes
SVG text, or PNG bytes.
Raises
------
ValueError
If ``atom_weights`` does not have one entry per atom, or ``fmt`` is
not recognized.
Examples
--------
>>> import numpy as np
>>> from rdkit import Chem
>>> from qsarkit.explainability import draw_atom_weights
>>> mol = Chem.MolFromSmiles("CC(=O)Nc1ccc(Cl)cc1")
>>> weights = np.linspace(-1, 1, mol.GetNumAtoms())
>>> svg = draw_atom_weights(mol, weights)
>>> svg.lstrip().startswith("<?xml") or svg.lstrip().startswith("<svg")
True
>>> isinstance(draw_atom_weights(mol, weights, fmt="png"), bytes)
True
A weight per atom is required, so a mismatched vector is caught rather
than silently misaligned:
>>> draw_atom_weights(mol, [0.1, 0.2])
Traceback (most recent call last):
...
ValueError: atom_weights has 2 entries but the molecule has 11 atoms.
References
----------
- Riniker, S. & Landrum, G. A. (2013). "Similarity Maps -- A
Visualization Strategy for Molecular Fingerprints and
Machine-Learning Methods." J. Cheminform., 5, 43.
https://doi.org/10.1186/1758-2946-5-43
- RDKit ``Chem.Draw.SimilarityMaps`` documentation:
https://www.rdkit.org/docs/source/rdkit.Chem.Draw.SimilarityMaps.html
"""
from rdkit import Chem
from rdkit.Chem import AllChem, Draw
from rdkit.Chem.Draw import SimilarityMaps
weights = np.asarray(atom_weights, dtype=np.float64).ravel()
if weights.size != mol.GetNumAtoms():
raise ValueError(
f"atom_weights has {weights.size} entries but the molecule has "
f"{mol.GetNumAtoms()} atoms."
)
if fmt not in ("svg", "png"):
raise ValueError(f"fmt must be 'svg' or 'png', got {fmt!r}.")
if normalize:
largest = float(np.abs(weights).max())
if largest > 0:
weights = weights / largest
# The drawing needs 2D coordinates; a molecule parsed from SMILES has none.
drawn = Chem.Mol(mol)
if drawn.GetNumConformers() == 0:
AllChem.Compute2DCoords(drawn)
drawer = (
Draw.MolDraw2DSVG(*size) if fmt == "svg" else Draw.MolDraw2DCairo(*size)
)
SimilarityMaps.GetSimilarityMapFromWeights(
drawn,
[float(w) for w in weights],
draw2d=drawer,
contourLines=contour_lines,
)
drawer.FinishDrawing()
return drawer.GetDrawingText()