# gabrielelozupone/axial architecture

> Architecture diagram of the GitHub repository gabrielelozupone/axial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gabrielelozupone/axial
- Repository: https://github.com/gabrielelozupone/axial

## Overview

##### Project type and purpose
- This is a specialized open-source deep learning framework for Alzheimer's disease diagnosis using 3D MRI scans.
- It handles data ingestion (ADNI → BIDS), preprocessing (bias correction, registration, brain extraction), model training (2D CNNs with slice-level attention and majority voting), and explainability (attention maps and GradCAM).

##### File structure
- Top-level scripts:
- data_preprocessing.py – runs the preprocessing pipeline with Clinica and creates dataset CSVs
- train.py – orchestrates 5-fold training and evaluation using config.yaml
- attention_xai_analysis.py – generates attention-based XAI metrics and visualizations
- cam_xai_analysis.py – generates GradCAM-based XAI metrics and visualizations
- Key directories under src:
- config – contains argparse and YAML configuration loaders
- data – implements dataset loading, splitting, transforms, DataLoader wrappers
- models – implements various architectures (Axial3D, AwareNet, transformers, majority voting) and metrics
- explainability – houses attention and CAM utility functions
- logger – encapsulates TensorBoard logging
- mynn – helper functions for optimizers, schedulers, positional encoding, transformer blocks
- Auxiliary files:
- config.yaml – central hyperparameter and path definitions
- template – stores brain template NIfTI files used to overlay XAI maps
- requirements.txt, LICENSE, README.md

##### Extract architecture from README
- Data flow: ADNI raw data + clinical CSVs → Clinica (ADNI-to-BIDS) → data_preprocessing → preprocessed images + dataset.csv
- Training: train.py reads dataset.csv, builds models, runs 5-fold CV, logs to TensorBoard
- Explainability: post-training, attention_xai_analysis.py and cam_xai_analysis.py read saved models and attention/CAM weights, compute cross-fold statistics, overlay on template

##### Main components
a. Data Ingestion & Preparation
- External Service: Clinica converter (ADNI → BIDS)
- Raw Data: ADNI images, clinical CSVs
b. Preprocessing Pipeline
- Script: data_preprocessing.py
- Modules: src/data (dataloader, transforms, split_data), template files
- Output: preprocessed NIfTI images + dataset.csv, dataset_conversionX.csv
c. Training & Evaluation
- Script: train.py
- Config: config.yaml + src/config loaders
- Modules: src/models (Axial3D, AwareNet, transformer3D, majority voting), src/mynn
- Logger: src/logger/TensorBoardWriter
- Output: model checkpoints, fold results, overall metrics
d. Explainability
- Attention XAI: attention_xai_analysis.py → src/explainability/attention/utils
- CAM XAI: cam_xai_analysis.py → src/explainability/cam/utils
- Outputs: voxel-level attention maps, GradCAM maps, regional statistics tables
e. Storage & Visualization
- Results CSVs, Figure outputs under readme_files, TensorBoard dashboard

