Source code of TSAP: Time-Series Additive exPlanations, a novel explainer based on time-series transformations
Description
This dataset contains the complete Python source code of Time-Series Additive exPlanations (TSAP), a novel model-agnostic explainer designed for time-series (TS) machine learning (ML) models. TSAP is based on measuring the impact of controlled TS transformations on the predicted output of forecasting models. The core component of the framework is the class "TsapExplainer", which can be applied to any TS ML model implementing the basic interface "TsModel" (provided as a Python class). The only required method is "predict", which receives a Pandas Series as input and returns a numerical value corresponding to the predicted next value of the series. This design enables compatibility with external ML libraries such as Keras or TensorFlow by implementing a lightweight wrapper class that conforms to the "TsModel" interface and defines the required method. To illustrate the usage of TSAP, this dataset includes the class "LstmExampleTsModel", which implements a Long Short-Term Memory (LSTM) neural network using Keras. This example retrieves stock time-series data through the Yahoo Finance application programming interface (API) and demonstrates how to integrate TSAP with a forecasting model in practice. TSAP supports both local and global explanations. Local explanations analyze the influence of TS transformations on a single prediction, while global explanations characterize the overall behavior of a model based on a group of TS instances. Additional classes and scripts included in the dataset are used for experimentation in the financial domain and for evaluating the explainer using Gummadi’s metrics. These materials were prepared to support the peer-review process of a scientific publication. Although the current version of TSAP includes default transformations related to trend and volatility, the framework is fully extensible. The explainer can receive custom transformation functions as parameters, allowing practitioners to define domain-specific transformations and generate explanations tailored to their particular TS ML models. Researchers and practitioners are encouraged to cite the associated publications and this dataset when using TSAP in academic or professional work.
Files
Steps to reproduce
After downloading the dataset, unzip the folder named "tsap" and place it in any directory of your system. When running the example experiments, the class "LstmExampleTsModel" will automatically create two folders in the parent folder: "Cache" and "Models". The folder "Cache" stores Yahoo Finance data locally in order to avoid exceeding API rate limits, and the folder "Models" stores trained LSTM models to prevent retraining under identical experimental conditions. Example experiments can be executed by running the main sections located under ‘if name == "main":’ in the files "CaseStudyStock.py", "LstmExampleTsModel.py", and "GummadiEvaluation.py". Some experimental configurations can be modified by uncommenting specific lines of code within these files. Users can also import the classes "TsapExplainer" and "TsModel" into their own projects to apply TSAP to custom TS ML models, provided that the required "predict" method is implemented according to the interface specification.
Institutions
- Universidad Complutense de MadridMadrid, Madrid