Juelich 2024

README.md

@@ -7,8 +7,8 @@
 # Tutorials for eXplainable Artificial Intelligence (XAI) methods
 
 This repository contains a collection of self-explanatory tutorials for different model-agnostic and model-specific XAI methods.
-Each tutorial comes in a Jupyter Notebook containing a short video lecture and practical exercises.
-The material has already been used in the context of two courses: the Zero to Hero Summer Academy (fully online) and ml4hearth (hybrid setting).
+Each tutorial comes in a Jupyter Notebook, containing a short video lecture and practical exercises.
+The material has already been used in the context of two courses: the Helmholtz Summer Academy 2022 and 2023 (fully online) and ml4hearth (hybrid setting), MALTAomics Summer School (hybrid setting).
 The course material can be adjusted according to the available time frame and the schedule.
 The material is self-explanatory and can also be consumed offline.
 
@@ -17,23 +17,81 @@ The learning objectives are:
 - understand the importance of interpretability
 - discover the existing model-agnostic and model-specific XAI methods
 - learn how to interpret the outputs and graphs of those methods with hands-on exercises
-- learn to choose which method is suitable for a specific task
+- learn to chose which method is suitable for a specific task
 
-## List of Tutorials for Model-Agnostic Methods
+## Venue
+The course will be fully online:
+*Add zoom link*
 
-- Permutation Feature Importance
-- SHapley Additive exPlanations (SHAP)
-- Local Interpretable Model-Agnostic Explanations (LIME)
+Link to the share notes: https://notes.desy.de/HAmuRdemQgK8VW9mqjBBPQ?both
 
-## List of Tutorials for Model-Specific Methods
+## Schedule at a glance
 
-- Forest-Guided Clustering
-- Grad-CAM
+#### Day 1 - XAI for Random Forest
+|  Time | Session  | Duration  |
+|---|---|---|
+|9:00 - 9:30 |Introduction |30 min|
+|9:30 - 10:15 |	Permutation Feature Importance|	45 min|
+|10:15 - 10:30 | Break|	15 min|
+| 10:30 - 11:30 | SHAP | 1 h| 
+|11:30 - 11:45 | Break|	10 min|
+|11:45- 12:15 |	LIME | 30 min|
+|12:15 - 12:55 | FGC |40 min|
+|12:55 - 13:00 | Conclusions |5 min|
 
