Brain Tumor MRI Classification — Deep Learning Comparison

A research project implementing and comparing four deep-learning architectures — CNN, RNN, LSTM, and GNN — for classifying brain tumors from MRI images into four categories: glioma, meningioma, pituitary, and no tumor.

The repository contains one self-contained Jupyter notebook per architecture, shared evaluation tooling, per-model documentation, and the trained artifacts produced from the runs.

Project Status

Research / portfolio project. The implementation is complete for the CNN, RNN, and LSTM notebooks. The GNN notebook is implemented but its training run did not finish, so it does not currently report final test metrics (see Model Status).

Key Features

• Four architectures targeting the same task, with the same dataset and evaluation harness for a fair comparison:
  • CNN — ResNet-style network with residual blocks (TensorFlow/Keras)
  • RNN — 1D-conv + bidirectional LSTM treating image rows as sequences (TensorFlow/Keras)
  • LSTM — stacked bidirectional LSTM with TimeDistributed projections and layer normalization (TensorFlow/Keras)
  • GNN — Graph Convolutional Network over SLIC superpixels (PyTorch + PyTorch Geometric)
• Per-class metrics with precision, recall, and F1
• Confusion matrices, ROC and precision-recall curves, learning curves, and error galleries
• Trained models and metrics.json artifacts persisted under artifacts/
• Detailed per-architecture write-ups under docs/

Model Status

Model	Status	Test Accuracy	Macro F1	Weighted F1
CNN	Completed	0.8368	0.8406	0.8353
RNN	Completed	0.79	0.80	0.79
LSTM	Completed	0.77	0.78	0.7744
GNN	Implemented, training incomplete	—	—	—

The metrics above are taken from each notebook's executed test cell and from results_plots/comparison_report.md (CNN/RNN/LSTM only). The GNN notebook ran only one of its configured eight training epochs and did not produce final evaluation outputs, so no GNN test metrics are reported here. Rerunning the GNN notebook end-to-end is required to report GNN performance.

Per-class performance (F1) — completed models

Class	CNN	RNN	LSTM
glioma	0.77	0.75	0.74
meningioma	0.93	0.74	0.71
pituitary	0.80	0.83	0.80
no tumor	0.86	0.88	0.88

results_plots/comparison_report.md was generated when three models (CNN, RNN, LSTM) had completed; GNN results were not included in that report.

Architecture

flowchart LR
    A["Brain Tumor MRI dataset<br/>(glioma / meningioma / pituitary / no tumor)"] --> B["Train/val/test split<br/>(80/0/20, seed 42)"]
    B --> C["Preprocessing & augmentation<br/>(128x128 or 64x64 grayscale,<br/>flip/rotate/zoom/shift/contrast)"]
    C --> D1["CNN<br/>ResNet-style<br/>4 residual blocks"]
    C --> D2["RNN<br/>1D-Conv + BiLSTM<br/>row-sequence view"]
    C --> D3["LSTM<br/>Stacked BiLSTM<br/>+ TimeDistributed"]
    C --> D4["GNN<br/>SLIC superpixels<br/>+ GCN layers"]
    D1 --> E["Shared evaluation<br/>confusion matrix, ROC/PR,<br/>per-class F1, error gallery"]
    D2 --> E
    D3 --> E
    D4 --> E
    E --> F["artifacts/<model>/<br/>metrics.json, best model,<br/>history, plots"]

Loading

CNN/RNN/LSTM use TensorFlow/Keras; GNN uses PyTorch with PyTorch Geometric.

Technology Stack

• Language: Python 3.10
• Deep learning: TensorFlow >= 2.12 (CNN, RNN, LSTM); PyTorch >= 2.0 with PyTorch Geometric (GNN)
• Data / image: NumPy, pandas, Pillow, scikit-image (SLIC superpixels), OpenCV (Grad-CAM)
• Evaluation: scikit-learn
• Visualization: matplotlib, seaborn
• Environment: Jupyter notebooks

Repository Structure

