README.md

---
license: cc-by-4.0
tags:
  - weather
  - microclimate
  - campus
  - singapore
  - variational-autoencoder
  - embeddings
---

# 🌤️ NUS-40: Dense Campus Weather Embeddings

> **40 weather stations · 1 year hourly · 6 variables · NUS Singapore**  
> *A single 6-dimensional VAE embedding supports spatial interpolation, forecasting, clustering, anomaly detection, and future prediction.*

---

## 🔬 Overview

A **variational autoencoder (VAE)** that compresses 6-variable weather observations from 40 campus stations into a compact **6-dimensional embedding**. The embedding achieves R² > 0.99 reconstruction and supports **5 downstream tasks** with no retraining:

| # | Task | Result |
|---|---|---|
| 1️⃣ | **Spatial Interpolation** — predict weather at unmeasured locations | AirTemp MAE = 0.39°C |
| 2️⃣ | **Temporal Forecasting** — predict future weather vs persistence baseline | +15.7% skill at T+6h |
| 3️⃣ | **Microclimate Clustering** — discover climate zones without labels | 4 zones (silhouette=0.23) |
| 4️⃣ | **Anomaly Detection** — flag unusual weather from reconstruction error | 5% flagged, storm-linked |
| 5️⃣ | **24h Future Prediction** — rolling forecast across full diurnal cycle | +42% peak skill at T+14h |

---

## 📊 The NUS-40 Dataset

40 stations deployed across the National University of Singapore Kent Ridge campus (~2 km²), recording at hourly resolution for all of 2025.

### Variables

| Variable | Unit | Mean | Std | Range |
|---|---|---|---|---|
| 🌡️ Air Temperature | °C | 28.64 | 2.56 | 21.5 – 39.5 |
| 💧 Relative Humidity | % | 80.49 | 10.11 | 37.6 – 99.5 |
| 🔵 Atmospheric Pressure | hPa | 1006.4 | 2.72 | 994.6 – 1016.4 |
| 💨 Wind Speed | m/s | 0.65 | 0.67 | 0.0 – 17.0 |
| 🧭 Wind Direction | ° | 185.4 | 108.0 | 0 – 360 |
| ☀️ Solar Radiation | W/m² | 141.1 | 233.2 | 0 – 1500 |

### At a Glance
- **40 stations**, mean spacing ~100–200 m
- **8,760 hours** (Jan–Dec 2025)
- **2.0 km × 1.4 km** campus footprint
- **Tropical climate** (Köppen Af) — minimal seasons, strong diurnal cycle
- **4.7% missing**, with imputation flags provided
- WS17 has no pressure sensor (filled with campus mean)

---

## 🏗️ Model

A standard VAE with MLP encoder and decoder.

```
Input (6 vars) → Encoder (3-layer MLP, 128 hidden) → z ~ N(μ, σ²)  [6 dims]
                                                          ↓
Output (6 vars) ← Decoder (3-layer MLP, 128 hidden) ←────┘
```

| Property | Value |
|---|---|
| Parameters | 70,930 |
| Latent dimensions | 6 |
| Encoder/Decoder | 3-layer MLP, LayerNorm, GELU |
| Loss | MSE + β·KL (β = 0.001) |
| Training | 100 epochs, AdamW, cosine schedule |
| Training time | ~20 min on CPU |

---

## 📈 Results

### Reconstruction (R² on held-out test set)

| AirTemp | RelHum | AtmPress | WindSpeed | WindDir | GlobalRad |
|---|---|---|---|---|---|
| **0.9997** | **0.9997** | **0.9995** | 0.9429 | **0.9994** | **0.9998** |

### Spatial Interpolation (5 held-out stations, reconstructed from neighbours)

| Variable | MAE | R² |
|---|---|---|
| 🌡️ Air Temperature | **0.39°C** | **0.949** |
| 💧 Relative Humidity | **1.80%** | **0.944** |
| 🔵 Atmospheric Pressure | **0.21 hPa** | **0.987** |
| 💨 Wind Speed | 0.33 m/s | −0.52 |
| ☀️ Solar Radiation | 35.5 W/m² | 0.19 |

> Temperature and humidity interpolate within sensor accuracy (±0.3°C). Wind and radiation depend too strongly on local building geometry.

### Forecasting Skill (vs persistence baseline)

