PyIAML 1.0.0__py3-none-any.whl

iaml/decorators/runner.py

@@ -0,0 +1,100 @@
+"""Step.run() decorator."""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import time
+
+from ..logger import Logger
+
+if TYPE_CHECKING:
+    from ..candidate import Candidate
+
+
+def runner(func: callable) -> callable:
+    """runner MUST decorate your run() method. It you manage every boring things for you.
+
+        - Store results in cache
+        - Send information to Destroyers
+        - Put results in good shape
+        - And maybe more
+
+    :param callable func: decorated method.
+    :return: edited method.
+    """
+    def runner_wrapper(self, candidates: list[Candidate]) -> list[Candidate]:
+        """Wrapping decorated method
+
+        :param list[Candidate] candidates: Candidates to apply wrapper to.
+        :return: All generated candidates.
+        """
+        # Avoid circular import
+        from ..candidate import Candidate  # pylint: disable=import-outside-toplevel
+
+        if candidates.__class__ in [Candidate]:
+            candidates = [candidates]
+
+        def _shape_from_candidate(candidate: Candidate) -> str:
+            try:
+                dataset = candidate.dataset
+                if dataset is None or dataset.X is None:
+                    return "None"
+                return f"{dataset.X.shape[0]}x{dataset.X.shape[1]}"
+            except Exception:  # pylint: disable=broad-except
+                return "?"
+
+        def _summarize_shapes(cands: list[Candidate]) -> str:
+            if not cands:
+                return "none"
+            counts: dict[str, int] = {}
+            for cand in cands:
+                shape = _shape_from_candidate(cand)
+                counts[shape] = counts.get(shape, 0) + 1
+            parts = []
+            for shape in sorted(counts.keys()):
+                count = counts[shape]
+                if count == 1:
+                    parts.append(shape)
+                else:
+                    parts.append(f"{shape} (x{count})")
+            return ", ".join(parts)
+
+        logger = Logger()
+        log_timing = logger.verbose > 1
+        step_label = None
+        start_time = None
+        input_shapes = None
+        if log_timing:
+            try:
+                step_label = self.to_rich_str()
+            except Exception:  # pylint: disable=broad-except
+                step_label = self.__class__.__name__
+            logger.info(f'running step: {step_label}')
+            start_time = time.perf_counter()
+            input_shapes = _summarize_shapes(candidates)
+
+        result: list[Candidate] = []
+
+        for current_candidate in candidates:
+            if self.suitable(current_candidate.dataset) and self.enable:
+                candidate = self.from_cache(current_candidate)
+                if not candidate:
+                    candidate = func(self, current_candidate)
+                    self.add_cache(current_candidate, candidate)
+            else: # If the step is disabled or not suitable for the dataset, do nothing
+                candidate = current_candidate
+
+
+            result = result + ([candidate] if type(candidate) in [Candidate] else candidate)
+
+        if log_timing and start_time is not None:
+            elapsed = time.perf_counter() - start_time
+            output_shapes = _summarize_shapes(result)
+            logger.info(
+                f'finished step: {step_label} in {elapsed:.2f}s '
+                f'(outputs={len(result)}, data={input_shapes}->{output_shapes})'
+            )
+
+        self.candidate = result
+
+        return result
+
+    return runner_wrapper

iaml/explanation.py

@@ -0,0 +1,112 @@
+"""Enables steps to "explain" their processings and prediction results."""
+from __future__ import annotations
+
+import textwrap
+
+import numpy as np
+import shap
+
+from .plots.shap_plot import ShapPlot
+
+
+class Explanation:
+    """Enables steps to "explain" their processings and prediction results.
+
+    :param shap.Explanation, optional shap_values: Shap values to append to the explanation.
+        Default to None.
+    """
+    def __init__(
+        self,
+        shap_values: shap.Explanation = None) -> None:
+        self.shap_values = shap_values
+        """Shap values to append to the explanation."""
+
+    def to_plot(
+            self,
+            plot: str,
+            ps: slice = None,
+            scatter_feature: list[str] = None) -> ShapPlot:
+        """Plot SHAP values.
+
+        :param str plot: Plot to generate (one of "force", "scatter",
+            "beeswarm", "heatmap", "bar"). Refer to the SHAP
+            documentation for more details on these plots.
+        :param slice, optional ps: Specify the indexes of the SHAP values
+            to plot. Defaults to all predictions. If plot is
+            "force" or "waterfall", it will pick the first
+            prediction matching the provided slice (defaults to
+            first of all). Default to None.
+        :param list[str], optional scatter_feature: Specify the feature to
+            plot in the scatter plot (defaults to first). Default to None.
+        :raise RuntimeError: Cannot generate plots for this explanation without SHAP values.
+        :return: object containing shap plot
+        """
+        if self.shap_values is None:
+            raise RuntimeError('Cannot generate plots for this explanation without SHAP values.')
+
+        shap_plot = None
+        if plot == 'scatter':
+            shap_plot = ShapPlot(plot, self.shap_values, ps=ps, scatter_feature=scatter_feature)
+        else:
+            shap_plot = ShapPlot(plot, self.shap_values, ps=ps)
+
+        return shap_plot
+
+    def to_plots(self, plots: list[str] = None) -> list[ShapPlot]:
+        """Generate several plots
+
+        :param list[str], optional plots: list of plots to generate. If None are provided, it will
+            generate ['force', 'waterfall', 'beeswarm', 'scatter', 'heatmap', 'bar'].
+        :return: list of plots
+        """
+        if plots is None:
+            plots = ['force', 'waterfall', 'beeswarm', 'scatter', 'heatmap', 'bar']
+        return [self.to_plot(p) for p in plots]
+
+    def features_importance(self) -> dict[str, str]:
+        """Return features importance
+
+        :return: name and impact of each feature
+        """
+        if self.shap_values is None:
+            return []
+
+        feature_names = self.shap_values.feature_names
+        feature_values = np.abs(self.shap_values.values).mean(axis=0)
+
+        return dict(zip(feature_names, feature_values))
+
+    def to_markdown_shap(self) -> str:
+        """Renders SHAP values for this explanation as Markdown text.
+
+        :return: Markdown document.
+        """
+        if self.shap_values is None:
+            return ''
+
+        feature_importance = '\n            '.join([
+            f'| `{name}` | **{np.mean(value):.3f}** |'
+            for name, value in self.features_importance().items()
+        ])
+
+        return textwrap.dedent(f"""\
+            ### Features impact
+            | Feature | Mean impact (SHAP value) |
+            | ------- | ------------------------ |
+            {feature_importance}
+            """)
+
+    def to_markdown_plots(self, plots: list[str] = None) -> str:
+        """Generates SHAP plots for this explanation, and renders them as
+        Markdown text.
+
+        :param list[str], optional plots: list of plots to generate
+        :return: Markdown text.
+        """
+        if plots is None:
+            plots = ['force', 'waterfall', 'beeswarm', 'scatter', 'heatmap', 'bar']
+
+        if self.shap_values is None or len(plots) == 0:
+            return ""
+
+        return '\n'.join([ p.to_markdown() for p in self.to_plots(plots) ])