oracle-ads 2.13.9rc0__py3-none-any.whl → 2.13.9rc1__py3-none-any.whl

ads/explanations/mlx_interface.py

@@ -0,0 +1,386 @@
+#!/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/
+
+try:
+    from mlx import LimeExplainer
+    from mlx import FDExplainer, AleExplainer
+    from mlx import PermutationImportance
+    from mlx.whatif import WhatIf
+except:
+    pass
+from ads.common import logger
+from ads.dataset.helper import is_text_data
+
+import pandas as pd
+from ads.common.decorator.deprecate import deprecated
+
+
+def _reset_index(x):
+    assert isinstance(x, pd.DataFrame) or isinstance(x, pd.Series)
+    return x.reset_index(drop=True)
+
+
+def check_tabular_or_text(est, X):
+    """
+    Returns "text" if a text dataset, "tabular" otherwise.
+
+    Parameters
+    ----------
+    est : ADSModel
+        Model to explain.
+    X : pandas.DataFrame
+        Dataset.
+
+    Return
+    ------
+    str
+        "text" or "tabular"
+    """
+    return "text" if is_text_data(X) else "tabular"
+
+
+@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_lime_explainer(
+    explainer,
+    est,
+    X_train,
+    y_train,
+    mode,
+    class_names=None,
+    selected_features=None,
+    client=None,
+    batch_size=16,
+    surrogate_model="linear",
+    num_samples=5000,
+    exp_sorting="absolute",
+    discretization="decile",
+    scale_weight=True,
+):
+    """
+    Initializes a local LIME Explainer. Also supports aggregate local
+    explanations, which approximates a global behavior based on multiple local explanations.
+
+    Supports both tabular and text datasets. The explainer is initialized to the defaults
+    and can be updated with `MLXGlobalExplainer.configure_feature_importance()` or
+    `MLXLocalExplainer.configure_local_explainer()`.
+
+    Parameters
+    ----------
+    explainer : LimeExplainer, None
+        If the explainer has previously been initialized, it can be passed in to avoid
+        creating a new explainer object. If `None`, a new `LimeExplainer` instance will be created.
+    est : ADSModel
+        Model to explain.
+    X_train : pandas.DataFrame
+        Training dataset.
+    y_train : pandas.DataFrame/Series
+        Training labels.
+    mode : str
+        'classification' or 'regression'.
+    class_names : list
+        List of target names.
+    selected_features : list[int], optional
+        Pass the selected features information to the explainer. Defaults value is `None`.
+    client : Dask Client
+        Specifies that Dask Client object to use in MLX. If None, no parallelization.
+    batch_size : int
+        Number of local explanations that are batched and processed by each Dask worker
+        in parallel.
+    surrogate_model : str
+        Surrogate model to approximate the local behavior of the ML model. Can be
+        'linear' or 'decision_tree'.
+    num_samples : int
+        Number of samples the local explainer generates in the local neighborhood
+        around the sample to explain to fit the surrogate model.
+    exp_sorting : str
+        Order of how to sort the feature importances. Can be 'absolute' or 'ordered'.
+        Absolute ordering orders based on the absolute values, while ordered considers
+        the sign of the feature importance values.
+    discretizer : str
+        Method to discretize continuous features in the local explainer. Supports 'decile',
+        'quartile', 'entropy', and `None`. If `None`, the continuous feature values are
+        used directly. If not None, each continuous feature is discretized and treated
+        as a categorical feature.
+    scale_weight : bool
+        Normalizes the feature importance coefficients from the local explainer to sum to one.
+
+    Return
+    ------
+    :class:`mlx.LimeExplainer`
+    """
+    if explainer is None:
+        exp = LimeExplainer()
+    else:
+        if not isinstance(explainer, LimeExplainer):
+            raise TypeError(
+                "Invalid explainer provided to "
+                "init_lime_explainer: {}".format(type(explainer))
+            )
+        exp = explainer
+    exp_type = check_tabular_or_text(est, X_train)
+    exp.set_config(
+        type=exp_type,
+        mode=mode,
+        discretizer=discretization,
+        client=client,
+        batch_size=batch_size,
+        scale_weight=scale_weight,
+        surrogate_model=surrogate_model,
+        num_samples=num_samples,
+        exp_sorting=exp_sorting,
+        kernel_width="dynamic",
+    )
+    exp.fit(
+        est,
+        X_train,
+        y=y_train,
+        target_names=class_names,
+        selected_features=selected_features,
+    )
+    return exp
+
+
+@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_permutation_importance_explainer(
+    explainer,
+    est,
+    X_train,
+    y_train,
+    mode,
+    class_names=None,
+    selected_features=None,
+    client=None,
+    random_state=42,
+):
+    """
+    Initializes a Global Feature Permutation Importance Explainer.
+
+    Supported for tabular datasets only.
+
+    The explainer is initialized to the defaults and can be updated with
+    MLXGlobalExplainer.configure_feature_importance().
+
+    Parameters
+    ----------
+    explainer : PermutationImportance, None
+        If the explainer has previously been initialized, it can be passed in to avoid
+        creating a new explainer object. If `None`, a new `PermutationImportance` explainer
+        will be created.
+    est : ADSModel
+        Model to explain.
+    X_train : pandas.DataFrame
+        Training dataset.
+    y_train : pandas.DataFrame/Series
+        Training labels.
+    mode : str
+        'classification' or 'regression'.
+    class_names : list, optional
+        List of target names. Default value is `None`
+    selected_features : list[str], list[int], optional
+        Pass the selected features list to the explainer. Defaults value is `None`.
+    client : Dask Client, optional
+        Specifies that Dask Client object to use in MLX. If `None`, no parallelization.
+    random_state : int, optional
+        Random seed, by default 42.
+
+    Return
+    ------
+    :class:`mlx.PermutationImportance`
+    """
+    if explainer is None:
+        exp = PermutationImportance()
+    else:
+        if not isinstance(explainer, PermutationImportance):
+            raise TypeError(
+                "Invalid explainer provided to "
+                "init_permutation_importance_explainer: {}".format(type(explainer))
+            )
+        exp = explainer
+    if check_tabular_or_text(est, X_train) == "text":
+        raise TypeError(
+            "Global feature importance explainers are currently not "
+            "supported for text datasets."
+        )
+    exp.set_config(mode=mode, client=client, random_state=random_state)
+    try:
+        exp.fit(
+            est,
+            X_train,
+            y=y_train,
+            target_names=class_names,
+            selected_features=selected_features,
+        )
+    except Exception as e:
+        logger.error(
+            f"Unable to construct the PermutationImportance explainer based on the MLX config "
+            f"and fit to the train data due to: {e}."
+        )
+        raise e
+    return exp
+
+
+@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_partial_dependence_explainer(
+    explainer, est, X_train, y_train, mode, class_names=None, client=None
+):
+    """
+    Initializes a Global feature dependence explainer.
+
+    Supports one and two feature partial dependence plots (PDP) and one feature individual
+    conditional expectation plots (ICE). Currently only supported for tabular datasets
+    (text is not supported).
+
+    The explainer is initialized to the defaults and can be updated with
+    `MLXGlobalExplainer.configure_partial_dependence()`.
+
+    Parameters
+    ----------
+    explainer : FDExplainer
+        If the explainer has previously been initialized, it can be passed in to avoid
+        creating a new explainer object. If None, a new `FDExplainer` will be created.
+    est : ADSModel
+        Model to explain.
+    X_train : pandas.DataFrame
+        Training dataset.
+    y_train : pandas.DataFrame/Series
+        Training labels.
+    mode : str
+        'classification' or 'regression'.
+    class_names : list
+        List of target names.
+    client : Dask Client
+        Specifies that Dask Client object to use in MLX. If None, no parallelization.
+
+    Return
+    ------
+    :class:`mlx.FDExplainer`
+    """
+    if explainer is None:
+        exp = FDExplainer()
+    else:
+        if not isinstance(explainer, FDExplainer):
+            raise TypeError(
+                "Invalid explainer provided to "
+                "init_partial_dependence_explainer: {}".format(type(explainer))
+            )
+        exp = explainer
+    if check_tabular_or_text(est, X_train) == "text":
+        raise TypeError(
+            "Global partial dependence explainers are currently not "
+            "supported for text datasets."
+        )
+    exp.set_config(mode=mode, client=client)
+    exp.fit(est, X_train, y=y_train, target_names=class_names)
+    return exp
+
+
+@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_ale_explainer(
+    explainer, est, X_train, y_train, mode, class_names=None, client=None
+):
+    """
+    Initializes a Global Accumulated Local Effects(ALE) Explainer.
+
+    Supports one feature ALE plots. Supported for tabular datasets
+    (text is not supported).
+
+    The explainer is initialized to the defaults and can be updated with
+    `MLXGlobalExplainer.configure_accumulated_local_effects()`.
+
+    Parameters
+    ----------
+    explainer : AleExplainer
+        If the explainer has previously been initialized, it can be passed in to avoid
+        creating a new explainer object. If None, a new AleExplainer will be created.
+    est : ADSModel
+        Model to explain.
+    X_train : pandas.DataFrame
+        Training dataset.
+    y_train : pandas.DataFrame/Series
+        Training labels.
+    mode : str
+        "classification" or "regression".
+    class_names : list, optional
+        List of target names. Default value is `None`.
+    client : Dask Client, optional
+        Specifies that Dask Client object to use in MLX. If `None`, no parallelization.
+
+    Return
+    ------
+    :class:`mlx.FDExplainer`
+    """
+    if explainer is None:
+        exp = AleExplainer()
+    else:
+        if not isinstance(explainer, AleExplainer):
+            raise TypeError(
+                "Invalid explainer provided to "
+                "init_partial_dependence_explainer: {}".format(type(explainer))
+            )
+        exp = explainer
+    if check_tabular_or_text(est, X_train) == "text":
+        raise TypeError(
+            "Global partial dependence explainers are currently not "
+            "supported for text datasets."
+        )
+    exp.set_config(mode=mode, client=client)
+    exp.fit(est, X_train, y=y_train, target_names=class_names)
+    return exp
+
+
+@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_whatif_explainer(
+    explainer,
+    est,
+    X_test,
+    y_test,
+    mode,
+    class_names=None,
+    train=None,
+    target_title="target",
+    random_state=42,
+    **kwargs,
+):
+    if explainer is None:
+        width = kwargs.get("width", 1100)
+        exp = WhatIf(mode=mode, random_state=random_state, width=width)
+    else:
+        if not isinstance(explainer, WhatIf):
+            raise TypeError(
+                "Invalid explorer provided to "
+                "init_explorer: {}".format(type(explainer))
+            )
+        exp = explainer
+    exp_type = check_tabular_or_text(est, X_test)
+    if exp_type == "text":
+        raise TypeError(
+            "WhatIf explainer are currently not "
+            "supported for text datasets.".format(type(explainer))
+        )
+    exp.fit(
+        model=est,
+        X=X_test,
+        y=y_test,
+        target_names=class_names,
+        train=train,
+        target_title=target_title,
+    )
+    return exp

