Renaming of "diagnostics" package into "insights", Addition of Insigh…

…t and SHAPInsight classes, refactoring of SHAP functions into SHAPInsight class.

CHANGELOG.md

@@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
-- `diagnostics` dependency group
+- `insights` dependency group
 - SHAP explanations
 - `allow_missing` and `allow_extra` keyword arguments to `Objective.transform`
 

CONTRIBUTORS.md

@@ -27,4 +27,4 @@
 - Julian Streibel (Merck Life Science KGaA, Darmstadt, Germany):\
   Bernoulli multi-armed bandit and Thompson sampling
 - Alexander Wieczorek (Swiss Federal Institute for Materials Science and Technology, Dübendorf, Switzerland):\
-  SHAP explainers for diagnoatics
+  SHAP explainers for insights

README.md

@@ -296,7 +296,7 @@ The available groups are:
 - `mypy`: Required for static type checking.
 - `onnx`: Required for using custom surrogate models in [ONNX format](https://onnx.ai).
 - `polars`: Required for optimized search space construction via [Polars](https://docs.pola.rs/)
-- `diagnostics`: Required for built-in model and campaign analysis, e.g. [SHAP](https://shap.readthedocs.io/)pip install uv
+- `insights`: Required for built-in model and campaign analysis, e.g. [SHAP](https://shap.readthedocs.io/)pip install uv
 - `simulation`: Enabling the [simulation](https://emdgroup.github.io/baybe/stable/_autosummary/baybe.simulation.html) module.
 - `test`: Required for running the tests.
 - `dev`: All of the above plus `tox` and `pip-audit`. For code contributors.

baybe/_optional/info.py

@@ -46,7 +46,7 @@ def exclude_sys_path(path: str, /):  # noqa: DOC402, DOC404
 
 # Package combinations
 CHEM_INSTALLED = MORDRED_INSTALLED and RDKIT_INSTALLED
-DIAGNOSTICS_INSTALLED = SHAP_INSTALLED
+INSIGHTS_INSTALLED = SHAP_INSTALLED
 LINT_INSTALLED = all(
     (
         FLAKE8_INSTALLED,

baybe/_optional/insights.py

@@ -0,0 +1,16 @@
+"""Optional import for insight subpackage."""
+
+from baybe.exceptions import OptionalImportError
+
+try:
+    import shap
+except ModuleNotFoundError as ex:
+    raise OptionalImportError(
+        "Explainer functionality is unavailable because 'insights' is not installed."
+        " Consider installing BayBE with 'insights' dependency, e.g. via "
+        "`pip install baybe[insights]`."
+    ) from ex
+
+__all__ = [
+    "shap",
+]

baybe/insights/__init__.py

@@ -0,0 +1,12 @@
+"""Baybe insights (optional)."""
+
+from baybe._optional.info import INSIGHTS_INSTALLED
+
+if INSIGHTS_INSTALLED:
+    from baybe.insights.base import Insight
+    from baybe.insights.shap import SHAPInsight
+
+__all__ = [
+    "SHAPInsight",
+    "Insight",
+]

baybe/insights/base.py

@@ -0,0 +1,45 @@
+"""Base class for all insights."""
+
+from abc import ABC
+
+import pandas as pd
+
+from baybe import Campaign
+from baybe._optional.info import INSIGHTS_INSTALLED
+from baybe.objectives.base import Objective
+from baybe.recommenders.pure.bayesian.base import BayesianRecommender
+from baybe.searchspace import SearchSpace
+
+if INSIGHTS_INSTALLED:
+    pass
+
+
+class Insight(ABC):
+    """Base class for all insights."""
+
+    def __init__(self, surrogate):
+        self.surrogate = surrogate
+
+    @classmethod
+    def from_campaign(cls, campaign: Campaign):
+        """Create an insight from a campaign."""
+        return cls(campaign.get_surrogate())
+
+    @classmethod
+    def from_recommender(
+        cls,
+        recommender: BayesianRecommender,
+        searchspace: SearchSpace,
+        objective: Objective,
+        bg_data: pd.DataFrame,
+    ):
+        """Create an insight from a recommender."""
+        if not hasattr(recommender, "get_surrogate"):
+            raise ValueError(
+                "The provided recommender does not provide a surrogate model."
+            )
+        surrogate_model = recommender.get_surrogate(searchspace, objective, bg_data)
+
+        return cls(
+            surrogate_model,
+        )