Add TSSaliency to Python TrustyAI (#172)

* Add TSSaliency

* Fix linting and formatting

Author: ruivieira

pyproject.toml

@@ -49,7 +49,7 @@ dev = [
     "xgboost==1.4.2"
 ]
 extras = [
-    "aix360 [default,tsice] @ https://github.com/Trusted-AI/AIX360/archive/refs/heads/master.zip"
+    "aix360 [default,tsice,tssaliency] @ https://github.com/Trusted-AI/AIX360/archive/refs/heads/master.zip"
 ]
 
 [project.urls]

src/trustyai/explainers/extras/tssaliency.py

@@ -0,0 +1,83 @@
+"""
+Wrapper module for TSSaliencyExplainer from aix360.
+Original at https://github.com/Trusted-AI/AIX360/
+"""
+
+from typing import Callable, List
+
+import pandas as pd
+import numpy as np
+from aix360.algorithms.tssaliency import TSSaliencyExplainer as TSSaliencyExplainerAIX
+from pandas.io.formats.style import Styler
+import matplotlib.pyplot as plt
+
+from trustyai.explainers.explanation_results import ExplanationResults
+
+
+class TSSaliencyResults(ExplanationResults):
+    """Wraps TSSaliency results. This object is returned by the :class:`~TSSaliencyExplainer`,
+    and provides a variety of methods to visualize and interact with the explanation.
+    """
+
+    def __init__(self, explanation):
+        self.explanation = explanation
+
+    def as_dataframe(self) -> pd.DataFrame:
+        saliencies = self.explanation["saliency"].reshape(-1)
+        return pd.DataFrame(saliencies, columns=self.explanation["feature_names"])
+
+    def as_html(self) -> Styler:
+        """Returns the explanation as an HTML table."""
+        dataframe = self.as_dataframe()
+        return dataframe.style
+
+    def plot(self):
+        """Plot tssaliency explanation for the test point
+        Based on https://github.com/Trusted-AI/AIX360/blob/master/examples/tssaliency"""
+        max_abs = np.max(np.abs(self.explanation["saliency"]))
+
+        plt.imshow(
+            self.explanation["saliency"][np.newaxis, :],
+            aspect="auto",
+            cmap="seismic",
+            vmin=-max_abs,
+            vmax=max_abs,
+        )
+        plt.colorbar()
+        plt.plot(self.explanation["input_data"])
+        plt.show()
+
+
+class TSSaliencyExplainer(TSSaliencyExplainerAIX):
+    """
+    Wrapper for TSSaliencyExplainer from aix360.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        model: Callable,
+        input_length: int,
+        feature_names: List[str],
+        base_value: List[float] = None,
+        n_samples: int = 50,
+        gradient_samples: int = 25,
+        gradient_function: Callable = None,
+        random_seed: int = 22,
+    ):
+        super().__init__(
+            model=model,
+            input_length=input_length,
+            feature_names=feature_names,
+            base_value=base_value,
+            n_samples=n_samples,
+            gradient_samples=gradient_samples,
+            gradient_function=gradient_function,
+            random_seed=random_seed,
+        )
+
+    def explain(self, inputs, outputs=None, **kwargs) -> TSSaliencyResults:
+        """
+        Explain the model's prediction on X.
+        """
+        _explanation = super().explain_instance(inputs, y=outputs, **kwargs)
+        return TSSaliencyResults(_explanation)

tests/extras/tsice/test_tssaliency.py

@@ -0,0 +1,95 @@
+import unittest
+import numpy as np
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from sklearn.ensemble import RandomForestRegressor
+
+from aix360.datasets import SunspotDataset
+from trustyai.explainers.extras.tssaliency import TSSaliencyExplainer
+from trustyai.utils.extras.timeseries import tsFrame
+
+
+# transform a time series dataset into a supervised learning dataset
+# below sample forecaster is from: https://machinelearningmastery.com/random-forest-for-time-series-forecasting/
+class RandomForestUniVariateForecaster:
+    def __init__(self, n_past=4, n_future=1, RFparams={"n_estimators": 250}):
+        self.n_past = n_past
+        self.n_future = n_future
+        self.model = RandomForestRegressor(**RFparams)
+
+    def fit(self, X):
+        train = self._series_to_supervised(X, n_in=self.n_past, n_out=self.n_future)
+        trainX, trainy = train[:, : -self.n_future], train[:, -self.n_future:]
+        self.model = self.model.fit(trainX, trainy)
+        return self
+
+    def _series_to_supervised(self, data, n_in=1, n_out=1, dropnan=True):
+        n_vars = 1 if type(data) is list else data.shape[1]
+        df = pd.DataFrame(data)
+        cols = list()
+
+        # input sequence (t-n, ... t-1)
+        for i in range(n_in, 0, -1):
+            cols.append(df.shift(i))
+        # forecast sequence (t, t+1, ... t+n)
+        for i in range(0, n_out):
+            cols.append(df.shift(-i))
+        # put it all together
+        agg = pd.concat(cols, axis=1)
+        # drop rows with NaN values
+        if dropnan:
+            agg.dropna(inplace=True)
+        return agg.values
+
+    def predict(self, X):
+        row = X[-self.n_past:].flatten()
+        y_pred = self.model.predict(np.asarray([row]))
+        return y_pred
+
+
+class TestTSSaliencyExplainer(unittest.TestCase):
+    def setUp(self):
+        # load data
+        df, schema = SunspotDataset().load_data()
+        ts = tsFrame(
+            df, timestamp_column=schema["timestamp"], columns=schema["targets"]
+        )
+
+        (self.ts_train, self.ts_test) = train_test_split(
+            ts, shuffle=False, stratify=None, test_size=0.15, train_size=None
+        )
+
+    def test_tssaliency(self):
+        # load model
+        input_length = 48
+        forecast_horizon = 10
+        forecaster = RandomForestUniVariateForecaster(
+            n_past=input_length, n_future=forecast_horizon
+        )
+
+        forecaster.fit(self.ts_train.iloc[-200:])
+
+        # initialize/fit explainer
+
+        explainer = TSSaliencyExplainer(
+            model=forecaster.predict,
+            input_length=input_length,
+            feature_names=self.ts_train.columns.tolist(),
+            n_samples=2,
+            gradient_samples=50,
+        )
+
+        # compute explanations
+        test_window = self.ts_test.iloc[:input_length]
+        explanation = explainer.explain(test_window)
+
+        # validate explanation structure
+        self.assertIn("input_data", explanation.explanation)
+        self.assertIn("feature_names", explanation.explanation)
+        self.assertIn("saliency", explanation.explanation)
+        self.assertIn("timestamps", explanation.explanation)
+        self.assertIn("base_value", explanation.explanation)
+        self.assertIn("instance_prediction", explanation.explanation)
+        self.assertIn("base_value_prediction", explanation.explanation)
+
+        self.assertEqual(explanation.explanation["saliency"].shape, test_window.shape)