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

ads/explanations/base_explainer.py

@@ -1,142 +0,0 @@
-#!/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

@@ -1,83 +0,0 @@
-### 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

@@ -1,190 +0,0 @@
-#!/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()