OSCC Classification - Bachelor Thesis

Author: Luana Rafaela Gerber Brito

Institution: IU Internationale Hochschule
Supervisors: Dr. Anne Schwerk, Dr. Anna Araújo

Overview

Mobile CNN application for oral squamous cell carcinoma (OSCC) histopathological image classification for educational purposes. This project develops a lightweight MobileNetV3-based model optimized for iOS deployment.

Key Objectives:

• Macro-F1 ≥ 0.75
• Inference latency ≤ 200ms
• Model size ≤ 50MB

Hardware Requirements

• RAM: 8GB minimum, 16GB recommended
• Disk Space: ~30GB for WSI files and processed datasets
• GPU: Apple Silicon (M1/M2/M3) with MPS, or NVIDIA GPU with CUDA
• OS: macOS (this setup script is macOS-specific)

Project Structure

thesis_luanagerber/
├── app/                    # iOS application files
│   └── metrics/            # iOS performance test results
├── data/                   # Processed datasets
│   ├── dataset_card.txt    # Dataset documentation and statistics
│   ├── patches/            # Extracted patches from WSI
│   ├── filtered/           # Quality-filtered patches
│   ├── normalized/         # Macenko normalized patches
│   ├── balanced/           # Balanced dataset
│   └── splits/             # Train/val/test splits
├── scripts/                # Data processing and model training scripts
├── logs/                   # Processing logs and statistics
├── models/                 # Trained models and checkpoints
│   ├── mobilenet/          # MobileNet models
│   ├── resnet/             # ResNet50 models
│   └── coreml/             # Core ML converted models
├── visualizations/         # Dataset image samples
├── wsi_files/              # Original TCGA whole slide images
├── thesis_env/             # Python virtual environment
├── setup_environment.sh    # Environment setup script
├── requirements.txt        # Project requirements information
└── README.md               # This file

Note: Most folders are created automatically by the processing scripts.

Environment Setup

Prerequisites

• macOS (Apple Silicon or Intel)
• Homebrew installed
• Python 3.8+

Installation

1. Move the project folder to your home directory:

   mv thesis_luanagerber ~
   cd ~/thesis_luanagerber

2. Give execution permission to setup script:

   chmod +x setup_environment.sh

3. Run the setup script:

   bash setup_environment.sh

4. Add OpenSlide library path to your shell profile (for permanent access):

   echo 'export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/opt/openslide/lib:$DYLD_FALLBACK_LIBRARY_PATH"' >> ~/.zshrc
   source ~/.zshrc

5. Download the extracted patches:

   Run the download script:

   bash download_extracted_patches.sh

Or download manually from: http://luanagerber.duno.ch/thesis/1_0_patches_raw.zip

6. Make sure that the extracted files are located at the correct path:

   thesis_luanagerber/
   └── data/
       └── 1_0_patches_raw/
           ├── normal/
           └── tumor/

Activating the Environment

Always activate the virtual environment before running scripts:

cd ~/thesis_luanagerber
source thesis_env/bin/activate

Scripts Summary

Phase 1: Patch Extraction

• 1_0_extract_patches_wsi.py - Extract 224×224 patches from TCGA whole slide images at 20× magnification

Phase 2: Quality Filtering

• 2_0_quality_filtering.py - Filter patches based on tissue ratio and saturation thresholds
• 2_1_visualize_rejected_patches.py - Visualize rejected patches for quality assessment
• 2_2_analyze_threshold_impact.py - Analyze impact of different quality thresholds
• 2_3_extract_all_threshold_ranges.py - Extract patches across multiple threshold configurations
• 2_4_validate_filtered_quality.py - Validate quality of filtered patches
• 2_5_manual_filter_delete_patches.py - Manual review and deletion of low-quality patches

Phase 3: Stain Normalization

• 3_0_test_macenko_params.py - Test and optimize Macenko normalization parameters
• 3_1_macenko_normalization.py - Apply Macenko stain normalization to filtered patches

Phase 4: Data Balancing & Augmentation

