Metadata-Version: 2.1
Name: tgcnn_act_graph
Version: 0.2
Description-Content-Type: text/markdown
License-File: LICENSE.txt

# Create Activation Graphs for TG-CNN Model


![Tests](https://github.com/ZoeHancox/tgcnn_activation_graphs/actions/workflows/tests.yml/badge.svg)

Produce graphs using the 3D CNN layers from the trained TG-CNN model. These graphs show which edges or timesteps are the most important during model prediction. 


## Activation mapping graphs for edges steps:

* Get the patient 'graph'
* Get the filter with the strongest differentiation of maximum activation
* Do element-wise multiplication between the filter and the patient graph
* Make the edges with zero activation grey
    * Where an edge is the x and y for each timestep.
    * A node is a new node even if the node has already been visited.
    * Nodes can be named e.g. r5_t1 (read code = 5, timestep = 1)
    * Use the element-wise ('activation') result to colour the edges red if the connection isn't zero.
    
Limitations:
* This method requires there to be no overlap in the CNN windows.

---

The equations of how maximum activation is calculated is as follows:

To get the edge weights: For a given filter $f_{k}$, patient $p$, and time step $i$, the process can be summarised as:

1. Extract the slice:

   $
   W_{i}^{(p, k)} = G_{p}[i:i+F, :, :],
   $
   
   where $F$ is the size of the filter in the time dimension, $G_{p}$ as the input tensor for patient $p$, $f_{k}$ as the $k$-th filter, and $W_{i}^{(p, k)}$ is the slice of the tensor $G_{p}$ at time step $i$ with the same dimensions as the filter $f_{k}$.

2. Apply the filter and sum the result:
   
   $
   S_{i}^{(p, k)} = \sum (W_{i}^{(p, k)} \odot f_{k}),
   $

   where $\odot$ denotes element-wise multiplication.

3. Apply the leaky ReLU activation function:
   
   $
   A_{i}^{(p, k)} = leaky ReLU(S_{i}^{(p, k)}, \alpha),
   $

    where $\alpha$ is the leaky ReLU parameter.

4. Compute the maximum activation value across all time steps:
   
   $
   \text{max\_activation\_value}_{p, k} = \max_{i} (A_{i}^{(p, k)})
   $

5. Combine these into one formula:

    $
    Max Activation Value_{p, k} = \max_{i} \left( leaky ReLU \left( \sum (G_{p}[i:i+F, :, :] \odot f_{k}), \alpha \right) \right)
    $


## USAGE

See examples in `create_graphs.ipynb` for how to use this code.

## ROADMAP

See the [Issues](https://github.com/ZoeHancox/tgcnn_activation_graphs/issues) in GitHub for a list of proposed features and known issues.


## TESTING

Run tests by using `pytest test_graphs/test_calculations.py` in the top directory.

## LICENSE

Unless stated otherwise, the codebase is released under the BSD Licence. This covers both the codebase and any sample code in the documentation.

See [LICENCE](https://github.com/ZoeHancox/tgcnn_activation_graphs/blob/main/LICENSE.txt) for more information.

## ACKNOWLEDGEMENTS