##### Architectural patterns & design principles
- Modular separation: preprocessing, training, explainability modules reside in separate scripts and src subpackages
- Config-driven: YAML + argparse for reproducibility and easy hyperparameter tuning
- Pipeline orchestration: single scripts orchestrate multi-step processes (data_prep → training → XAI)
- Extension points: src/models allows plugging in new architectures; src/explainability supports adding new XAI methods

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        RawData["ADNI Raw Data & Clinical CSVs"]:::data
        Clinica["Clinica Converter"]:::external
        RawData -->|".tar, .nii, .csv"| Clinica
        DP["Preprocessing Script\ndata_preprocessing.py"]:::data
        Clinica --> DP
        click DP "https://github.com/gabrielelozupone/axial/blob/main/data_preprocessing.py"
        subgraph "src/data" 
            direction TB
            DF["dataframe_loader.py"]:::data
            DL["dataloader.py"]:::data
            DS1["dataset.py"]:::data
            DS2["dataset_2d.py"]:::data
            SD["split_data.py"]:::data
            TR["transforms.py"]:::data
            DF --> DL --> DS1 --> DS2 --> SD --> TR
            click DF "https://github.com/gabrielelozupone/axial/blob/main/src/data/dataframe_loader.py"
            click DL "https://github.com/gabrielelozupone/axial/blob/main/src/data/dataloader.py"
            click DS1 "https://github.com/gabrielelozupone/axial/blob/main/src/data/dataset.py"
            click DS2 "https://github.com/gabrielelozupone/axial/blob/main/src/data/dataset_2d.py"
            click SD "https://github.com/gabrielelozupone/axial/blob/main/src/data/split_data.py"
            click TR "https://github.com/gabrielelozupone/axial/blob/main/src/data/transforms.py"
        end
        DP -->|"uses"| DF
        Template["Brain Templates\n(template/)"]:::data
        click Template "https://github.com/gabrielelozupone/axial/tree/main/template/"
        DP -->|".nii.gz templates"| Template
        DP -->|".nii.gz images"| Preprocessed["Preprocessed Images\n(.nii.gz)"]:::storage
        DP -->|".csv labels"| DSCSV["Dataset CSVs\n(.csv)"]:::storage
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        CFGYAML["config.yaml"]:::config
        AC["argparse_config.py"]:::config
        YC["yaml_config.py"]:::config
        click CFGYAML "https://github.com/gabrielelozupone/axial/blob/main/config.yaml"
        click AC "https://github.com/gabrielelozupone/axial/blob/main/src/config/argparse_config.py"
        click YC "https://github.com/gabrielelozupone/axial/blob/main/src/config/yaml_config.py"
        CFGYAML --> AC
        CFGYAML --> YC
    end

    %% Training & Evaluation
    subgraph "Model Training & Evaluation"
        direction TB
        Train["Training Script\ntrain.py"]:::train
        click Train "https://github.com/gabrielelozupone/axial/blob/main/train.py"
        Train --> CFGYAML
        Train --> AC
        Train --> YC
        subgraph "Model Implementations\n(src/models)"
            direction TB
            M1["axial_3d.py"]:::train
            M2["transformer_conv_3d.py"]:::train
            M3["majority_voting_3d.py"]:::train
            AddC["add_classifier.py"]:::train
            LBB["load_backbone.py"]:::train
            MET["metrics.py"]:::train
            subgraph "aware_net"
                direction TB
                AN1["awarenet.py"]:::train
                AN2["networks3D.py"]:::train
                AN3["aware_dataset.py"]:::train
                AN4["aware_experiment.py"]:::train
                AN5["get_dataloader.py"]:::train
                AN1 --> AN2 --> AN3 --> AN4 --> AN5
                click AN1 "https://github.com/gabrielelozupone/axial/blob/main/src/models/aware_net/awarenet.py"
                click AN2 "https://github.com/gabrielelozupone/axial/blob/main/src/models/aware_net/networks3D.py"
                click AN3 "https://github.com/gabrielelozupone/axial/blob/main/src/models/aware_net/aware_dataset.py"
                click AN4 "https://github.com/gabrielelozupone/axial/blob/main/src/models/aware_net/aware_experiment.py"
                click AN5 "https://github.com/gabrielelozupone/axial/blob/main/src/models/aware_net/get_dataloader.py"
            end
            M1 --> M2 --> M3 --> AddC --> LBB --> MET
            click M1 "https://github.com/gabrielelozupone/axial/blob/main/src/models/axial_3d.py"
            click M2 "https://github.com/gabrielelozupone/axial/blob/main/src/models/transformer_conv_3d.py"
            click M3 "https://github.com/gabrielelozupone/axial/blob/main/src/models/majority_voting_3d.py"
            click AddC "https://github.com/gabrielelozupone/axial/blob/main/src/models/add_classifier.py"
            click LBB "https://github.com/gabrielelozupone/axial/blob/main/src/models/load_backbone.py"
            click MET "https://github.com/gabrielelozupone/axial/blob/main/src/models/metrics.py"
        end
        Train --> M1
        Train --> AN1
        subgraph "Utilities\n(src/mynn)"
            direction TB
            O1["get_optimizer.py"]:::train
            O2["get_scheduler.py"]:::train
            O3["get_warmup_scheduler.py"]:::train
            O4["attention_layer.py"]:::train
            O5["classifiers.py"]:::train
            O6["positional_encoding.py"]:::train
            O7["transformer_block.py"]:::train
            O1 --> O2 --> O3 --> O4 --> O5 --> O6 --> O7
            click O1 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/get_optimizer.py"
            click O2 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/get_scheduler.py"
            click O3 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/get_warmup_scheduler.py"
            click O4 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/attention_layer.py"
            click O5 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/classifiers.py"
            click O6 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/positional_encoding.py"
            click O7 "https://github.com/gabrielelozupone/axial/blob/main/src/mynn/transformer_block.py"
        end
        Train --> O1
        subgraph "Logging\n(src/logger)"
            TB["TensorBoardWriter"]:::train
            click TB "https://github.com/gabrielelozupone/axial/blob/main/src/logger/tensorboard_writer.py"
        end
        Train <-->|logs| TB
        Train -->|".pt models"| Checkpoints["Model Checkpoints\n(.pt)"]:::storage
        Train -->|".csv results"| FoldRes["Fold Results\n(.csv)"]:::storage
        Train -->|"metrics"| Metrics["Overall Metrics"]:::storage
    end

    %% Explainability
    subgraph "Explainability Modules"
        direction TB
        Checkpoints --> AX["Attention XAI Script\nattention_xai_analysis.py"]:::xai
        click AX "https://github.com/gabrielelozupone/axial/blob/main/attention_xai_analysis.py"
        AXU["Attention Utils\nutils.py"]:::xai
        click AXU "https://github.com/gabrielelozupone/axial/blob/main/src/explainability/attention/utils.py"
        Checkpoints --> CX["CAM XAI Script\ncam_xai_analysis.py"]:::xai
        click CX "https://github.com/gabrielelozupone/axial/blob/main/cam_xai_analysis.py"
        CXU["CAM Utils\nutils.py"]:::xai
        click CXU "https://github.com/gabrielelozupone/axial/blob/main/src/explainability/cam/utils.py"
        AX --> Template
        CX --> Template
        AX -->|".nii.gz maps"| AttMaps["Attention Maps"]:::storage
        AX -->|".csv stats"| AttStats["Regional Stats"]:::storage
        CX -->|".nii.gz maps"| CamMaps["GradCAM Maps"]:::storage
        CX -->|".csv stats"| CamStats["Regional Stats"]:::storage
    end

    %% Styles
    classDef data fill:#D0E8FF,stroke:#1E90FF,color:#000;
    classDef external fill:#E8E8E8,stroke:#888,color:#000;
    classDef config fill:#F0E0FF,stroke:#B03060,color:#000;
    classDef train fill:#D6FFD6,stroke:#008000,color:#000;
    classDef storage fill:#FFF5BA,stroke:#DAA520,color:#000;
    classDef xai fill:#FFE8C4,stroke:#FF8C00,color:#000;
```