ads/explanations/mlx_local_explainer.py

@@ -0,0 +1,287 @@
+#!/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/
+
+import numpy as np
+import pandas as pd
+from ads.common import logger
+from ads.explanations.base_explainer import LocalExplainer
+from ads.explanations.mlx_interface import init_lime_explainer
+from ads.common.decorator.deprecate import deprecated
+
+
+class MLXLocalExplainer(LocalExplainer):
+    """
+    Local Explainer class.
+
+    Generates explanations for single predictions from machine learning models.
+    For tabular and text datasets, supports
+
+        - Binary classification
+        - Multi-class classification
+        - Regression
+    """
+
+    @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):
+        super(LocalExplainer, self).__init__()
+        self.explainer = None
+
+    def explain(
+        self,
+        row,
+        y=None,
+        num_features=None,
+        report_fidelity=True,
+        validation_percentiles=None,
+        selected_features=None,
+    ):
+        """
+        Explains the sample, row. Returns a local explanation object.
+
+        Parameters
+        ----------
+        row : pandas.DataFrame
+            Pandas DataFrame of one row (instance) to explain.
+        y : pandas.DataFrame/Series, optional
+            True target label/value for row. Default value is `None`.
+        num_features : int, optional
+            Number of features to show in the local explanation. By default `None`,
+            which includes all features.
+        report_fidelity : bool, optional
+            If `True`, the explanation quality (fidelity) is computed and shown in
+            the local explanation visualization. Default value is `True`.
+        validation_percentiles : list of int, optional
+            List of values specifying the different regions to evaluate the local explanation model
+            quality (fidelity). This is specified in percentiles of the distances from the
+            instance to explain to all of the samples in the dataset used to fit the explainer.
+            For example, [1, 5, 10], generates three evaluation datasets with a maximum distance from
+            the instance to explain (row) of 1, 5, and 10 percentiles of the distances from the instance
+            to explain (row) and all other samples in the train set. The evaluation dataset at percentile
+            1 is very local to the sample to explain, the evaluation dataset at percentile 10 evaluates
+            the explanation quality further away from the instance to explain (row). This can be helpful
+            to see how the explanation generalizes to nearby samples. By default None ([1, 5, 15]).
+        selected_features: list[int], optional
+            List of the selected features (list of numbers of features). It can be any subset of
+            the original features that are in the dataset provided to the model.
+            Default value is None.
+
+        Return
+        ------
+        LocalExplanation
+            Local explanation object.
+        """
+        self.configure_local_explainer(selected_features=selected_features)
+        assert row is not None and isinstance(row, pd.DataFrame) and row.shape[0] == 1
+
+        labels = list(range(len(self.class_names)))
+
+        if num_features is None:
+            num_features = len(row.columns.values)
+
+        try:
+            explanation = self.explainer.compute(
+                row.copy(),
+                y=None if y is None else y.copy(),
+                labels=labels,
+                verbose=False,
+                num_features=num_features,
+                report_fidelity=report_fidelity,
+                validation_percentiles=validation_percentiles,
+            )[0]
+        except IndexError as e:
+            if selected_features is not None:
+                raise IndexError(
+                    f"Unable to generate local explanations due to: {e}. "
+                    f"selected_features must be a list of features within the bounds of the existing features "
+                    f"(that were provided to model). Provided selected_features: {selected_features}."
+                )
+        except Exception as e:
+            logger.error(f"Unable to generate local explanations due to: {e}.")
+            raise e
+
+        return LocalExplanation(explanation, self.class_names)
+
+    def configure_local_explainer(self, **kwargs):
+        """
+        Validates the local explanation configuration parameters and initializes the local
+        explainer with the provided configuration parameters.
+
+        Supported configuration options in kwargs:
+            - `surrogate_model` (str): Surrogate model to use. Can be 'linear' or 'decision_tree'.
+            - `num_samples` (int): Number of generated samples to fit the surrogate model.
+            - `exp_sorting` (str): Feature importance sorting. Can be 'absolute' or 'ordered'.
+            - `scale_weight` (bool): Normalizes the feature importance coefficients from LIME to sum to one.
+            - `client`: Only allowed to be None to disable parallelization.
+            - `batch_size` (int): Number of local explanations per Dask worker.
+            - `random_state` (`None` or `int` or instance of `RandomState`): the random state.
+            - `selected_features` (`None`, or `list`): list of the selected features numbers.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword parameter dictionary.
+
+        Return
+        ------
+        MLXLocalExplainer
+            Modified instance (self)
+        """
+        avail_args = [
+            "client",
+            "surrogate_model",
+            "num_samples",
+            "exp_sorting",
+            "scale_weight",
+            "batch_size",
+            "selected_features",
+        ]
+        for k, v in kwargs.items():
+            if k not in avail_args:
+                raise ValueError(
+                    "Unexpected argument for the local explainer: {}".format(k)
+                )
+        if kwargs.get("client", None) is not None:
+            raise ValueError(
+                "Invalid client provided. Currently only supports disabling parallelization "
+                "by setting client=None"
+            )
+        if kwargs.get("surrogate_model", None) not in ["linear", "decision_tree", None]:
+            raise ValueError(
+                "Invalid surrogate_model provided. Currently only supports linear or decision_tree"
+            )
+        selected_features = kwargs.get("selected_features", None)
+        if selected_features is not None and not isinstance(selected_features, list):
+            raise ValueError(
+                f"selected_features ({selected_features}) value must be a list of features, "
+                f"but it is of type: {type(selected_features)}."
+            )
+
+        self._init_explainer(**kwargs)
+        return self
+
+    def summary(self):
+        """
+        Displays detailed information about the local LIME explainer.
+
+        Return
+        ------
+        str
+            HTML object representing the explainer summary.
+        """
+        if self.explainer is None:
+            self.configure_local_explainer()
+        return self.explainer.show_in_notebook()
+
+    def _init_explainer(self, **kwargs):
+        """
+        Internal function to initialize the local explainer.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword parameter dictionary.
+        """
+        if self.mode == "regression":
+            self.class_names_ = ["Target"]
+        self.explainer = init_lime_explainer(
+            self.explainer,
+            self.est,
+            self.X_train,
+            self.y_train,
+            self.mode,
+            class_names=self.class_names,
+            **kwargs,
+        )
+
+
+class LocalExplanation:
+    """
+    Local explanation object constructed by the :class:`MLXLocalExplainer`.
+
+    Contains functions to visualize the explanation and extract the
+    raw explanation data.
+    """
+
+    def __init__(self, explanation, class_names):
+        self.explanation = explanation
+        self.class_names = class_names
+        if isinstance(self.class_names, np.ndarray):
+            self.class_names = self.class_names.tolist()
+
+    def show_in_notebook(
+        self, mode="lime", labels=None, colormap=None, return_wordcloud=False, **kwargs
+    ):
+        """
+        Generate a local explanation visualization for this explanation object.
+
+        Contains:
+            - Information about the model's prediction and the true target label/value.
+            - The instance being explained.
+            - Information about the local explainer configuration parameters.
+            - Legend describing how to interpret the explanation.
+            - The actual explanation (ordered list of +/- feature importances).
+            - Quality (fidelity) evaluation of the explanation.
+
+        Parameters
+        ----------
+        mode : str
+            Type of visualization to generate for the explanation. `mode` can be one of the following:
+                - **lime**: Horizontal bar chart where each feature contributes either to an increase
+                        or decrease in the target value.
+                - **stacked**: Stacked horizontal bar chart where each feature contributes either to an
+                        increase or decrease in the target value.
+                - **dual**: Horizontal bar chart where each feature can contribute both to an increase
+                        or decrease in the target value (only supported when the :class:`MLXLocalExplainer`
+                        surrogate model is set to "decision_tree").
+                - **wordcloud**: Word cloud highlighting the important features/words for a given target
+                             label/value. Features/ or words with higher importance are larger than those
+                             of a lower importance.
+        labels : tuple, list, int, bool, str
+            Label indices or name of label to visualize. If `None`, all of the labels that the
+            explanation was generated for will be visualized. Default value is `None`.
+        colormap : list of str, optional
+            List of standard colormaps to use for the wordclouds. One per label. Defaults to `None`.
+        return_wordcloud : bool, optional
+            If `True`, the wordcloud objects are returned instead of visualized. Defaults to `False`.
+        **kwargs : dict
+            Keyword dictionary for configuring the wordclouds.
+
+        Return
+        ------
+        HTML or pyplot figure
+            Returns an HTML object for this local explanation. If `mode=wordcloud` and `return_wordcloud=True`,
+            returns the wordcloud
+        """
+        if labels is None:
+            labels = (0,)
+        if np.isscalar(labels):
+            labels = [labels]
+        labels = [
+            self.class_names.index(label) if isinstance(label, str) else label
+            for label in labels
+        ]
+        return self.explanation.show_in_notebook(
+            mode=mode,
+            labels=labels,
+            colormap=colormap,
+            return_wordcloud=return_wordcloud,
+            **kwargs,
+        )
+
+    def get_diagnostics(self):
+        """
+        Extracts the raw explanation and evaluation data from the explanation object to generate
+        the visualizations.
+
+        Return
+        ------
+        dict
+            Dictionary containing the raw explanation/evaluation data.
+        """
+        return self.explanation.get_diagnostic()