pakflood-lora / CODE_README.md
msherry's picture
project code, results and figures
17285c6 verified
|
Raw History Blame Contribute Delete
3.95 kB
# PakFlood-LoRA: project code
Deep learning course project, MS AI, NED University of Engineering & Technology.
Author: Muhammad Shahwar Uddin (CS-139/2026). Supervisor: Dr. Sharaf Hussain.
Everything runs on top of the GEOID-Flood authors' TerraTorch repository (github.com/links-ads/geoid-flood) in a
Python 3.12 virtual environment (TerraTorch 1.1, PyTorch 2.7.1, PEFT 0.21.3). The scripts below are the project's
own additions; the dataset (82 GB) and the full checkpoints stay on the training server, the trained rank-32 LoRA model
is in `assets/` of this repository as an fp16 state dict (205 MB).
## Folder layout (this repository)
| Path | What it is |
|---|---|
| `app.py`, `requirements.txt`, `samples/`, `samples.json`, `assets/` | the live demo (Gradio): rebuilds the model with TerraTorch and loads the trained weights; 15 official Pakistani test tiles |
| `PakFlood_LoRA_Colab_demo.ipynb` | runs the demo in Google Colab with a public link |
| `code/` | the training and evaluation pipeline (below) |
| `code/configs/` | one YAML per run, generated by `make_configs.py` from the authors' early-fusion Sentinel-1 config (regenerate it inside the authors' repository) |
| `results/results.json` | every number in the report (test metrics, confidence intervals, cost table, population) |
| `results/per_tile_lora_r32_all_test.csv` | per-tile confusion matrices of the rank-32 model on the 2,417 official test tiles |
| `results/pop_*.csv` | affected population per EMSR838 tile and area of interest, per model |
| `figures/` | all figures of the report and slides |
## Pipeline (`code/`)
| Script | What it does |
|---|---|
| `make_sa_split.py` | builds the South Asia hold-out, few-shot and Pakistan-test metadata CSVs from the official split |
| `make_configs.py` | derives every run configuration (frozen, LoRA r16, LoRA r32, full fine-tune, CE+Dice, hold-out, few-shot) |
| `tasks.py` | TerraTorch task subclass: weighted cross-entropy + Dice loss, checkpoint initialisation for the few-shot pass |
| `run_job.sh` | queues a `terratorch fit`/`test` or any command on the GPU behind a lock, detached from the login session |
| `h3_chain.sh`, `h12_chain.sh` | the ordered evaluation chains (hold-out tests, few-shot fit and tests, predictions, population) |
| `predict_tiles.py` | full-tile sliding-window prediction (256/128, averaged softmax), GeoTIFF maps, per-tile confusion matrices |
| `bootstrap.py` | paired bootstrap 95% confidence intervals over tiles or events |
| `population.py` | WorldPop overlay: affected people and flooded area per area of interest |
| `pack_demo.py` | exports the fp16 state dict and the sample tiles for the demo |
| `plot_results.py`, `plot_overview.py`, `plot_architecture.py`, `make_figures.py` | the figures |
## Reproducing a run
```bash
# inside the geoid-flood repository, with the dataset under data/geoid-flood and this repo's code/ copied to pakflood/
.venv/bin/python pakflood/make_sa_split.py
.venv/bin/python pakflood/make_configs.py
bash pakflood/run_job.sh fit lora_r32_all pakflood/configs/lora_r32_all.yaml
bash pakflood/run_job.sh test test_lora_r32_all pakflood/configs/lora_r32_all.yaml workdir/pakflood/lora_r32_all/v1/checkpoints/best.ckpt
PYTHONPATH=. .venv/bin/python pakflood/predict_tiles.py workdir/pakflood/lora_r32_all/v1/checkpoints/best.ckpt preds/r32_test --events all --split test --task pakflood
.venv/bin/python pakflood/bootstrap.py r32=preds/r32_test/per_tile.csv --unit event
```
## Headline results
Official GEOID-Flood test split (2,417 tiles, 80 events), flood IoU: frozen encoder 0.433, LoRA r16 (q, v) 0.493,
LoRA r32 (all linear layers) 0.525, full fine-tune 0.525. South Asia hold-out 0.679, after few-shot with 26 tiles 0.720.
Affected population for EMSR838 (Punjab, August 2025): hold-out model 795,280 vs official 766,148 (+3.8%).
Data: GEOID-Flood v1.1 (CC BY 4.0). Base model: TerraMind v1 base (IBM and ESA). Population: WorldPop 2020.