oracle-ads 2.13.9rc0__py3-none-any.whl → 2.13.10__py3-none-any.whl

ads/explanations/base_explainer.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2020, 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+from abc import abstractmethod
+
+from ads.common.decorator.deprecate import deprecated
+
+
+class Explainer:
+    """Base class for `GlobalExplainer` and `LocalExplainer`"""
+
+    @deprecated(
+        details="Working with AutoML has moved from within ADS to working directly with the AutoMLx library. AutoMLx are preinstalled in conda pack automlx_p38_cpu_v2 and later, and can now be updated independently of ADS. AutoMLx documentation may be found at https://docs.oracle.com/en-us/iaas/tools/automlx/latest/html/multiversion/v23.1.1/index.html. Notebook examples are in Oracle's samples repository: https://github.com/oracle-samples/oci-data-science-ai-samples/tree/master/notebook_examples and a migration tutorial can be found at https://accelerated-data-science.readthedocs.io/en/latest/user_guide/model_training/automl/quick_start.html .",
+        raise_error=True,
+    )
+    def __init__(self):
+        self.X_train_ = None
+        self.y_train_ = None
+        self.X_test_ = None
+        self.y_test_ = None
+        self.est_ = None
+        self.mode_ = None
+        self.class_names_ = None
+
+    def setup(self, model, X_test, y_test, X_train=None, y_train=None):
+        """
+        Sets up required attributes for global explainer.
+
+        Parameters
+        ----------
+        model : instance of `ADSModel`
+            The model being explained
+        X_test : pandas.DataFrame
+            Test data to explain.
+        y_test : pandas.Series
+            Labels for test data.
+        X_train : pandas.DataFrame, optional
+            Training data to build explainer. Defaults to `None`.
+        y_train : pandas.Series, optional
+            Labels for training data. Defaults to `None`.
+        """
+        # assert isinstance(model, ADSModel)
+        self.X_train_ = X_train if X_train is not None else X_test
+        self.y_train_ = y_train if y_train is not None else y_test
+        self.X_test_ = X_test
+        self.y_test_ = y_test
+        self.est_ = model
+        if hasattr(model, "classes_") and model.classes_ is not None:
+            self.mode_ = "classification"
+            self.class_names_ = model.classes_
+        else:
+            self.mode_ = "regression"
+
+    @property
+    def X_train(self):
+        """
+        Training data.
+        """
+        return self.X_train_
+
+    @property
+    def y_train(self):
+        """
+        Labels for training data.
+        """
+        return self.y_train_
+
+    @property
+    def X_test(self):
+        """
+        Test data.
+        """
+        return self.X_test_
+
+    @property
+    def y_test(self):
+        """
+        Labels for test data.
+        """
+        return self.y_test_
+
+    @property
+    def mode(self):
+        """
+        Mode of explanation.
+        Either `classification` or `regression`.
+        """
+        return self.mode_
+
+    @property
+    def est(self):
+        """
+        Model Estimator.
+        """
+        return self.est_
+
+    @property
+    def class_names(self):
+        """
+        Class names.
+        Returns `None` for regression.
+        """
+        return self.class_names_
+
+
+class GlobalExplainer(Explainer):
+    """Abstract `GlobalExplainer` class. Must be subclassed to create instances."""
+
+    @abstractmethod
+    def compute_feature_importance(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def compute_partial_dependence(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def show_in_notebook(self):
+        pass
+
+
+class LocalExplainer(Explainer):
+    """Abstract `LocalExplainer` class. Must be subclassed to create instances."""
+
+    @abstractmethod
+    def explain(self, **kwargs):
+        pass
+
+
+class WhatIfExplainer(Explainer):
+    """Abstract `WhatIfExplainer` class. Must be subclassed to create instances."""
+
+    @abstractmethod
+    def explore_sample(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def explore_predictions(self, **kwargs):
+        pass

ads/explanations/capabilities.md

@@ -0,0 +1,83 @@
+### Model Explanation Capabilities
+
+Model Evaluation Service (MES) exposes various capabilities to aid in
+understanding the results of a black-box model. Model explanations
+can be of two types:
+* Local Explanations and,
+* Global Explanations.
+
+#### Local Explanations
+
+Local explanations involve understanding and explaining the model
+results for any single data point. For example, for a loan applicant
+classification model, local explanation could imply understanding
+the reasons for declaring an applicant as high-risk.
+
+##### Usage
+
+Local explanation can be made available through implementations in
+packages such as Oracle MLX, LIME or Skater. User needs to encapsulate
+the functionality provided by such packages and expose it through
+specific methods in the encapsulating class.
+
+An example template would be:
+```python
+class LocalExplainer:
+
+    def __init__(self):
+        """
+        Code to initialize local explainer.
+        """
+
+    def explanation(self, X):
+        """
+        Code to generate explanations for the record X in parameters
+        """
+```
+
+Such an implementation can then be used from an environment like
+Jupyter notebook. The implementation logic for generating local
+explanations can be changed and the consumer code for the above
+mentioned class will be able to use it without any changes.
+
+#### Global Explanations
+
+Global explanations involve explaining the over-all behavior of a
+model. Examples of global explanations include determination of
+importance of features as well as partial dependence plots which
+describe how strong of an influence a subset of features have on the
+response variable.
+
+##### Usage
+
+As with the local explanations, the global explanations can be made
+available through implementations in packages such as Oracle MLX,
+Skater etc. User needs to encapsulate the functionality provided by
+such packages and expose it through specific methods in the
+encapsulating class.
+
+An example template would be:
+```python
+class GlobalExplainer:
+
+    def __init__(self):
+        """
+        Initialize the global explainer
+        """
+
+    def compute_feature_importance(self, X):
+        """
+        Logic to compute feature importance for records in sample X
+        """
+    def compute_partial_dependence(self, X):
+        """
+        Logic to compute partial dependence among the variables of
+        a sample X
+        """
+```
+
+Again, similar to local explanations, such an implementation can then
+be used from an environment like Jupyter notebook. The implementation
+logic for generating global explanations can be changed and the
+consumer code for the above mentioned class will be able to use it
+without any changes.

ads/explanations/explainer.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; -*-
+
+# Copyright (c) 2020, 2023 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+
+from ads.explanations import MLXGlobalExplainer, MLXLocalExplainer
+from ads.explanations.mlx_whatif_explainer import MLXWhatIfExplainer
+from ads.explanations.mlx_interface import _reset_index
+from ads.common.decorator.deprecate import deprecated
+
+
+class ADSExplainer(object):
+    """
+    Main ADS Explainer class for configuring and managing local and global
+    explanation objects.
+    """
+
+    @deprecated(
+        details="Working with AutoML has moved from within ADS to working directly with the AutoMLx library. AutoMLx are preinstalled in conda pack automlx_p38_cpu_v2 and later, and can now be updated independently of ADS. AutoMLx documentation may be found at https://docs.oracle.com/en-us/iaas/tools/automlx/latest/html/multiversion/v23.1.1/index.html. Notebook examples are in Oracle's samples repository: https://github.com/oracle-samples/oci-data-science-ai-samples/tree/master/notebook_examples and a migration tutorial can be found at https://accelerated-data-science.readthedocs.io/en/latest/user_guide/model_training/automl/quick_start.html .",
+        raise_error=True,
+    )
+    def __init__(self, test_data, model, training_data=None):
+        """
+        Creates an ads explainer object.
+
+        Parameters
+        ----------
+        test_data : ads.common.data.ADSData
+            The test data for exaplanation built with `ADSData.build()`.
+        model : ads.common.model.ADSModel
+            The model used for explanation built with `ADSModel.from_estimator()`.
+            Maximum length of the list is 3.
+        training_data : ads.common.data.ADSData instance, optional
+            Training data using `ADSData.build()`.
+            Using `ADSData.build()`.
+
+        Examples
+        --------
+        train, test = ds.train_test_split()
+
+        model = MyModelClass.train(train)
+
+        explainer = ADSExplainer(test, model)
+        """
+
+        self.X_train = None
+        self.y_train = None
+        if training_data is not None:
+            self.X_train, self.y_train = training_data.X, training_data.y
+        self.X_test, self.y_test = test_data.X, test_data.y
+        self.model = model
+
+    def global_explanation(self, provider=MLXGlobalExplainer()):
+        """
+        Initializes the given global explainer provider and returns it. The returned
+        explainer will have the following properties set:
+
+        * **est**: Estimator in the ADSModel
+        * **class_names** (`Iterable`): Target classes. None for regression
+        * **X_test** (`pandas.DataFrame`): Test data to explain.
+        * **y_test** (`pandas.Series`): Labels for test data.
+        * **X_train** (`pandas.DataFrame`, optional): Training data to build explainer.
+        * **y_train** (`pandas.Series`, optional) Labels for training data.
+
+        Parameters
+        ----------
+        provider : instance of `GlobalExplainer`, optional
+            The explainer instance that is set up. Defaults to `MLXGlobalExplainer`.
+            The properties will be set on the object
+
+        Return
+        ------
+        `GlobalExplainer` object
+            Modified instance of `GlobalExplainer` implementation passed into function
+
+        Examples
+        --------
+        explainer = ADSExplainer(test, model)
+
+        global_explanation = explainer.global_explanation()
+        """
+
+        provider.setup(self.model, self.X_test, self.y_test, self.X_train, self.y_train)
+        return provider
+
+    def local_explanation(self, provider=MLXLocalExplainer()):
+        """Initializes the given local explainer provider and returns it.
+
+        The returned `LocalExplainer` instance has the following properties set:
+
+        * **est**: Estimator in the ADSModel.
+        * **class_names** (`Iterable`): Target classes. None for regression.
+        * **X_test** (`pandas.DataFrame`): Test data to explain.
+        * **y_test** (`pandas.Series`): Labels for test data.
+        * **X_train** (`pandas.DataFrame`, optional): Training data to build explainer.
+        * **y_train** (`pandas.Series`, optional): Labels for training data.
+
+        Parameters
+        ----------
+        provider : instance of `LocalExplainer`, optional
+            The explainer instance that is set up. Defaults to `MLXLocalExplainer`.
+
+        Return
+        ------
+        `LocalExplainer` object
+            Modified instance of `LocalExplainer` implementation passed into function.
+
+        Examples
+        --------
+        explainer = ADSExplainer(test, model)
+
+        local_explanation = explainer.local_explanation()
+        """
+
+        provider.setup(self.model, self.X_test, self.y_test, self.X_train, self.y_train)
+        return provider
+
+    def whatif_explanation(self, provider=MLXWhatIfExplainer()):
+        """Initializes the given mlx explorer provider and returns it.
+
+        The returned `MLXWhatIfExplainer` instance would have the following properties set:
+
+        * **est**: Estimator in the ADSModel.
+        * **class_names** (Iterable): Target classes. None for regression.
+        * **X_test** (pandas.DataFrame): Test data to explain.
+        * **y_test** (pandas.Series): Labels for test data.
+        * **X_train** (pandas.DataFrame, optional): Training data to build explainer.
+        * **y_train** (pandas.Series, optional): Labels for training data.
+
+        Parameters
+        ----------
+        provider : Instance of `MLXWhatIfExplainer` implementation, optional.
+            Defaults to `MLXWhatIfExplainer`
+
+        Return
+        ------
+        `MLXWhatIfExplainer` object
+            Configured explanation provider.
+
+        Examples
+        --------
+        explainer = ADSExplainer(test, model)
+
+        local_explanation = explainer.explore_sample()
+        """
+
+        if self.X_train is None:
+            provider.setup(
+                model=self.model,
+                X_test=_reset_index(self.X_test),
+                y_test=_reset_index(self.y_test),
+                X_train=self.X_train,
+                y_train=self.y_train,
+            )
+        else:
+            provider.setup(
+                model=self.model,
+                X_test=_reset_index(self.X_test),
+                y_test=_reset_index(self.y_test),
+                X_train=_reset_index(self.X_train),
+                y_train=_reset_index(self.y_train),
+            )
+        return provider
+
+    def show_in_notebook(self, provider=MLXGlobalExplainer()):
+        """Generates a global or local explanation based on the default values and
+        returns a visualization for the explanation.
+
+        Parameters
+        ----------
+        provider : Instance of `GlobalExplainer` or `LocalExplainer` implementation, optional
+            Configures the type of explanation to generate and visualize (local or global).
+            Default is `MLXGlobalExplainer()`. Currently does not support `MLXWhatIfExplainer`.
+
+        Return
+        ------
+        `None`
+            Nothing
+
+
+        Raises
+        ------
+        TypeError
+            If `provider` is an instance of `MLXWhatIfExplainer`
+        """
+
+        if isinstance(provider, MLXWhatIfExplainer):
+            raise TypeError("MLXWhatIfExplainer does not support show_in_notebook.")
+        self.global_explanation(provider=provider).show_in_notebook()