How gabrielelozupone/axial works
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