Skip to content

phohoccode/KLTN-ALZHEIMER-GUI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
backend
backend
 
 
frontend
frontend
 
 
notebook
notebook
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 

Repository files navigation

Alzheimer MRI Classification & XAI

Tiếng Việt

Web demo hỗ trợ phân loại bệnh Alzheimer từ ảnh MRI 3D và dữ liệu lâm sàng, đồng thời trực quan hóa các vùng ảnh MRI ảnh hưởng đến dự đoán bằng XAI (Explainable Artificial Intelligence - trí tuệ nhân tạo có thể giải thích).

Hệ thống phục vụ demo khóa luận với hai luồng chính:

  • Classification (phân loại): phân loại ba lớp CN, MCI, AD bằng best multimodal model (mô hình đa phương thức tốt nhất).
  • XAI Visualization (trực quan hóa XAI): tạo heatmap (bản đồ nhiệt) cho các MRI-only models (mô hình chỉ dùng MRI) bằng Grad-CAM, Grad-CAM++, Ablation-CAM.

Tổng quan hệ thống

Ứng dụng cho phép người dùng upload file MRI tensor .pt. Backend tự suy ra subject_id từ tên file theo mẫu ADNI, ví dụ:

005_S_1224.pt
005_S_1224_mri.pt

Sau khi có subject_id, backend tự động:

  • Tìm dữ liệu lâm sàng trong file CSV.
  • Tìm file NIfTI trong thư mục nội bộ.
  • Kiểm tra hippocampus mask (mặt nạ hồi hải mã) đã tồn tại hay chưa.
  • Nếu cần, tạo hippocampus mask từ NIfTI và Harvard-Oxford atlas.

Kết quả hiển thị trên web gồm:

  • Nhãn dự đoán CN/MCI/AD.
  • Confidence (độ tin cậy) và xác suất từng lớp.
  • Ảnh XAI summary (ảnh tổng quan) theo phong cách notebook Kaggle.
  • Ảnh axial, coronal, sagittal gồm original (ảnh gốc), heatmap và overlay (ảnh chồng lớp).

Công nghệ sử dụng

Backend:

  • FastAPI
  • PyTorch
  • MONAI
  • scikit-learn
  • nibabel, nilearn
  • matplotlib, Pillow

Frontend:

  • Next.js
  • React
  • TypeScript
  • Tailwind CSS
  • shadcn-style local UI components
  • lucide-react icons

Cấu trúc thư mục

Alzheimer-Web-GUI/
├── backend/
│   ├── app/
│   │   ├── model_definitions/
│   │   ├── routers/
│   │   ├── services/
│   │   └── xai/
│   ├── data/
│   ├── models/
│   ├── outputs/
│   ├── tests/
│   ├── config.py
│   ├── main.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   └── lib/
│   ├── package.json
│   └── tailwind.config.ts
├── notebook/
├── .gitignore
└── README.md

Model và dữ liệu cần chuẩn bị

Do model checkpoint, MRI, NIfTI và dữ liệu bệnh nhân có kích thước lớn hoặc nhạy cảm, các file này không nên commit lên Git.

Best classification model (mô hình phân loại tốt nhất):

backend/models/classification/best_model.pt

Checkpoint XAI MRI-only:

backend/models/xai/densenet121.pt
backend/models/xai/efficientnet_b0.pt
backend/models/xai/seresnet50.pt
backend/models/xai/swin-transformer.pt
backend/models/xai/hybridnet.pt

CSV clinical mặc định:

backend/data/patient_clinical_data.csv

CSV cần có các cột clinical:

Age, MMSE, FAQ_Score, Global_CDR, APOE4, Gender, Education, ADAS11, ADAS13

Các cột ID được hỗ trợ:

subject_id, Subject, PTID, RID

Thư mục NIfTI mặc định:

D:/KhoaLuanTotNghiep/processed_dataset/bias_corrected

Có thể thay đổi bằng biến môi trường:

$env:NIFTI_DATA_DIR="D:/path/to/nifti"
$env:CLINICAL_CSV_PATH="D:/path/to/patient_clinical_data.csv"

Pattern NIfTI được backend tìm:

{subject_id}_mni_bias_corrected.nii
{subject_id}_mni_bias_corrected.nii.gz
{subject_id}*.nii
{subject_id}*.nii.gz

