diff --git a/dianna/__init__.py b/dianna/__init__.py
index 52dde758..0dbb22d9 100644
--- a/dianna/__init__.py
+++ b/dianna/__init__.py
@@ -32,6 +32,29 @@
__version__ = "0.7.0"
+def explain_timeseries(model_or_function, timeseries_data, method, labels, **kwargs):
+ """Explain timeseries data given a model and a chosen method.
+
+ Args:
+ model_or_function (callable or str): The function that runs the model to be explained _or_
+ the path to a ONNX model on disk.
+ timeseries_data (np.ndarray): Timeseries data to be explained
+ method (string): One of the supported methods: RISE, LIME or KernelSHAP
+ labels (Iterable(int)): Labels to be explained
+ kwargs: key word arguments
+
+ Returns:
+ One heatmap per class.
+
+ """
+ explainer = _get_explainer(method, kwargs, modality="Timeseries")
+ explain_image_kwargs = utils.get_kwargs_applicable_to_function(explainer.explain, kwargs)
+ return explainer.explain(model_or_function,
+ timeseries_data,
+ labels,
+ **explain_image_kwargs)
+
+
def explain_image(model_or_function, input_data, method, labels, **kwargs):
"""Explain an image (input_data) given a model and a chosen method.
diff --git a/dianna/methods/rise.py b/dianna/methods/rise.py
index 28cab728..1097609b 100644
--- a/dianna/methods/rise.py
+++ b/dianna/methods/rise.py
@@ -3,6 +3,9 @@
from tqdm import tqdm
from dianna import utils
+# To Do: remove this import when the method for different input type is splitted
+from dianna.methods.rise_timeseries import RISETimeseries # noqa: F401 ignore unused import
+
def normalize(saliency, n_masks, p_keep):
"""Normalizes salience by number of masks and keep probability."""
diff --git a/dianna/methods/rise_timeseries.py b/dianna/methods/rise_timeseries.py
new file mode 100644
index 00000000..e50d64cf
--- /dev/null
+++ b/dianna/methods/rise_timeseries.py
@@ -0,0 +1,70 @@
+import numpy as np
+from tqdm import tqdm
+from dianna import utils
+from dianna.utils.maskers import generate_masks
+from dianna.utils.maskers import mask_data
+
+
+def _make_predictions(input_data, runner, batch_size):
+ """Process the input_data with the model runner in batches and return the predictions."""
+ number_of_masks = input_data.shape[0]
+ batch_predictions = []
+ for i in tqdm(range(0, number_of_masks, batch_size), desc='Explaining'):
+ batch_predictions.append(runner(input_data[i:i + batch_size]))
+ return np.concatenate(batch_predictions)
+
+
+# Duplicate code from rise.py:
+def normalize(saliency, n_masks, p_keep):
+ """Normalizes salience by number of masks and keep probability."""
+ return saliency / n_masks / p_keep
+
+
+class RISETimeseries:
+ """RISE implementation for timeseries adapted from the image version of RISE."""
+
+ def __init__(self, n_masks=1000, feature_res=8, p_keep=0.5,
+ preprocess_function=None):
+ """RISE initializer.
+
+ Args:
+ n_masks (int): Number of masks to generate.
+ feature_res (int): Resolution of features in masks.
+ p_keep (float): Fraction of input data to keep in each mask (Default: auto-tune this value).
+ preprocess_function (callable, optional): Function to preprocess input data with
+ """
+ self.n_masks = n_masks
+ self.feature_res = feature_res
+ self.p_keep = p_keep
+ self.preprocess_function = preprocess_function
+ self.masks = None
+ self.predictions = None
+
+ def explain(self, model_or_function, input_timeseries, labels, batch_size=100, mask_type='mean'):
+ """Runs the RISE explainer on images.
+
+ The model will be called with masked timeseries,
+ with a shape defined by `batch_size` and the shape of `input_data`.
+
+ Args:
+ model_or_function (callable or str): The function that runs the model to be explained _or_
+ the path to a ONNX model on disk.
+ input_timeseries (np.ndarray): Input timeseries data to be explained
+ batch_size (int): Batch size to use for running the model.
+ labels (Iterable(int)): Labels to be explained
+ mask_type: Masking strategy for masked values. Choose from 'mean' or a callable(input_timeseries)
+
+ Returns:
+ Explanation heatmap for each class (np.ndarray).
+ """
+ runner = utils.get_function(model_or_function, preprocess_function=self.preprocess_function)
+ self.masks = generate_masks(input_timeseries, number_of_masks=self.n_masks, p_keep=self.p_keep)
+ masked = mask_data(input_timeseries, self.masks, mask_type=mask_type)
+
+ self.predictions = _make_predictions(masked, runner, batch_size)
+ n_labels = self.predictions.shape[1]
+
+ saliency = self.predictions.T.dot(self.masks.reshape(self.n_masks, -1)).reshape(n_labels,
+ *input_timeseries.shape)
+ selected_saliency = saliency[labels]
+ return normalize(selected_saliency, self.n_masks, self.p_keep)
diff --git a/dianna/utils/maskers.py b/dianna/utils/maskers.py
index bed4c9d7..56076736 100644
--- a/dianna/utils/maskers.py
+++ b/dianna/utils/maskers.py
@@ -1,4 +1,5 @@
import warnings
+from typing import Union
import numpy as np
@@ -17,21 +18,20 @@ def generate_masks(input_data: np.array, number_of_masks: int, p_keep: float = 0
number_of_steps_masked = _determine_number_of_steps_masked(p_keep, series_length)
masked_data_shape = [number_of_masks] + list(input_data.shape)
- masks = np.zeros(masked_data_shape, dtype=np.bool)
+ masks = np.ones(masked_data_shape, dtype=np.bool)
for i in range(number_of_masks):
steps_to_mask = np.random.choice(series_length, number_of_steps_masked, False)
- masked_value = 1
- masks[i, steps_to_mask] = masked_value
+ masks[i, steps_to_mask] = False
return masks
-def mask_data(data, masks, mask_type='mean'):
+def mask_data(data: np.array, masks: np.array, mask_type: Union[object, str]):
"""Mask data given using a set of masks.
Args:
- data: ?
+ data: Input data.
masks: an array with shape [number_of_masks] + data.shape
- mask_type: ?
+ mask_type: Masking strategy.
Returns:
Single array containing all masked input where the first dimension represents the batch.
@@ -39,13 +39,15 @@ def mask_data(data, masks, mask_type='mean'):
number_of_masks = masks.shape[0]
input_data_batch = np.repeat(np.expand_dims(data, 0), number_of_masks, axis=0)
result = np.empty(input_data_batch.shape)
- result[~masks] = input_data_batch[~masks]
- result[masks] = _get_mask_value(data, mask_type)
+ result[masks] = input_data_batch[masks]
+ result[~masks] = _get_mask_value(data, mask_type)
return result
def _get_mask_value(data: np.array, mask_type: str) -> int:
"""Calculates a masking value of the given type for the data."""
+ if callable(mask_type):
+ return mask_type(data)
if mask_type == 'mean':
return np.mean(data)
raise ValueError(f'Unknown mask_type selected: {mask_type}')
diff --git a/tests/methods/test_rise_timeseries.py b/tests/methods/test_rise_timeseries.py
new file mode 100644
index 00000000..d34800bc
--- /dev/null
+++ b/tests/methods/test_rise_timeseries.py
@@ -0,0 +1,37 @@
+import numpy as np
+import dianna
+from tests.methods.time_series_test_case import average_temperature_timeseries_with_1_cold_and_1_hot_day
+from tests.methods.time_series_test_case import input_train_mean
+from tests.methods.time_series_test_case import run_expert_model
+from tests.utils import run_model
+
+
+def test_rise_timeseries_correct_output_shape():
+ """Test if rise runs and outputs the correct shape given some data and a model function."""
+ input_data = np.random.random((10, 1))
+ axis_labels = ['t', 'channels']
+ labels = [1]
+
+ heatmaps = dianna.explain_timeseries(run_model, input_data, "RISE", labels, axis_labels=axis_labels,
+ n_masks=200, p_keep=.5)
+
+ assert heatmaps.shape == (len(labels), *input_data.shape)
+
+
+def test_rise_timeseries_with_expert_model_for_correct_max_and_min():
+ """Test if RISE highlights the correct areas for this artificial example."""
+ hot_day_index = 6
+ cold_day_index = 12
+ temperature_timeseries = average_temperature_timeseries_with_1_cold_and_1_hot_day(cold_day_index, hot_day_index)
+
+ summer_explanation, winter_explanation = dianna.explain_timeseries(run_expert_model,
+ timeseries_data=temperature_timeseries,
+ method='rise',
+ labels=[0, 1],
+ p_keep=0.1, n_masks=10000,
+ mask_type=input_train_mean)
+
+ assert np.argmax(summer_explanation) == hot_day_index
+ assert np.argmin(summer_explanation) == cold_day_index
+ assert np.argmax(winter_explanation) == cold_day_index
+ assert np.argmin(winter_explanation) == hot_day_index
diff --git a/tests/methods/time_series_test_case.py b/tests/methods/time_series_test_case.py
new file mode 100644
index 00000000..40e42e73
--- /dev/null
+++ b/tests/methods/time_series_test_case.py
@@ -0,0 +1,38 @@
+import numpy as np
+
+
+"""Test case for timeseries xai methods.
+This test case is designed to show if the xai methods could provide reasonable results.
+In this test case, every test instance is a 28 days by 1 channel array indicating the max temp on a day.
+"""
+
+
+def input_train_mean(_data):
+ """Return overall mean temperature of 14."""
+ return 14
+
+
+def average_temperature_timeseries_with_1_cold_and_1_hot_day(cold_day_index, hot_day_index):
+ """Creates a temperature time series of all 14s and a single cold (-2) and hot (30) day."""
+ temperature_timeseries = np.expand_dims(np.zeros(28), axis=1) + 14
+ temperature_timeseries[hot_day_index] = 30
+ temperature_timeseries[cold_day_index] = -2
+ return temperature_timeseries
+
+
+def run_expert_model(data):
+ """A simple model that classifies a batch of timeseries.
+
+ All instances with an average above 14 are classified as summer (0) and the rest as winter (1).
+ """
+ # Make actual decision
+ is_summer = np.mean(np.mean(data, axis=1), axis=1) > 14
+
+ # Create the correct output format
+ number_of_classes = 2
+ number_of_instances = data.shape[0]
+ result = np.zeros((number_of_instances, number_of_classes))
+ result[is_summer] = [1.0, 0.0]
+ result[~is_summer] = [0.0, 1.0]
+
+ return result
diff --git a/tests/test_common_usage.py b/tests/test_common_usage.py
index a143b6f7..5b5cc6e4 100644
--- a/tests/test_common_usage.py
+++ b/tests/test_common_usage.py
@@ -4,13 +4,29 @@
from tests.utils import run_model
-input_data = np.random.random((224, 224, 3))
-axis_labels = {-1: 'channels'}
-labels = [0, 1]
+def test_common_RISE_image_pipeline(): # noqa: N802 ignore case
+ """No errors thrown while creating a relevance map and visualizing it."""
+ input_image = np.random.random((224, 224, 3))
+ axis_labels = {-1: 'channels'}
+ labels = [0, 1]
+
+ heatmap = dianna.explain_image(run_model, input_image, "RISE", labels, axis_labels=axis_labels)[0]
+ dianna.visualization.plot_image(heatmap, show_plot=False)
+ dianna.visualization.plot_image(heatmap, original_data=input_image[0], show_plot=False)
-def test_common_RISE_pipeline(): # noqa: N802 ignore case
+def test_common_RISE_timeseries_pipeline(): # noqa: N802 ignore case
"""No errors thrown while creating a relevance map and visualizing it."""
- heatmap = dianna.explain_image(run_model, input_data, "RISE", labels, axis_labels=axis_labels)[0]
- dianna.visualization.plot_image(heatmap, show_plot=False)
- dianna.visualization.plot_image(heatmap, original_data=input_data[0], show_plot=False)
+ input_timeseries = np.random.random((31, 1))
+ labels = [0]
+
+ heatmap = dianna.explain_timeseries(run_model, input_timeseries, "RISE", labels)[0]
+ heatmap_channel = heatmap[:, 0]
+ segments = []
+ for i in range(len(heatmap_channel) - 1):
+ segments.append({
+ 'index': i,
+ 'start': i,
+ 'stop': i + 1,
+ 'weight': heatmap_channel[i]})
+ dianna.visualization.plot_timeseries(range(len(heatmap_channel)), input_timeseries[:, 0], segments, show_plot=False)
diff --git a/tutorials/models/season_prediction_model_temp_max_binary.onnx b/tutorials/models/season_prediction_model_temp_max_binary.onnx
new file mode 100644
index 00000000..f82b8f2c
Binary files /dev/null and b/tutorials/models/season_prediction_model_temp_max_binary.onnx differ
diff --git a/tutorials/rise_timeseries_weather.ipynb b/tutorials/rise_timeseries_weather.ipynb
new file mode 100644
index 00000000..be21dc1d
--- /dev/null
+++ b/tutorials/rise_timeseries_weather.ipynb
@@ -0,0 +1,1822 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "## Exploration of RISE for timeseries with weather dataset"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "This notebook shows how to use the RISE for timeseries explainer to explain trained onnx model with weather dataset."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {
+ "pycharm": {
+ "name": "#%% md\n"
+ }
+ },
+ "source": [
+ "### Load weather dataset"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {
+ "pycharm": {
+ "name": "#%%\n"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "import pandas as pd\n",
+ "import numpy as np\n",
+ "from sklearn.model_selection import train_test_split\n",
+ "import onnx\n",
+ "import onnxruntime as ort\n",
+ "import dianna\n",
+ "np.random.seed(0)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "outputs": [
+ {
+ "data": {
+ "text/plain": " DATE MONTH BASEL_cloud_cover BASEL_humidity \\\ncount 3.654000e+03 3654.000000 3654.000000 3654.000000 \nmean 2.004568e+07 6.520799 5.418446 0.745107 \nstd 2.874287e+04 3.450083 2.325497 0.107788 \nmin 2.000010e+07 1.000000 0.000000 0.380000 \n25% 2.002070e+07 4.000000 4.000000 0.670000 \n50% 2.004567e+07 7.000000 6.000000 0.760000 \n75% 2.007070e+07 10.000000 7.000000 0.830000 \nmax 2.010010e+07 12.000000 8.000000 0.980000 \n\n BASEL_pressure BASEL_global_radiation BASEL_precipitation \\\ncount 3654.000000 3654.000000 3654.000000 \nmean 1.017876 1.330380 0.234849 \nstd 0.007962 0.935348 0.536267 \nmin 0.985600 0.050000 0.000000 \n25% 1.013300 0.530000 0.000000 \n50% 1.017700 1.110000 0.000000 \n75% 1.022700 2.060000 0.210000 \nmax 1.040800 3.550000 7.570000 \n\n BASEL_sunshine BASEL_temp_mean BASEL_temp_min ... \\\ncount 3654.000000 3654.000000 3654.000000 ... \nmean 4.661193 11.022797 6.989135 ... \nstd 4.330112 7.414754 6.653356 ... \nmin 0.000000 -9.300000 -16.000000 ... \n25% 0.500000 5.300000 2.000000 ... \n50% 3.600000 11.400000 7.300000 ... \n75% 8.000000 16.900000 12.400000 ... \nmax 15.300000 29.000000 20.800000 ... \n\n STOCKHOLM_temp_min STOCKHOLM_temp_max TOURS_wind_speed \\\ncount 3654.000000 3654.000000 3654.000000 \nmean 5.104215 11.470635 3.677258 \nstd 7.250744 8.950217 1.519866 \nmin -19.700000 -14.500000 0.700000 \n25% 0.000000 4.100000 2.600000 \n50% 5.000000 11.000000 3.400000 \n75% 11.200000 19.000000 4.600000 \nmax 21.200000 32.900000 10.800000 \n\n TOURS_humidity TOURS_pressure TOURS_global_radiation \\\ncount 3654.000000 3654.000000 3654.000000 \nmean 0.781872 1.016639 1.369787 \nstd 0.115572 0.018885 0.926472 \nmin 0.330000 0.000300 0.050000 \n25% 0.700000 1.012100 0.550000 \n50% 0.800000 1.017300 1.235000 \n75% 0.870000 1.022200 2.090000 \nmax 1.000000 1.041400 3.560000 \n\n TOURS_precipitation TOURS_temp_mean TOURS_temp_min TOURS_temp_max \ncount 3654.000000 3654.000000 3654.000000 3654.000000 \nmean 0.186100 12.205802 7.860536 16.551779 \nstd 0.422151 6.467155 5.692256 7.714924 \nmin 0.000000 -6.200000 -13.000000 -3.100000 \n25% 0.000000 7.600000 3.700000 10.800000 \n50% 0.000000 12.300000 8.300000 16.600000 \n75% 0.160000 17.200000 12.300000 22.400000 \nmax 6.200000 31.200000 22.600000 39.800000 \n\n[8 rows x 165 columns]",
+ "text/html": "\n\n
\n \n \n | \n DATE | \n MONTH | \n BASEL_cloud_cover | \n BASEL_humidity | \n BASEL_pressure | \n BASEL_global_radiation | \n BASEL_precipitation | \n BASEL_sunshine | \n BASEL_temp_mean | \n BASEL_temp_min | \n ... | \n STOCKHOLM_temp_min | \n STOCKHOLM_temp_max | \n TOURS_wind_speed | \n TOURS_humidity | \n TOURS_pressure | \n TOURS_global_radiation | \n TOURS_precipitation | \n TOURS_temp_mean | \n TOURS_temp_min | \n TOURS_temp_max | \n
\n \n \n \n | count | \n 3.654000e+03 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n ... | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n 3654.000000 | \n
\n \n | mean | \n 2.004568e+07 | \n 6.520799 | \n 5.418446 | \n 0.745107 | \n 1.017876 | \n 1.330380 | \n 0.234849 | \n 4.661193 | \n 11.022797 | \n 6.989135 | \n ... | \n 5.104215 | \n 11.470635 | \n 3.677258 | \n 0.781872 | \n 1.016639 | \n 1.369787 | \n 0.186100 | \n 12.205802 | \n 7.860536 | \n 16.551779 | \n
\n \n | std | \n 2.874287e+04 | \n 3.450083 | \n 2.325497 | \n 0.107788 | \n 0.007962 | \n 0.935348 | \n 0.536267 | \n 4.330112 | \n 7.414754 | \n 6.653356 | \n ... | \n 7.250744 | \n 8.950217 | \n 1.519866 | \n 0.115572 | \n 0.018885 | \n 0.926472 | \n 0.422151 | \n 6.467155 | \n 5.692256 | \n 7.714924 | \n
\n \n | min | \n 2.000010e+07 | \n 1.000000 | \n 0.000000 | \n 0.380000 | \n 0.985600 | \n 0.050000 | \n 0.000000 | \n 0.000000 | \n -9.300000 | \n -16.000000 | \n ... | \n -19.700000 | \n -14.500000 | \n 0.700000 | \n 0.330000 | \n 0.000300 | \n 0.050000 | \n 0.000000 | \n -6.200000 | \n -13.000000 | \n -3.100000 | \n
\n \n | 25% | \n 2.002070e+07 | \n 4.000000 | \n 4.000000 | \n 0.670000 | \n 1.013300 | \n 0.530000 | \n 0.000000 | \n 0.500000 | \n 5.300000 | \n 2.000000 | \n ... | \n 0.000000 | \n 4.100000 | \n 2.600000 | \n 0.700000 | \n 1.012100 | \n 0.550000 | \n 0.000000 | \n 7.600000 | \n 3.700000 | \n 10.800000 | \n
\n \n | 50% | \n 2.004567e+07 | \n 7.000000 | \n 6.000000 | \n 0.760000 | \n 1.017700 | \n 1.110000 | \n 0.000000 | \n 3.600000 | \n 11.400000 | \n 7.300000 | \n ... | \n 5.000000 | \n 11.000000 | \n 3.400000 | \n 0.800000 | \n 1.017300 | \n 1.235000 | \n 0.000000 | \n 12.300000 | \n 8.300000 | \n 16.600000 | \n
\n \n | 75% | \n 2.007070e+07 | \n 10.000000 | \n 7.000000 | \n 0.830000 | \n 1.022700 | \n 2.060000 | \n 0.210000 | \n 8.000000 | \n 16.900000 | \n 12.400000 | \n ... | \n 11.200000 | \n 19.000000 | \n 4.600000 | \n 0.870000 | \n 1.022200 | \n 2.090000 | \n 0.160000 | \n 17.200000 | \n 12.300000 | \n 22.400000 | \n
\n \n | max | \n 2.010010e+07 | \n 12.000000 | \n 8.000000 | \n 0.980000 | \n 1.040800 | \n 3.550000 | \n 7.570000 | \n 15.300000 | \n 29.000000 | \n 20.800000 | \n ... | \n 21.200000 | \n 32.900000 | \n 10.800000 | \n 1.000000 | \n 1.041400 | \n 3.560000 | \n 6.200000 | \n 31.200000 | \n 22.600000 | \n 39.800000 | \n
\n \n
\n
8 rows × 165 columns
\n
\n\n
\n \n \n | \n DE_BILT_temp_max | \n
\n \n \n \n | count | \n 3654.000000 | \n
\n \n | mean | \n 14.798604 | \n
\n \n | std | \n 7.210740 | \n
\n \n | min | \n -4.700000 | \n
\n \n | 25% | \n 9.200000 | \n
\n \n | 50% | \n 14.900000 | \n
\n \n | 75% | \n 20.200000 | \n
\n \n | max | \n 35.700000 | \n
\n \n
\n
\n\n
\n \n \n | \n 0 | \n 1 | \n 2 | \n 3 | \n
\n \n \n \n | count | \n 120.000000 | \n 120.000000 | \n 120.000000 | \n 120.000000 | \n
\n \n | mean | \n 0.250000 | \n 0.250000 | \n 0.250000 | \n 0.250000 | \n
\n \n | std | \n 0.434828 | \n 0.434828 | \n 0.434828 | \n 0.434828 | \n
\n \n | min | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n
\n \n | 25% | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n
\n \n | 50% | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n 0.000000 | \n
\n \n | 75% | \n 0.250000 | \n 0.250000 | \n 0.250000 | \n 0.250000 | \n
\n \n | max | \n 1.000000 | \n 1.000000 | \n 1.000000 | \n 1.000000 | \n
\n \n
\n