DCAM

<p align="center"> <img width="190" src="./ressources/dCAM_logo.png"/> </p> <h1 align="center">dCAM</h1> <h2 align="center">Dimension-wise Class Activation Map for Explaining Multivariate Time Series Classification</h2> <div align="center"> <p> <img alt="GitHub" src="https://img.shields.io/github/license/boniolp/dcam"> <img alt="GitHub issues" src="https://img.shields.io/github/issues/boniolp/dcam"> </p> </div>

Abstract

Data series classification is an important and challenging problem in data science. Explaining the classification decisions by finding the discriminant parts of the input that led the algorithm to some decision is a real need in many applications. Convolutional neural networks perform well for the data series classification task; though,the explanations provided by this type of algorithms are poor for the specific case of multivariate data series. Solving this important limitation is a significant challenge. We propose a novel method that addresses the above challenge by highlighting both the temporal and dimensional discriminant information. Our contribution is two-fold: we first describe a new convolutional architecture that enables the comparison of dimensions; then, we propose a novel method that returns dCAM, a Dimension-wise ClassActivation Map specifically designed for multivariate time series.

<p align="center"> <img src="ressources/intro_figure.png" alt="drawing" width="400"/> </p>

This repository is dedicated to our paper titled "dCAM : Dimension-wise Class Activation Map for Explaining Multivariate Time Series Classification" published in the Proceedings of the 2022 International Conference on Management of Data also available on here.

dCAM in Practice:

Here are interesting papers that use dCAM.

• Linhao Fan et al. An Explainable Machine Learning Based Flashover Prediction Model Using Dimension-Wise Class Activation Map, Fire Safety Journal, 2023

Data

The data used in this project comes from two sources:

• The UCR/UEA archive. Informations are provided in the data folder in order to download our datasets.

Code

The code is divided as follows:

• The src/ folder that contains:

  • CNN_models.py:

    • CNN architecture (class ConvNet)
    • dCNN/cCNN architecture (class ConvNet2D)
    • ResNet architecture (class ResNet)
    • dResNet/cResNet architecture (class dResNet)
    • Inception Time architecture (class inceptiontime)
    • dInception Time/cInception Time architecture (class dinceptiontime)
    • CNN-MTEX architecture (class ConvNetMTEX)

  • RNN_models.py:

    • LSTM architecture (class LSTMClassifier)
    • RNN architecture (class RNNClassifier)
    • GRU architecture (class GRUClassifier)

  • the explanation/ folder:

    • CAM code (class CAM)
    • cCAM code (class cCAM)
    • dCAM code (class DCAM)
    • grad-CAM code used for CNN-MTEX (class GradCAM)

• The examples/ folder that contains:

  • Synthetic_experiment-CAM.ipynb: An example on how to use CNN-based models and the Class Activation Map.
  • Synthetic_experiment_DCAM.ipynb: An example on how to use dCNN-based models and the dCAM.

• The experiments/ folder that contains:

  • classification/: scripts in order to reproduce our classification results.
  • explanation/: scripts in order to reproduce our explanation results.
  • execution_time/: scripts in order to reproduce our execution_time results.

• Results_overview.ipynb: Notebook containing all the informations and the procedures to run the experiments/ scripts and generate the figures in our paper.

Prerequisites

First, to download the datasets (unzip and move the content in the corresponding folder), please run the following commands:

• Go to the following folder:

cd data/UCR_UEA

• Download and unzip the following archive:

https://helios2.mi.parisdescartes.fr/~themisp/dCAM/data/UCR_UEA_datasets.zip

• Then, go to the following folder:

cd data/synthetic

• Download and unzip the following archive:

https://helios2.mi.parisdescartes.fr/~themisp/dCAM/data/Synthetic_datasets.zip

Python environment management with uv

We recommend using uv to manage the Python environment defined in pyproject.toml/uv.lock.

# Install uv if you do not already have it
curl -Ls https://astral.sh/uv/install.sh | sh

# Create a .venv/
uv venv

# Install the project into a virtual environment (created at .venv/)
uv sync

# Activate the environment when you want to work on the project
source .venv/bin/activate

Once the environment is active you can launch notebooks or scripts with uv run <command> (for example uv run jupyter notebook).

Alternative: pip

All python packages needed are listed in requirements.txt and can be installed simply using the pip command:

pip install -r requirements_version.txt

If the versions are not compatible in your environement, please run the following command:

pip install -r requirements.txt

Jupyter notebook should be installed. To do so, please run the following command:

pip install notebook

Overall, the required python packages are listed as follows:

• numpy
• pandas
• sklearn
• pytorch
• tqdm
• matplotlib (For the jupyter notebooks only)
• torchsummary (For the jupyter notebooks only)
• scipy (For the jupyter notebooks only)

Reference

If you re-use this work, please cite:

@inproceedings{DBLP:conf/sigmod/BoniolMRP22,
  author    = {Paul Boniol and
               Mohammed Meftah and
               Emmanuel Remy and
               Themis Palpanas},
  editor    = {Zachary Ives and
               Angela Bonifati and
               Amr El Abbadi},
  title     = {dCAM: Dimension-wise Class Activation Map for Explaining Multivariate
               Data Series Classification},
  booktitle = {{SIGMOD} '22: International Conference on Management of Data, Philadelphia,
               PA, USA, June 12 - 17, 2022},
  pages     = {1175--1189},
  publisher = {{ACM}},
  year      = {2022},
  url       = {https://doi.org/10.1145/3514221.3526183},
  doi       = {10.1145/3514221.3526183},
  timestamp = {Tue, 14 Jun 2022 18:31:24 +0200},
  biburl    = {https://dblp.org/rec/conf/sigmod/BoniolMRP22.bib},
  bibsource = {dblp computer science bibliography, https://dblp.org}
}