MorphoFuse-LCZ

Official PyTorch implementation of MorphoFuse-LCZ, a multimodal deep learning framework for Local Climate Zone (LCZ) classification using co-registered Sentinel-1 SAR (8 channels) and Sentinel-2 Optical (10 multispectral bands) Earth observation imagery.

---

Installation

git clone https://github.com/The-Fallen-Phoenix/Morphofuze-LCZ.git
cd Morphofuze-LCZ
pip install -r requirements.txt

Verify model initialization and tensor dimensions:

python scripts/model_shape_check.py

---

Dataset

The codebase is built for the So2Sat LCZ42 (v4) HDF5 benchmark. Expected directory structure:

data/so2sat_lcz42/v4/
├── training.h5
├── validation.h5
└── testing.h5

To validate dataset splits:

python scripts/prepare_so2sat.py --root data/so2sat_lcz42 --splits train val test --validate

---

Usage

1. Training

Train the model using the default configuration:

python train.py --config configs/default.yaml

Run the 3-stage training pipeline (frozen -> unfrozen -> fine-tune):

python run_pipeline.py --config configs/default.yaml

2. Evaluation

Run 8-fold test-time augmentation (TTA) evaluation:

python evaluate_tta.py --run-dir experiments/<run_name> --split test

Evaluate robustness to input perturbations:

python evaluate_robustness.py --run-dir experiments/<run_name> --split test

3. Explainability (XAI)

Generate Grad-CAM, SHAP, and LIME attribution maps:

python run_gradcam.py --run-dir experiments/<run_name> --split test --max-samples 64
python run_shap.py --run-dir experiments/<run_name> --split test
python run_lime.py --run-dir experiments/<run_name> --split test

4. Ablation Suite

Run the 25-configuration ablation experiments:

python auto_run_ablation_pipeline.py

---

Project Structure

Morphofuze-LCZ/
├── configs/                          # Experiment configuration YAMLs
│   ├── ablations/                    # 25 ablation configurations
│   └── default.yaml                  # Default model and training config
├── src/morphofuse_lcz/               # Source package
│   ├── models/                       # Model definitions (SASS, PSR, GCMF, UMTB)
│   ├── data.py                       # HDF5 dataset loaders and samplers
│   ├── trainer.py                    # PyTorch AMP training engine
│   ├── evaluator.py                  # Evaluation and metrics aggregation
│   ├── losses.py                     # Loss functions (CB-Focal, Hierarchical, SupCon)
│   ├── transforms.py                 # Multimodal spatial & radiometric transforms
│   └── xai.py                        # Explainability implementations
├── scripts/                          # Dataset verification and utility scripts
├── notebooks/                        # Colab and analysis notebooks
├── auto_run_ablation_pipeline.py     # Automated ablation pipeline runner
├── evaluate_tta.py                   # TTA evaluator
├── evaluate_robustness.py            # Robustness evaluator
├── run_pipeline.py                   # Multi-stage training runner
├── train.py                          # Training entry point
└── requirements.txt                  # Dependencies

---

License

This project is licensed under the MIT License - see the LICENSE file for details.