Cài đặt backend

cd backend
python -m pip install -r requirements.txt

Chạy backend:

python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Kiểm tra health check:

Invoke-RestMethod http://127.0.0.1:8000/api/health

Cài đặt frontend

cd frontend
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000

Mở web:

http://127.0.0.1:3000

API chính

Health check:

GET /api/health

Thông tin model:

GET /api/models

Danh sách bệnh nhân từ CSV:

GET /api/patients
GET /api/patients/{subject_id}

Metadata sau khi upload MRI:

POST /api/xai/mri-metadata

Response gồm subject, MRI shape, clinical status, NIfTI status và mask status.

Phân loại bằng best model:

POST /api/predict-best

XAI:

POST /api/xai/explain
POST /api/xai/gradcam

/api/xai/explain hỗ trợ:

  • method=gradcam
  • method=gradcam_plus
  • method=ablationcam

Luồng sử dụng trên web

  1. Chọn file MRI .pt.
  2. Hệ thống tự suy ra subject_id.
  3. Backend tự tìm clinical data trong CSV.
  4. Backend tự tìm NIfTI trong NIFTI_DATA_DIR.
  5. Bấm Chạy phân loại để xem kết quả CN/MCI/AD.
  6. Bấm Tạo heatmap để sinh ảnh XAI.

Nếu không tìm thấy clinical data, giao diện mới hiển thị form nhập clinical_vector thủ công.

Nếu không tìm thấy NIfTI, XAI vẫn chạy nhưng không có contour hồi hải mã.

Kiểm thử

Backend:

python -m compileall backend
python backend/tests/test_xai_mri_metadata.py
python backend/tests/test_xai_gradcam.py
python backend/tests/test_xai_gradcam_plus.py
python backend/tests/test_xai_ablationcam.py
python backend/tests/test_xai_kaggle_style.py

Frontend:

cd frontend
npm run lint
npm run build

Lưu ý Git

.gitignore đã loại các file lớn và dữ liệu sinh ra:

  • backend/models/
  • backend/outputs/
  • backend/data/patient_clinical_data.csv
  • backend/data/nilearn_data/
  • backend/data/hippocampus_masks/
  • *.pt, *.pth, *.nii, *.nii.gz
  • frontend/node_modules/, frontend/.next/

Không commit checkpoint model, dữ liệu bệnh nhân, output XAI hoặc MRI gốc lên repository công khai.

Ghi chú

Hệ thống này là web demo phục vụ nghiên cứu/khóa luận. Kết quả phân loại và XAI không thay thế chẩn đoán y khoa.

English

This web demo supports Alzheimer classification from 3D MRI scans and clinical data, while also visualizing MRI regions that influence the prediction using XAI (Explainable Artificial Intelligence).

The system is designed for a thesis demo and includes two main workflows:

  • Classification: classifies three labels CN, MCI, and AD using the best multimodal model.
  • XAI Visualization: generates heatmaps for MRI-only models using Grad-CAM, Grad-CAM++, and Ablation-CAM.

System overview

The application allows users to upload an MRI tensor file .pt. The backend automatically infers the subject_id from the filename using the ADNI format, for example:

005_S_1224.pt
005_S_1224_mri.pt

After obtaining the subject_id, the backend automatically:

  • Searches for the corresponding clinical data in the CSV file.
  • Searches for the matching NIfTI file in the internal data directory.
  • Checks whether the hippocampus mask already exists.
  • If needed, generates a hippocampus mask from the NIfTI file and the Harvard-Oxford atlas.

The web result includes:

  • Predicted label CN/MCI/AD.
  • Confidence score and class probabilities.
  • Kaggle-notebook-style XAI summary image.
  • Axial, coronal, and sagittal images, including original image, heatmap, and overlay.

Tech stack

Backend:

  • FastAPI
  • PyTorch
  • MONAI
  • scikit-learn
  • nibabel, nilearn
  • matplotlib, Pillow

Frontend:

  • Next.js
  • React
  • TypeScript
  • Tailwind CSS
  • shadcn-style local UI components
  • lucide-react icons

Project structure