.
├── notebooks/
│   ├── cnn_brain_tumor_classification.ipynb
│   ├── rnn_brain_tumor_classification.ipynb
│   ├── lstm_brain_tumor_classification.ipynb
│   ├── gnn_brain_tumor_classification.ipynb
│   └── compare_all_models.ipynb
├── docs/
│   ├── CNN_Documentation.md
│   ├── RNN_Documentation.md
│   ├── LSTM_Documentation.md
│   └── GNN_Documentation.md
├── artifacts/            # Trained models, metrics.json, history, confusion matrices
│   ├── cnn/
│   ├── rnn/
│   ├── lstm/
│   └── gnn/
├── results_plots/
│   └── comparison_report.md   # CNN/RNN/LSTM comparison (generated 2025-10-13)
├── requirements.txt
└── README.md

The dataset directory (data/) is not committed; each notebook expects it on disk (see Getting Started).

Prerequisites

• Python 3.10
• A CUDA-capable GPU is recommended for the TensorFlow notebooks (the CNN notebook enables mixed precision and notes GPU acceleration); CPU execution works but is slower
• PyTorch Geometric must be installed separately from PyTorch, following the PyG install guide for your CUDA/CPU build (only needed for the GNN notebook)

Getting Started

1. Clone and enter the repository:

   git clone https://github.com/dilrukshax/deep-learning-brain-tumor-detection
   cd deep-learning-brain-tumor-detection

2. Create and activate a virtual environment, then install dependencies:

   python -m venv venv
   source venv/bin/activate      # Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Install PyTorch Geometric for the GNN notebook (optional, if you only run the TensorFlow notebooks):

   pip install torch-geometric
   # plus the matching wheel index for your torch/cuda build, see the PyG docs

4. Provide the dataset in the expected layout (data is not committed):

   data/
   ├── glioma/
   ├── meningioma/
   ├── pituitary/
   └── notumor/
   

   Each subfolder should contain the respective MRI images in JPG/PNG format. The notebooks use a single configurable DATA_DIR pointing at this data/ directory.

5. Run the notebooks from the notebooks/ directory (paths in the notebooks are relative to notebooks/, so launch Jupyter from there):

   cd notebooks
   jupyter notebook

   Open and run in order:

   • cnn_brain_tumor_classification.ipynb
   • rnn_brain_tumor_classification.ipynb
   • lstm_brain_tumor_classification.ipynb
   • gnn_brain_tumor_classification.ipynb (note: training did not complete on the committed run)
   • compare_all_models.ipynb

Training Details

Common settings used across the TensorFlow notebooks:

• Optimizer: Adam, learning rate 1e-3
• Loss: sparse categorical crossentropy
• Batch size: 32 (16 on CPU)
• Epochs: up to 30 with early stopping
• Train/validation split: 80/20, seed 42
• Callbacks: EarlyStopping, ReduceLROnPlateau, ModelCheckpoint
• Augmentation: random horizontal flips, rotations (±15°), zoom (±15%), translations, contrast adjustments

The GNN notebook uses 8 epochs, batch size 8, Adam (lr 1e-3), cross-entropy with class weights.

Documentation

Detailed per-architecture write-ups are in docs/:

• CNN Documentation
• RNN Documentation
• LSTM Documentation
• GNN Documentation

Testing

There is no separate test suite. The notebooks themselves are the executable specification and include the evaluation cells that produced the reported metrics. The committed notebooks retain their executed outputs, so the metrics in the table above can be cross-checked against those cells.

Limitations

• The GNN notebook's training run did not complete; re-run it end-to-end to obtain GNN metrics and regenerate the comparison report with all four models.
• The dataset is not included in the repository; results require the Brain Tumor MRI dataset in the layout described above.
• Test-set metrics reflect a single train/validation split with seed 42 and are not cross-validated.

Contributing

Contributions are welcome. Please open an issue first to discuss the change, then submit a pull request from a feature branch.

License

Licensed under the MIT License.

Author

Dilan Dilruksha
Software Engineer | Backend & Full-Stack Development
Portfolio: https://dilandilruksha.dev
LinkedIn: https://www.linkedin.com/in/dilan-dilruksha
GitHub: https://github.com/dilrukshax