• 4_0_analyze_actual_patches_per_patient.py - Analyze patch distribution per patient
• 4_1_offline_augmentation.py - Apply offline augmentation (20× for normal class)
• 4_2_visualize_augmented_patches.py - Visualize augmented patches
• 4_3_undersample_tumor_random.py - Undersample tumor class for balance
• 4_4_remove_mixed_patient_tumor_patches.py - Remove patches with data leakage risk
• 4_5_analyze_final_patches_per_patient.py - Final analysis of balanced dataset

Phase 5: Data Splitting

• 5_0_create_split_cv_8020.py - Create patient-level 80/20 train/val splits for 5-fold CV
• 5_1_verify_data_leakage.py - Verify no patient-level data leakage between splits

Phase 6: MobileNet Training & Evaluation

• 6_0_train_mobilenet_cv.py - Train MobileNetV3-Large with 5-fold cross-validation
• 6_1_analyze_mobilenet_cv_results.py - Analyze CV results with bootstrap confidence intervals
• 6_2_train_mobilenet_final.py - Train final MobileNet model on full training set
• 6_3_analyze_mobilenet_cv_misclassifications.py - Analyze top misclassified patches
• 6_4_visualize_mobilenet_cv_predictions.py - Visualize model predictions

Phase 7: ResNet50 Training & Evaluation

• 7_0_train_resnet50_cv.py - Train ResNet50 with 5-fold cross-validation (baseline)
• 7_1_analyze_resnet_cv_results.py - Analyze ResNet50 CV results
• 7_2_train_resnet50_final.py - Train final ResNet50 model
• 7_3_compare_mobilenet_resnet.py - Statistical comparison of MobileNet vs ResNet50

Phase 8: Core ML Conversion

• 8_0_convert_mobilenet_float32_coreml.py - Convert MobileNet to Core ML (FLOAT32)
• 8_1_convert_resnet_float32_coreml.py - Convert ResNet50 to Core ML (FLOAT32)

Phase 9: Quantization Analysis

• 9_0_create_split_for_quantization_8020.py - Create calibration split for quantization
• 9_1_train_mobilenet_for_quantization.py - Train MobileNet model for INT8 quantization
• 9_2_convert_mobilenet_for_quantization_to_coreml.py - Convert quantized model to Core ML
• 9_3_validate_quantization_models.py - Compare FLOAT32 vs INT8 performance

Phase 10: Final Model Deployment

• 10_apply_quantization_to_final_model.py - Apply optimal quantization to final production model
• 10_1_csv_analysis.py - Analyze iOS Performance Metrics

Workflow

1. Data Preparation: Run scripts 1.x - 4.x sequentially
2. Cross-Validation: Run scripts 5.x - 7.x for model training and comparison
3. Deployment: Run scripts 8.x - 10.x for iOS optimization
4. Testing: Use the iOS app for testing and demonstration

iOS Application

The app/ directory contains the Swift/SwiftUI iOS application designed for two primary purposes, also the performance testing results:

Performance Testing: Measure real-world performance metrics (latency, memory, model size) for thesis deliverables Usage Demonstration: Provide a practical example of how end-users would interact with the OSCC classification system

Target Devices:

• iPhone SE (baseline performance)
• iPhone 14 (optimized performance)

For detailed app documentation and implementation details, see app/OSCCClassifier/README.md.

Key Technologies

• Deep Learning: PyTorch, TorchVision
• Image Processing: OpenSlide, scikit-image, OpenCV
• Mobile Deployment: Core ML, INT8 quantization
• Analysis: scikit-learn, pandas, matplotlib, seaborn

Dataset

• Source: TCGA-HNSC (The Cancer Genome Atlas - Head and Neck Squamous Cell Carcinoma)
• Magnification: 20×
• Patch Size: 224×224 pixels
• Classes: Tumor vs Normal oral cavity tissue
• Challenge: Severe class imbalance (~50:1 tumor to normal ratio)

Hardware Acceleration

• macOS (Apple Silicon): Metal Performance Shaders (MPS)
• macOS (Intel): CPU fallback
• Target Deployment: iPhone SE, iPhone 14

License

This project is part of a Bachelor's thesis at IU Internationale Hochschule.

Contact

For questions or collaboration: luanagerber.dev@gmail.com