GSK-1533

python-client/giskard/core/suite.py

@@ -83,7 +83,7 @@ def to_wandb(self, **kwargs) -> None:
             # Log just a test description and a metric.
             columns = ["Metric name", "Data slice", "Metric value", "Passed"]
             data = [[*_parse_test_name(result[0]), result[1].metric, result[1].passed] for result in self.results]
-            run.log({"Test-Suite Results": wandb.Table(columns=columns, data=data)})
+            run.log({"Test suite results/Test-Suite Results": wandb.Table(columns=columns, data=data)})
 
 
 class SuiteInput:

python-client/giskard/datasets/base/__init__.py

@@ -676,7 +676,7 @@ def to_wandb(self, **kwargs) -> None:
         from giskard.integrations.wandb.wandb_utils import wandb_run
         import wandb  # noqa library import already checked in wandb_run
         with wandb_run(**kwargs) as run:
-            run.log({"dataset": wandb.Table(dataframe=self.df)})
+            run.log({"Dataset/dataset": wandb.Table(dataframe=self.df)})
 
 
 def _cast_to_list_like(object):

python-client/giskard/integrations/wandb/wandb_utils.py

@@ -1,5 +1,9 @@
 import contextlib
-from typing import Optional, Tuple, Generator
+from typing import Optional, Tuple, Generator, Any, Iterable
+
+import numpy as np
+import pandas as pd
+from shap import Explanation
 
 try:
     import wandb  # noqa
@@ -21,3 +25,68 @@ def _parse_test_name(test_name: str) -> Tuple[str, str]:
     metric_name, data_slice = test_name[0], test_name[-1]
     data_slice = data_slice.replace('"', "")
     return metric_name, data_slice
+
+
+def _wandb_bar_plot(shap_explanations: Explanation, feature_name: str) -> Any:
+    """Get wandb bar plot of shap values of the categorical feature."""
+    feature_column = "feature_values"
+    shap_column = "shap_abs_values"
+
+    # Extract feature values and related shap explanations.
+    shap_values = shap_explanations[:, feature_name].values
+    feature_values = shap_explanations[:, feature_name].data
+
+    # We are interested in magnitude.
+    shap_abs_values = np.abs(shap_values)
+
+    # Calculate mean shap value per feature value.
+    df = pd.DataFrame(data={feature_column: feature_values, shap_column: shap_abs_values})
+    shap_abs_means = pd.DataFrame(df.groupby(feature_column)[shap_column].mean()).reset_index()
+
+    # Create bar plot.
+    table = wandb.Table(dataframe=shap_abs_means)
+    plot = wandb.plot.bar(
+        table, label=feature_column, value=shap_column, title=f"Mean(Abs(SHAP)) of '{feature_name}' feature values"
+    )
+
+    return plot
+
+
+def _wandb_scatter_plot(shap_explanations: Explanation, feature_name: str) -> Any:
+    """Get wandb scatter plot of shap values of the numerical feature."""
+    feature_column = "feature_values"
+    shap_column = "shap_values"
+
+    # Extract feature values and related shap explanations.
+    shap_values = shap_explanations[:, feature_name].values
+    feature_values = shap_explanations[:, feature_name].data
+
+    # Create scatter plot.
+    df = pd.DataFrame(data={feature_column: feature_values, shap_column: shap_values})
+    table = wandb.Table(dataframe=df)
+    plot = wandb.plot.scatter(
+        table, y=feature_column, x=shap_column, title=f"'{feature_name}' feature values vs SHAP values"
+    )
+
+    return plot
+
+
+def _wandb_general_bar_plot(shap_explanations: Explanation, feature_names: Iterable) -> Any:
+    """Get wandb bar plot of general shap mean values."""
+    feature_column = "feature"
+    shap_column = "global_shap_mean"
+
+    # Calculate global shap means.
+    shap_general_means = list()
+
+    for feature_name in feature_names:
+        shap_general_means.append(np.abs(shap_explanations[:, feature_name].values).mean())
+
+    # Create bar plot.
+    df = pd.DataFrame(data={feature_column: feature_names, shap_column: shap_general_means})
+    table = wandb.Table(dataframe=df)
+    plot = wandb.plot.bar(
+        table, label=feature_column, value=shap_column, title="General Mean(Abs(SHAP)) across all features"
+    )
+
+    return plot

python-client/giskard/models/model_explanation.py

@@ -4,48 +4,101 @@
 
 import numpy as np
 import pandas as pd
+from shap.maskers import Text
+from shap import KernelExplainer, Explanation, Explainer
 
 from giskard.datasets.base import Dataset