Alzheimer-Web-GUI/
├── backend/
│   ├── app/
│   │   ├── model_definitions/
│   │   ├── routers/
│   │   ├── services/
│   │   └── xai/
│   ├── data/
│   ├── models/
│   ├── outputs/
│   ├── tests/
│   ├── config.py
│   ├── main.py
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   └── lib/
│   ├── package.json
│   └── tailwind.config.ts
├── notebook/
├── .gitignore
└── README.md

Required models and data

Model checkpoints, MRI files, NIfTI files, and patient data can be large or sensitive, so they should not be committed to Git.

Best classification model:

backend/models/classification/best_model.pt

MRI-only XAI checkpoints:

backend/models/xai/densenet121.pt
backend/models/xai/efficientnet_b0.pt
backend/models/xai/seresnet50.pt
backend/models/xai/swin-transformer.pt
backend/models/xai/hybridnet.pt

Default clinical CSV:

backend/data/patient_clinical_data.csv

Required clinical columns:

Age, MMSE, FAQ_Score, Global_CDR, APOE4, Gender, Education, ADAS11, ADAS13

Supported ID columns:

subject_id, Subject, PTID, RID

Default NIfTI directory:

D:/KhoaLuanTotNghiep/processed_dataset/bias_corrected

You can override the paths using environment variables:

$env:NIFTI_DATA_DIR="D:/path/to/nifti"
$env:CLINICAL_CSV_PATH="D:/path/to/patient_clinical_data.csv"

NIfTI filename patterns searched by the backend:

{subject_id}_mni_bias_corrected.nii
{subject_id}_mni_bias_corrected.nii.gz
{subject_id}*.nii
{subject_id}*.nii.gz

Backend setup

cd backend
python -m pip install -r requirements.txt

Run backend:

python -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Health check:

Invoke-RestMethod http://127.0.0.1:8000/api/health

Frontend setup

cd frontend
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000

Open the web app:

http://127.0.0.1:3000

Main APIs

Health check:

GET /api/health

Model information:

GET /api/models

Patient list and patient detail from CSV:

GET /api/patients
GET /api/patients/{subject_id}

MRI metadata after upload:

POST /api/xai/mri-metadata

The response includes subject information, MRI shape, clinical status, NIfTI status, and mask status.

Best model classification:

POST /api/predict-best

XAI:

POST /api/xai/explain
POST /api/xai/gradcam

/api/xai/explain supports:

  • method=gradcam
  • method=gradcam_plus
  • method=ablationcam

Web usage flow

  1. Select an MRI .pt file.
  2. The system automatically infers the subject_id.
  3. The backend automatically searches for clinical data in the CSV file.
  4. The backend automatically searches for the NIfTI file in NIFTI_DATA_DIR.
  5. Click Chạy phân loại to view the CN/MCI/AD prediction.
  6. Click Tạo heatmap to generate XAI images.

If clinical data is not found, the interface will display a manual clinical_vector input form.

If the NIfTI file is not found, XAI can still run, but the hippocampus contour will not be displayed.

Testing

Backend:

python -m compileall backend
python backend/tests/test_xai_mri_metadata.py
python backend/tests/test_xai_gradcam.py
python backend/tests/test_xai_gradcam_plus.py
python backend/tests/test_xai_ablationcam.py
python backend/tests/test_xai_kaggle_style.py

Frontend:

cd frontend
npm run lint
npm run build

Git notes

.gitignore excludes large files and generated data:

  • backend/models/
  • backend/outputs/
  • backend/data/patient_clinical_data.csv
  • backend/data/nilearn_data/
  • backend/data/hippocampus_masks/
  • *.pt, *.pth, *.nii, *.nii.gz
  • frontend/node_modules/, frontend/.next/

Do not commit model checkpoints, patient data, XAI outputs, or original MRI files to a public repository.

Note

This system is a research/thesis demo. Classification and XAI results must not be used as a replacement for medical diagnosis.

About

[Graduation Thesis @ VLUTE] A full-stack Next.js & FastAPI GUI for Alzheimer's disease classification using 3D MRI & clinical data. Integrated with Quantum Machine Learning and Explainable AI (Grad-CAM, Grad-CAM++, Ablation-CAM). Student: [Nhan Quoc Viet] | Advisor: M.Sc. Nguyen Khac Tuong

Topics

nextjs grad-cam quantum-machine-learning explainable-ai seresnet fastapi densenet121 efficientnet hybridnet swin-transformer 3d-mri alzheimers-classification

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Contributors

Languages