| Horizon | AirTemp | RelHum |
|---|---|---|
| T+1h | −6.0% ❌ | −8.0% ❌ |
| T+6h | **+15.7%** ✅ | **+13.8%** ✅ |
| T+12h | **+37.9%** ✅ | ~+25% ✅ |
| T+24h | +2.5% | +5.0% |

> Persistence wins at 1h in the tropics. Embeddings outperform at 6–15h horizons.

### Anomaly Detection
- **438 hours** flagged (5.0% of year)
- Anomalous hours have **54% less solar radiation** → storm/cloud association
- Bimodal temporal pattern: **peaks at 07:00 (sunrise) and 18:00 (sunset)** transitions
- Station WS17 flagged automatically (missing pressure sensor)

---

## 📁 Repository Structure

```
📦 citysyntaxlab/campus-weather
├── 📄 README.md
├── 📄 paper/paper.md               ← Full manuscript (~4,300 words, 16 references)
│
├── 💻 code/
│   ├── model.py                    ← VAE architecture (90 lines)
│   ├── train.py                    ← Data loading, training, embedding extraction
│   ├── evaluate.py                 ← All 5 downstream evaluations
│   └── figures.py                  ← Figure generation
│
├── 📊 figures/                     ← 6 figures (PDF + PNG)
│   ├── fig1_campus.{pdf,png}       ← Station map + discovered clusters
│   ├── fig2_reconstruction.{pdf,png} ← Reconstruction R² bar chart
│   ├── fig3_spatial.{pdf,png}      ← Spatial interpolation results
│   ├── fig4_forecasting.{pdf,png}  ← Forecast MAE comparison
│   ├── fig5_anomaly.{pdf,png}      ← Anomaly timeseries + hour distribution
│   └── fig6_future.{pdf,png}       ← 24h forecast skill curves
│
├── 🧪 results/
│   ├── all_results.json            ← All numerical results
│   ├── anomaly_errors.npy          ← Hourly reconstruction errors
│   └── checkpoints/
│       ├── best.pt                 ← Trained model weights
│       └── embeddings.npz          ← All embeddings: (8760, 40, 6) + data + coords
│
├── 📡 raw/                         ← 40 station CSVs (original measurements)
│   └── NUS_CAMPUS_WS{01-40}_2025_Hourly.csv
│
└── 📡 imputed/                     ← 40 station CSVs (gap-filled, with flags)
    └── NUS_CAMPUS_WS{01-40}_2025_Hourly_imputed.csv
```

---

## 🚀 Quick Start

### Load pre-trained model and embeddings

```python
import torch, numpy as np
from model import WeatherVAE

# Load checkpoint
ckpt = torch.load('results/checkpoints/best.pt', map_location='cpu')
model = WeatherVAE(**ckpt['config'])
model.load_state_dict(ckpt['model'])
model.set_normalisation(ckpt['mean'], ckpt['std'])
model.eval()

# Get embedding for a weather observation
# [WindSpeed, WindDir, AirTemp, RelHum, AtmPress, GlobalRad]
x = torch.tensor([[0.5, 180.0, 29.0, 80.0, 1007.0, 300.0]])
z = model.get_embedding(x)  # shape: (1, 6)

# Load pre-computed embeddings for all data
npz = np.load('results/checkpoints/embeddings.npz', allow_pickle=True)
embeddings = npz['embeddings']   # (8760, 40, 6)
data = npz['data']               # (8760, 40, 6)
coords = npz['coords']           # (40, 2) — [lat, lng]
```

### Train from scratch

```bash
python code/train.py --data imputed/ --epochs 100 --config base
```

### Run all evaluations

```bash
python code/evaluate.py
```

### Generate figures

```bash
python code/figures.py
```

---

## 📝 Paper

Full manuscript at [`paper/paper.md`](paper/paper.md).

**Title:** Learning Dense Weather Embeddings for Campus-Scale Microclimate Analysis  
**Target venue:** Building and Environment  
**Words:** ~4,300 | **References:** 16 (all verified)

---

## 📎 Citation

```bibtex
@article{nus40weather2025,
  title={Learning Dense Weather Embeddings for Campus-Scale Microclimate Analysis},
  author={City Syntax Lab, National University of Singapore},
  year={2025}
}
```

---

## 📜 License

Dataset and code released under CC-BY-4.0. Please cite the paper if you use this work.