-## Requirements and Setup
+Homework 1: Comparison notebook - [Tutorial_XAI_for_RandomForest](https://github.com/HelmholtzAI-Consultants-Munich/XAI-Tutorials/blob/Juelich-2024/xai-for-tabular-data/Tutorial_XAI_for_RandomForests.ipynb)
+
+Homework 2: SHAP exercise - [Compute Shapley values by hand](https://github.com/HelmholtzAI-Consultants-Munich/XAI-Tutorials/blob/Juelich-2024/SHAP_exercise.pdf)
+
+
+#### Day 2 - XAI for CNNs
+|  Time | Session  | Duration  |
+|---|---|---|
+|9:00 - 9:15 | Welcome |15 min|
+|9:15 - 9:30 |	Homework Discussion| 15 min|
+|9:30 - 10:00 | Intro CNNs|	30 min|
+|10:00 - 10:15 | Break | 15 min| 
+|10:15 - 11:05 | Grad-CAM for Images| 50 min|
+|11:05- 11:45 |	 Grad-CAM for Signals | 40 min|
+|11:45 - 12:00 | Break | 15 min| 
+|12:00 - 12:30 | LIME for Images | 30 min|
+|12:30 - 12:55| SHAP for Images | 25 min |
+|12:55 - 13:00 | Conclusions |5 min|
+
+Homework 1: Comparison notebook - [Tutorial_XAI_for_ImageAnalysis](https://github.com/HelmholtzAI-Consultants-Munich/XAI-Tutorials/blob/Juelich-2024/xai-for-image-data/Tutorial_XAI_for_ImageAnalysis.ipynb)
+
+
+#### Day 3 - XAI for Transformers
+|  Time | Session  | Duration  |
+|---|---|---|
+|9:00 - 9:15 |Welcome |15 min|
+|9:15 - 9:30 |	Homework Discussion| 15 min|
+|9:30 - 10:15 | Intro to trasformers | 45 min|
+|10:15 - 10:30 | Break | 15 min| 
+|10:30 - 11:00 | Attention for text | 45 min|
+|11:00 - 11:30 | Intro to Vision Transformers | 30 min|
+|11:30 - 11:45 | Break | 15 min| 
+|11:45 - 12:45 | Attention map for image transformers | 60 min|
+|12:45 - 13:00 | Conclusions & Survey | 15 min|
+
+
+## Requirements and Setup - *Check this section*
 
 It is possible to either create an environment and install all the necessary packages locally (using the requirements.txt file) or to execute the notebooks on the browser, by clicking the 'Open in Colab' button. This second option doesn't require any further installation, but the user must have access to a Google account.
 
+If you prefer to run the notebooks on your device, create a virtual environment using the requirements.txt file:
+```
+conda create -n XAI-Course-2024 python=3.9
+conda activate XAI-Course-2024
+pip install -r requirements.txt
+```
+
+Once your environment is created, clone `Juelich-2024` brach branch of the repo using the following command:
+
+```
+git clone --branch Juelich-2024 https://github.com/HelmholtzAI-Consultants-Munich/XAI-Tutorials.git
+```
+
 ## Contributions
 
 Comments and input are very welcome! If you have a suggestion or think something should be changed, please open an issue or submit a pull request. 

data_and_models/ECG/ECG.py

@@ -0,0 +1,23 @@
+#%%
+import torch
+import torch.utils.data as data
+import pandas as pd 
+import numpy as np
+
+class ECG(data.Dataset):
+    def __init__(self, data):
+        self.data = pd.read_csv(data, sep=',', header=None)
+        self.samples = self.data.iloc[:, :187]
+        self.targets = self.data[187].to_numpy()
+
+
+    def __getitem__(self, index):
+        x = self.samples.iloc[index, :]
+        x = torch.from_numpy(x.values).float()
+        x = torch.unsqueeze(x, 0)
+        y = self.targets[index].astype(np.int64)
+        return x, y
+
+    def __len__(self):
+        return len(self.data)
+

data_and_models/ECG/ResNet1D.py

@@ -0,0 +1,93 @@
+#%%
+import torch
+import torch.nn as nn
+
+class ResNetBlock(nn.Module):
+    def __init__(self, in_channels, out_channels, stride=1):
+        super(ResNetBlock, self).__init__()
+        self.conv1 = nn.Conv1d(in_channels, out_channels, kernel_size=3, stride=stride, padding=1, bias=False)
+        self.bn1 = nn.BatchNorm1d(out_channels)
+        self.relu = nn.ReLU(inplace=True)
+        self.conv2 = nn.Conv1d(out_channels, out_channels, kernel_size=3, stride=1, padding=1, bias=False)
+        self.bn2 = nn.BatchNorm1d(out_channels)
+        self.stride = stride
+
+        self.shortcut = nn.Sequential()
+        if stride != 1 or in_channels != out_channels:
+            self.shortcut = nn.Sequential(
+                nn.Conv1d(in_channels, out_channels, kernel_size=1, stride=stride, bias=False),
+                nn.BatchNorm1d(out_channels)
+            )
+
+    def forward(self, x):
+        residual = x
+
+        out = self.conv1(x)
+        out = self.bn1(out)
+        out = self.relu(out)
+
+        out = self.conv2(out)
+        out = self.bn2(out)
+
+        out += self.shortcut(residual)
+        out = self.relu(out)
+
+        return out
+
+class ResNet(nn.Module):
+    def __init__(self, block, layers, num_classes=10):
+        super(ResNet, self).__init__()
+        self.in_channels = 64
+
+        self.conv1 = nn.Conv1d(1, 64, kernel_size=3, stride=1, padding=1, bias=False)
+        self.bn1 = nn.BatchNorm1d(64)
+        self.relu = nn.ReLU(inplace=True)
+        self.layer1 = self.make_layer(block, 64, layers[0])
+        self.layer2 = self.make_layer(block, 128, layers[1], stride=2)
+        self.layer3 = self.make_layer(block, 256, layers[2], stride=2)
+        self.layer4 = self.make_layer(block, 512, layers[3], stride=2)
+        self.avg_pool = nn.AdaptiveAvgPool1d((1,))
+        self.fc = nn.Linear(512, num_classes)
+        self.gradient = None
+
+    def make_layer(self, block, out_channels, blocks, stride=1):
+        layers = []
+        layers.append(block(self.in_channels, out_channels, stride))
+        self.in_channels = out_channels
+        for i in range(1, blocks):
+            layers.append(block(out_channels, out_channels))
+        return nn.Sequential(*layers)
+
+    # hook for the gradients
+    def activations_hook(self, grad):
+        self.gradient = grad
+
+    def get_gradient(self):
+        return self.gradient
+
+    def get_activations(self, x):
+        return self.features(x)
+
+    def forward(self, x, label=None, return_cam=False):
+        x = self.conv1(x)
+        x = self.bn1(x)
+        x = self.relu(x)
+
+        x = self.layer1(x)
+        x = self.layer2(x)
+        x = self.layer3(x)
+        x = self.layer4(x)
+        x.register_hook(self.activations_hook)
+
+        pre_logits = self.avg_pool(x)
+        pre_logits = torch.flatten(pre_logits, 1)
+        logits = self.fc(pre_logits)
+
+        if return_cam:
+            feature_map = x.detach().clone()
+            cam_weights = self.fc.weight[label]
+            cams = (cam_weights.view(*feature_map.shape[:2], 1) *
+            feature_map).mean(1, keepdim=False)
+            return logits, cams
+
+        return logits, x

data_and_models/ECG/main.py

@@ -0,0 +1,110 @@
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.tensorboard import SummaryWriter
+from torch.utils.data import DataLoader
+
+from ResNet1D import ResNet, ResNetBlock
+from ECG import ECG
+
+
+
+def training_loop(model, train_loader, criterion, optimizer, num_epochs, writer, device):
+
+    for epoch in range(num_epochs):
+        running_loss = 0.0
+        for i, data in enumerate(train_loader, 0):
+            inputs, labels = data
+            optimizer.zero_grad()
+            outputs = model(inputs.to(device))
+            loss = criterion(outputs[0], labels.to(device))
+            loss.backward()
+            optimizer.step()
+            running_loss += loss.item()
+            if i % 2000 == 1999:
+                print('[%d, %5d] loss: %.3f' %
+                    (epoch + 1, i + 1, running_loss / 2000))
+
+        torch.save(model.state_dict(), 'weights/model_weights'+str(epoch)+'.pth')
+
+        writer.add_scalar('training loss', running_loss/len(train_loader), epoch)
+
+    torch.save(model.state_dict(), 'weights/model_final_weights_ecg.pth')
+
+def inference_loop(model, test_loader, criterion):
+
+
+    model.eval()
+
+    device = next(model.parameters()).device
+    true_positives = [0] * 5
+    false_positives = [0] * 5
+    false_negatives = [0] * 5
+    true_negatives = [0] * 5
+    total_loss = 0
+    total_samples = 0
+
+    with torch.no_grad():
+        for inputs, targets in test_loader:
+            targets = targets.to(device)
+            inputs = inputs.to(device)
+            outputs = model(inputs)
+            outputs = outputs[0]
+
+            loss = criterion(outputs, targets)
+
+            total_loss += loss.item()
+            total_samples += inputs.size(0)
+            _, predictions = torch.max(outputs, -1)
+
+            for i in range(5):
+
+                true_positives[i] += ((predictions == i) & (targets == i)).sum().item()
+                false_positives[i] += ((predictions == i) & (targets != i)).sum().item()
+                false_negatives[i] += ((predictions != i) & (targets == i)).sum().item()
+                true_negatives[i] += ((predictions != i) & (targets != i)).sum().item()
+
+    accuracy = (sum(true_positives) + sum(true_negatives)) / (sum(true_positives) + sum(false_positives) + sum(false_negatives) + sum(true_negatives))
+    recall = [true_positives[i] / (true_positives[i] + false_negatives[i]) if true_positives[i] + false_negatives[i] > 0 else 0 for i in range(5)]
+    precision = [true_positives[i] / (true_positives[i] + false_positives[i]) if true_positives[i] + false_positives[i] > 0 else 0 for i in range(5)]
+    f1 = [2 * precision[i] * recall[i] / (precision[i] + recall[i]) if precision[i] + recall[i] > 0 else 0 for i in range(5)]
+    average_loss = total_loss / total_samples
+
+    return accuracy, recall, precision, f1, average_loss
+
+
+if __name__ == "__main__":
+
+    model_weights_path = 'weights/model_final_weights_ecg.pth'
+    train_data_path = 'data/Dataset_ECG/mitbih_train.csv'
+    test_data_path = 'data/Dataset_ECG/mitbih_test.csv'
+    num_epochs = 10
+
+    device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
+
+    model = ResNet(ResNetBlock, [2, 2, 2, 2], num_classes=5)
+    model = model.to(device)
+
+    criterion = nn.CrossEntropyLoss()
+    optimizer = optim.SGD(model.parameters(), lr=0.001, momentum=0.9)
+
+    ecg = ECG(train_data_path)
+    train_loader = DataLoader(ecg, batch_size=64, shuffle=True, num_workers=4)
+
+    ecg = ECG(test_data_path)
+    test_loader = DataLoader(ecg, batch_size=64, shuffle=True, num_workers=4)
+
+    writer = SummaryWriter()
+
+    # training_loop(model, train_loader, criterion, optimizer, num_epochs, writer, device)
+
+    model.load_state_dict(torch.load(model_weights_path))
+
+    accuracy, recall, precision, f1, average_loss = inference_loop(model, test_loader, criterion)
+
+    print("Accuracy: ", accuracy)
+    print("Recall: ", recall)
+    print("Precision: ", precision)
+    print("F1: ", f1)
+    print("Average loss: ", average_loss)
+