-from giskard.ml_worker.utils.logging import timer
 from giskard.models.base import BaseModel
+from giskard.models.shap_result import ShapResult
+from giskard.ml_worker.utils.logging import timer
 
 warnings.filterwarnings("ignore", message=".*The 'nopython' keyword.*")
-import shap  # noqa
-
 logger = logging.getLogger(__name__)
 
 
-@timer()
-def explain(model: BaseModel, dataset: Dataset, input_data: Dict):
-    def prepare_df(df):
-        df = model.prepare_dataframe(df, column_dtypes=dataset.column_dtypes, target=dataset.target)
-        if dataset.target in df.columns:
-            prepared_ds = Dataset(df=df, target=dataset.target, column_types=dataset.column_types)
-        else:
-            prepared_ds = Dataset(df=df, column_types=dataset.column_types)
-        prepared_df = model.prepare_dataframe(
-            prepared_ds.df, column_dtypes=prepared_ds.column_dtypes, target=prepared_ds.target
-        )
-        columns_in_original_order = (
-            model.meta.feature_names
-            if model.meta.feature_names
-            else [c for c in dataset.df.columns if c in prepared_df.columns]
-        )
-        # Make sure column order is the same as in df
-        return prepared_df[columns_in_original_order]
+def _get_background_example(df: pd.DataFrame, feature_types: Dict[str, str]) -> pd.DataFrame:
+    """Create background example for the SHAP explainer as a mode/median of features."""
+    median = df.median(numeric_only=True)
+    background_sample = df.mode(dropna=False).head(1)
 
-    df = model.prepare_dataframe(dataset.df, column_dtypes=dataset.column_dtypes, target=dataset.target)
-    feature_names = list(df.columns)
+    # Use median of the numerical features.
+    numerical_features = [feature for feature in list(df.columns) if feature_types.get(feature) == "numeric"]
+    for feature in numerical_features:
+        background_sample[feature] = median[feature]
+
+    background_sample = background_sample.astype(df.dtypes)
+    return background_sample
+
+
+def _get_columns_original_order(prepared_dataset: Dataset, model: BaseModel, dataset: Dataset) -> list:
+    """Get columns of the prepared_dataset in the original order."""
+    features_names = model.meta.feature_names
+    return features_names if features_names else [c for c in dataset.df.columns if c in prepared_dataset.df.columns]
+
+
+def _prepare_for_explanation(input_df: pd.DataFrame, model: BaseModel, dataset: Dataset) -> pd.DataFrame:
+    """Prepare dataframe for an inference step."""
+    input_df = model.prepare_dataframe(input_df, column_dtypes=dataset.column_dtypes, target=dataset.target)
+
+    target = dataset.target if dataset.target in input_df.columns else None
+    prepared_dataset = Dataset(input_df, column_types=dataset.column_types, target=target)
+    prepared_df = prepared_dataset.df[_get_columns_original_order(prepared_dataset, model, dataset)]
+    return prepared_df
+
+
+def _calculate_dataset_shap_values(model: BaseModel, dataset: Dataset) -> np.ndarray:
+    """Perform SHAP values calculation for samples of a given dataset."""
+    # Prepare background sample to be used in the KernelSHAP.
+    background_df = model.prepare_dataframe(dataset.df, dataset.column_dtypes, dataset.target)
+    background_sample = _get_background_example(background_df, dataset.column_types)
+
+    # Prepare input data for an explanation.
+    data_to_explain = _prepare_for_explanation(dataset.df, model=model, dataset=dataset)
 
-    input_df = prepare_df(pd.DataFrame([input_data]))
+    # Obtain SHAP explanations.
+    explainer = KernelExplainer(model.predict_df, background_sample, data_to_explain.columns, keep_index=True)
+    shap_values = explainer.shap_values(data_to_explain, silent=True)
+    return shap_values
+
+
+def _get_highest_proba_shap(shap_values: list, model: BaseModel, dataset: Dataset) -> list:
+    """Get SHAP explanations of classes with the highest predicted probability."""
+    predictions = model.predict(dataset).raw_prediction
+    return [shap_values[predicted_class][sample_idx] for sample_idx, predicted_class in enumerate(predictions)]
+
+
+def explain_with_shap(model: BaseModel, dataset: Dataset, only_highest_proba: bool = True) -> ShapResult:
+    """Get SHAP explanation result."""
+    shap_values = _calculate_dataset_shap_values(model, dataset)
+    if only_highest_proba and model.is_classification:
+        shap_values = _get_highest_proba_shap(shap_values, model, dataset)
+
+    # Put SHAP values to the Explanation object for a convenience.
+    feature_names = model.meta.feature_names or list(dataset.df.columns.drop(dataset.target, errors="ignore"))
+    shap_explanations = Explanation(shap_values, data=dataset.df[feature_names], feature_names=feature_names)
+
+    feature_types = {key: dataset.column_types[key] for key in feature_names}
+    return ShapResult(shap_explanations, feature_types, feature_names, model.meta.model_type, only_highest_proba)
+
+
+def _calculate_sample_shap_values(model: BaseModel, dataset: Dataset, input_data: Dict) -> np.ndarray:
+    df = model.prepare_dataframe(dataset.df, column_dtypes=dataset.column_dtypes, target=dataset.target)
+    data_to_explain = _prepare_for_explanation(pd.DataFrame([input_data]), model=model, dataset=dataset)
 
     def predict_array(array):
         arr_df = pd.DataFrame(array, columns=list(df.columns))
-        return model.predict_df(prepare_df(arr_df))
+        return model.predict_df(_prepare_for_explanation(arr_df, model=model, dataset=dataset))
 
-    example = background_example(df, dataset.column_types)
-    kernel = shap.KernelExplainer(predict_array, example)
-    shap_values = kernel.shap_values(input_df, silent=True)
+    example = _get_background_example(df, dataset.column_types)
+    kernel = KernelExplainer(predict_array, example)
+    shap_values = kernel.shap_values(data_to_explain, silent=True)
+    return shap_values
+
+
+@timer()
+def explain(model: BaseModel, dataset: Dataset, input_data: Dict):
+    shap_values = _calculate_sample_shap_values(model, dataset, input_data)
+    feature_names = model.meta.feature_names or list(dataset.df.columns.drop(dataset.target, errors="ignore"))
 
     if model.is_regression:
         explanation_chart_data = summary_shap_regression(shap_values=shap_values, feature_names=feature_names)
@@ -63,11 +116,8 @@ def predict_array(array):
 @timer()
 def explain_text(model: BaseModel, input_df: pd.DataFrame, text_column: str, text_document: str):
     try:
-        text_explainer = shap.Explainer(
-            text_explanation_prediction_wrapper(model.predict_df, input_df, text_column),
-            shap.maskers.Text(tokenizer=r"\W+"),
-        )
-
+        masker = Text(tokenizer=r"\W+")
+        text_explainer = Explainer(text_explanation_prediction_wrapper(model.predict_df, input_df, text_column), masker)
         shap_values = text_explainer(pd.Series([text_document]))
 
         return (
@@ -80,16 +130,6 @@ def explain_text(model: BaseModel, input_df: pd.DataFrame, text_column: str, tex
         raise Exception("Failed to create text explanation") from e
 
 
-def background_example(df: pd.DataFrame, input_types: Dict[str, str]) -> pd.DataFrame:
-    example = df.mode(dropna=False).head(1)  # si plusieurs modes, on prend le premier
-    # example.fillna("", inplace=True)
-    median = df.median()
-    num_columns = [key for key in list(df.columns) if input_types.get(key) == "numeric"]
-    for column in num_columns:
-        example[column] = median[column]
-    return example.astype(df.dtypes)
-
-
 def summary_shap_classification(
     shap_values: List[np.ndarray],
     feature_names: List[str],

python-client/giskard/models/shap_result.py

@@ -0,0 +1,58 @@
+from enum import Enum
+from dataclasses import dataclass
+
+from shap import Explanation
+
+from giskard.core.core import ModelType, SupportedModelTypes
+
+
+class PanelNames(str, Enum):
+    CATEGORICAL = "Feature importance for categorical features"
+    NUMERICAL = "Feature importance for numerical features"
+    GENERAL = "Global feature importance"
+
+
+@dataclass
+class ShapResult:
+    explanations: Explanation = None
+    feature_types: dict = None
+    feature_names: list = None
+    model_type: ModelType = None
+    only_highest_proba: bool = True
+
+    def _validate_wandb_config(self):
+        if not self.only_highest_proba and self.model_type == SupportedModelTypes.CLASSIFICATION:
+            raise ValueError(
+                "We currently support 'ShapResult.to_wandb()' only with 'only_highest_proba == True' for "
+                "classification models."
+            )
+
+    def to_wandb(self, **kwargs) -> None:
+        """Create and log to the WandB run SHAP charts."""
+        from giskard.integrations.wandb.wandb_utils import wandb_run
+        from giskard.integrations.wandb.wandb_utils import _wandb_bar_plot, _wandb_general_bar_plot, _wandb_scatter_plot
+
+        self._validate_wandb_config()
+
+        with wandb_run(**kwargs) as run:
+            charts = dict()
+
+            # Create general SHAP feature importance plot.
+            general_bar_plot = _wandb_general_bar_plot(self.explanations, self.feature_names)
+            charts.update({f"{PanelNames.GENERAL}/general_shap_bar_plot": general_bar_plot})
+
+            # Create per-feature SHAP plots.
+            for feature_name, feature_type in self.feature_types.items():
+                if feature_type == "category":
+                    bar_plot = _wandb_bar_plot(self.explanations, feature_name)
+                    charts.update({f"{PanelNames.CATEGORICAL}/{feature_name}_shap_bar_plot": bar_plot})
+                elif feature_type == "numeric":
+                    scatter_plot = _wandb_scatter_plot(self.explanations, feature_name)
+                    charts.update({f"{PanelNames.NUMERICAL}/{feature_name}_shap_scatter_plot": scatter_plot})
+                else:
+                    raise NotImplementedError(
+                        "We do not support the wandb logging of ShapResult for text features yet."
+                    )
+
+            # Log created plots.
+            run.log(charts)

python-client/giskard/scanner/result.py

@@ -128,5 +128,5 @@ def to_wandb(self, **kwargs):
         with wandb_run(**kwargs) as run:
             with tempfile.NamedTemporaryFile(prefix="giskard-scan-results-", suffix=".html") as f:
                 self.to_html(filename=f.name)
-                wandb_artifact_name = f.name.split("/")[-1].split(".html")[0]
+                wandb_artifact_name = "Vulnerability scan results/" + f.name.split("/")[-1].split(".html")[0]
                 run.log({wandb_artifact_name: wandb.Html(open(f.name), inject=False)})

python-client/tests/integrations/test_wandb.py

@@ -3,24 +3,36 @@
 import re
 
 from giskard import scan
+from giskard.models.model_explanation import explain_with_shap
 
 wandb.setup(wandb.Settings(mode="disabled", program=__name__, program_relpath=__name__, disable_code=True))
 
+NOT_SUPP_TEXT_ERROR_MSG = "We do not support the wandb logging of ShapResult for text features yet."
+
 
 @pytest.mark.parametrize(
     "dataset_name,model_name",
     [
+        ("hotel_text_data", "hotel_text_model"),
         ("german_credit_data", "german_credit_model"),
         ("breast_cancer_data", "breast_cancer_model"),
         ("drug_classification_data", "drug_classification_model"),
         ("diabetes_dataset_with_target", "linear_regression_diabetes"),
-        ("hotel_text_data", "hotel_text_model"),
     ],
 )
 def test_fast(dataset_name, model_name, request):
+    # Expect the 'NotImplementedError' when dataset contains textual features.
+    exception_fixtures = ("hotel_text_data",)
+
     dataset = request.getfixturevalue(dataset_name)
     model = request.getfixturevalue(model_name)
-    _to_wandb(model, dataset)
+
+    if dataset_name in exception_fixtures:
+        with pytest.raises(NotImplementedError) as e:
+            _to_wandb(model, dataset)
+        assert e.match(NOT_SUPP_TEXT_ERROR_MSG)
+    else:
+        _to_wandb(model, dataset)
 
 
 @pytest.mark.parametrize(
@@ -34,9 +46,17 @@ def test_fast(dataset_name, model_name, request):
 )
 @pytest.mark.slow
 def test_slow(dataset_name, model_name, request):
+    exception_fixtures = ("enron_data_full", "medical_transcript_data", "amazon_review_data")
+
     dataset = request.getfixturevalue(dataset_name)
     model = request.getfixturevalue(model_name)
-    _to_wandb(model, dataset)
+
+    if dataset_name in exception_fixtures:
+        with pytest.raises(NotImplementedError) as e:
+            _to_wandb(model, dataset)
+        assert e.match(NOT_SUPP_TEXT_ERROR_MSG)
+    else:
+        _to_wandb(model, dataset)
 
 
 def _to_wandb(model, dataset):
@@ -51,4 +71,8 @@ def _to_wandb(model, dataset):
     test_suite_results = scan_results.generate_test_suite().run()
     test_suite_results.to_wandb()
 
+    # Verify that the logging of the SHAP explanation charts works.
+    explanation_results = explain_with_shap(model, dataset)
+    explanation_results.to_wandb()
+
     assert re.match("^[0-9a-z]{8}$", str(wandb.run.id))