Calculate Urban Heat Island (UHI) intensity from MODIS LST GeoTIFF data. Classify heat island levels, perform temporal analysis, and output UHI maps with sta...
SKILL.md

---
name: urban-heat-analysis
display_name: 城市热岛分析工具
version: 0.1.0
author: ruiduobao
license: MIT-0
description: |
  Calculate Urban Heat Island (UHI) intensity from MODIS LST GeoTIFF data.
  Classify heat island levels, perform temporal analysis, and output UHI maps
  with statistics.
runtime: python>=3.8
tags: [gis, remote-sensing, uhi, modis, lst, urban-heat-island]
---

# urban-heat-analysis

Calculate Urban Heat Island (UHI) intensity from MODIS Land Surface Temperature (LST) GeoTIFF data. Supports UHI classification, temporal analysis, and map output.

## Features

- **UHI Intensity**: T_urban - T_rural_reference
- **Auto Rural Reference**: Uses coolest N% of pixels when no mask provided
- **Custom Rural Mask**: Accepts user-defined rural reference mask
- **Heat Island Classification**: Strong / Moderate / Weak / None
- **Temporal Analysis**: Seasonal UHI patterns from multiple LST images
- **GeoTIFF Output**: UHI intensity and classification maps
- **Statistics**: Mean, max, min, classification percentages

## Usage

```bash
# Compute UHI from single LST image
python urban-heat-analysis.py analyze --lst MOD11A1.tif --output uhi.tif

# With rural reference mask
python urban-heat-analysis.py analyze --lst lst.tif --rural-mask rural.tif --output uhi.tif

# Classify UHI intensity map
python urban-heat-analysis.py classify --uhi-tif uhi.tif --output classified.tif

# Temporal analysis across multiple images
python urban-heat-analysis.py temporal --lst-dir ./lst_data/ --output seasonal.json
```

## Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--lst` | LST GeoTIFF file path | Required |
| `--rural-mask` | Rural reference mask (1=rural) | None |
| `--rural-fraction` | Fraction of coolest pixels as rural ref | 0.1 |
| `--uhi-tif` | UHI intensity GeoTIFF (classify mode) | Required |
| `--lst-dir` | Directory of LST files (temporal mode) | Required |
| `--output` | Output file path | Auto-generated |

## Installation

```bash
pip install requests>=2.28.0 tqdm numpy scipy rasterio
# Or: pip install -r scripts/requirements.txt
```

## Dependencies

| Package | Purpose |
|---------|---------|
| `rasterio` | GeoTIFF I/O and CRS handling |
| `numpy` | Array computation and statistics |
| `requests` | Data download (if applicable) |
| `tqdm` | Progress bars |

## Data Source

- **MODIS LST** (MOD11A1/MYD11A1) — NASA EOSDIS, Public Domain
- Scale factor: value × 0.02 = Kelvin
- Supports both Terra (MOD) and Aqua (MYD) products

## Data Acquisition

Obtain MODIS LST data from:
- **NASA Earthdata Search** (https://search.earthdata.nasa.gov/) — search for MOD11A1 or MYD11A1
- **NASA LAADS DAAC** (https://ladsweb.modaps.eosdis.nasa.gov/)
- Requires free Earthdata login (https://urs.earthdata.nasa.gov/)

## Nodata Handling

Nodata pixels (QC-flagged or fill values) are automatically excluded from UHI computation. The output GeoTIFF uses `nodata=-9999`. When using auto rural reference, nodata pixels are not considered in the coolest-N% calculation.

## CRS Requirements

All input rasters should be in the **same CRS**. If combining Terra and Aqua images, ensure they share the same projection and spatial extent. Reproject with `gdalwarp` if needed:

```bash
gdalwarp -t_srs EPSG:4326 input.tif reprojected.tif
```

## Cloud Contamination Handling

Use the QC band (`QC_Day` or `QC_Night`) to filter cloud-contaminated pixels. Pixels with QC flags indicating cloud cover should be masked out before UHI analysis:

```bash
python urban-heat-analysis.py analyze --lst MOD11A1.tif --qc-band qc.tif --output uhi.tif
```

If QC band is not available, consider using only clear-sky quality flags (QC == 0).

## Temporal Analysis Date Logic

For temporal analysis, dates are extracted from filenames using the MODIS naming convention (e.g., `MOD11A1.A2023001.h27v05.061.2023002010234.hdf`). Alternatively, use `--date-format` to specify a custom pattern:

```bash
python urban-heat-analysis.py temporal --lst-dir ./lst_data/ --date-format "%Y%m%d" --output seasonal.json
```

## Output GeoTIFF Structure

| Property | Value |
|----------|-------|
| Data type | `float32` |
| Bands | 1 (UHI intensity in °C) |
| NoData | -9999 |
| CRS | Same as input |

## Custom UHI Thresholds

Default classification uses fixed thresholds. To customize:

```bash
python urban-heat-analysis.py classify --uhi-tif uhi.tif --thresholds "1.0,2.5,4.0" --output classified.tif
```

The 3 values define boundaries between: none / weak / moderate / strong UHI.

## CSV Export for Statistics

Export classification statistics to CSV:

```bash
python urban-heat-analysis.py analyze --lst lst.tif --output uhi.tif --csv-stats stats.csv
```

CSV columns: `class, pixel_count, percentage, mean_intensity`.

## Multi-Sensor Combination

Combine Terra (MOD) and Aqua (MYD) for same-day average:

```bash
python urban-heat-analysis.py combine --terra MOD11A1.tif --aqua MYD11A1.tif --output lst_avg.tif
```

Then run UHI analysis on the averaged LST.

## Validation / Quality Assessment

- Compare UHI results with ground-based air temperature stations
- Check for anomalous values (|UHI| > 10°C may indicate cloud residual or data error)
- Report rural reference temperature sanity (should be within regional climate norms)

## Citation

```bibtex
@article{imhoff2010remote,
  title={Remote sensing of the urban heat island effect across biomes in the continental USA},
  author={Imhoff, Marc L and Zhang, Ping and Wolfe, Robert E and Bounoua, Lahouari},
  journal={Remote Sensing of Environment},
  volume={114},
  number={3},
  pages={504--513},
  year={2010},
  doi={10.1016/j.rse.2009.10.008}
}
```

## Visualization Guidance

```python
import rasterio
import matplotlib.pyplot as plt
import numpy as np

with rasterio.open("uhi.tif") as src:
    uhi = src.read(1)
    nodata = src.nodata

uhi_plot = np.where(uhi == nodata, np.nan, uhi)

fig, ax = plt.subplots(figsize=(10, 8))
im = ax.imshow(uhi_plot, cmap="RdYlBu_r", vmin=-2, vmax=6)
cbar = plt.colorbar(im, ax=ax, shrink=0.8)
cbar.set_label("UHI Intensity (°C)")
ax.set_title("Urban Heat Island Intensity")
ax.axis("off")
plt.tight_layout()
plt.savefig("uhi_map.png", dpi=200)
```

## UHI Classification

| UHI Intensity (°C) | Classification |
|---------------------|----------------|
| > 4.0 | Strong UHI |
| 2.0 to 4.0 | Moderate UHI |
| 0.0 to 2.0 | Weak UHI |
| < 0.0 | None/Cool |

## Troubleshooting

| Error | Cause | Solution |
|-------|-------|----------|
| `ConnectionError` | Network issue | Check internet, retry |
| `HTTP 429` | Rate limit | Wait 60s, retry |
| `ValueError` | Invalid input | Check parameter format |
| Empty output | No data | Try different parameters |
| `ModuleNotFoundError` | Missing dep | Run pip install |

---

## Advanced Usage

### Batch Multi-Date Analysis
```bash
for lst_file in data/MOD11A1*.tif; do
  python scripts/urban_heat_analysis.py analyze     --input "$lst_file" --rural-fraction 0.1     --output "uhi_$(basename $lst_file)"
done
```

### CI/CD Integration (GitHub Actions)
```yaml
# .github/workflows/uhi-monitor.yml
name: UHI Monthly Analysis
on:
  schedule:
    - cron: '0 0 5 * *'  # Monthly
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install numpy rasterio
      - run: |
          python scripts/urban_heat_analysis.py analyze \
            --input data/latest_lst.tif \
            --rural-fraction 0.1 \
            --output data/uhi_latest.tif
```

### PostGIS Raster Import
```bash
raster2pgsql -s 4326 -I -C uhi_latest.tif public.uhi_intensity | psql -d gis_db
```

### Performance Tips
- `--rural-fraction 0.1` uses coolest 10% as rural reference; adjust for your region
- Use `--thresholds 1.5 3.0` for arid regions (default 2.0/4.0 is for temperate)
- Combine Terra + Aqua: run analysis separately, then average results

---

## 中文说明

基于 MODIS 地表温度（LST）GeoTIFF 数据计算城市热岛（UHI）强度，支持热岛分级、时序分析和专题图输出。

## 安装

```bash
pip install requests>=2.28.0 tqdm numpy scipy rasterio
# 或: pip install -r scripts/requirements.txt
```

## 依赖

| 包 | 用途 |
|-----|------|
| `rasterio` | GeoTIFF 读写和 CRS 处理 |
| `numpy` | 数组计算和统计 |
| `requests` | 数据下载（如适用） |
| `tqdm` | 进度条 |

## 数据获取

从以下渠道获取 MODIS LST 数据：
- **NASA Earthdata Search** (https://search.earthdata.nasa.gov/) — 搜索 MOD11A1 或 MYD11A1
- **NASA LAADS DAAC** (https://ladsweb.modaps.eosdis.nasa.gov/)
- 需要免费 Earthdata 账号 (https://urs.earthdata.nasa.gov/)

## NoData 处理

NoData 像元（QC 标记或填充值）自动从 UHI 计算中排除。输出 GeoTIFF 使用 `nodata=-9999`。使用自动乡村参考时，NoData 像元不参与最冷 N% 计算。

## CRS 要求

所有输入栅格应使用**相同 CRS**。如合并 Terra 和 Aqua 影像，确保它们共享相同的投影和空间范围。如需重投影：

```bash
gdalwarp -t_srs EPSG:4326 input.tif reprojected.tif
```

## 云污染处理

使用 QC 波段（`QC_Day` 或 `QC_Night`）过滤云污染像元。QC 标记为云覆盖的像元应在 UHI 分析前掩膜掉：

```bash
python urban-heat-analysis.py analyze --lst MOD11A1.tif --qc-band qc.tif --output uhi.tif
```

## 时序分析日期逻辑

时序分析中，日期从文件名按 MODIS 命名约定提取。也可使用 `--date-format` 指定自定义格式：

```bash
python urban-heat-analysis.py temporal --lst-dir ./lst_data/ --date-format "%Y%m%d" --output seasonal.json
```

## 输出 GeoTIFF 结构

| 属性 | 值 |
|------|-----|
| 数据类型 | `float32` |
| 波段数 | 1（UHI 强度，°C） |
| NoData | -9999 |
| CRS | 与输入相同 |

## 自定义 UHI 阈值

```bash
python urban-heat-analysis.py classify --uhi-tif uhi.tif --thresholds "1.0,2.5,4.0" --output classified.tif
```

3 个值定义无/弱/中/强热岛的分界。

## CSV 统计导出

```bash
python urban-heat-analysis.py analyze --lst lst.tif --output uhi.tif --csv-stats stats.csv
```

CSV 列：`class, pixel_count, percentage, mean_intensity`。

## 多传感器组合

组合 Terra (MOD) 和 Aqua (MYD) 计算同日平均：

```bash
python urban-heat-analysis.py combine --terra MOD11A1.tif --aqua MYD11A1.tif --output lst_avg.tif
```

## 验证/质量评估

- 将 UHI 结果与地面气温站对比
- 检查异常值（|UHI| > 10°C 可能为云残留或数据错误）
- 报告乡村参考温度合理性（应在区域气候正常范围内）

## 引用格式

```bibtex
@article{imhoff2010remote,
  title={Remote sensing of the urban heat island effect across biomes in the continental USA},
  author={Imhoff, Marc L and Zhang, Ping and Wolfe, Robert E and Bounoua, Lahouari},
  journal={Remote Sensing of Environment},
  volume={114},
  number={3},
  pages={504--513},
  year={2010},
  doi={10.1016/j.rse.2009.10.008}
}
```

## 可视化指南

```python
import rasterio
import matplotlib.pyplot as plt
import numpy as np

with rasterio.open("uhi.tif") as src:
    uhi = src.read(1)
    nodata = src.nodata

uhi_plot = np.where(uhi == nodata, np.nan, uhi)

fig, ax = plt.subplots(figsize=(10, 8))
im = ax.imshow(uhi_plot, cmap="RdYlBu_r", vmin=-2, vmax=6)
cbar = plt.colorbar(im, ax=ax, shrink=0.8)
cbar.set_label("UHI 强度 (°C)")
ax.set_title("城市热岛强度")
ax.axis("off")
plt.tight_layout()
plt.savefig("uhi_map.png", dpi=200)
```

## 故障排除

| 错误 | 原因 | 解决方案 |
|------|------|----------|
| `ConnectionError` | 网络问题 | 检查网络，重试 |
| `HTTP 429` | 速率限制 | 等待 60 秒后重试 |
| `ValueError` | 无效输入 | 检查参数格式 |
| 空输出 | 无数据 | 尝试不同参数 |
| `ModuleNotFoundError` | 缺少依赖 | 运行 pip install |

基于 MODIS 地表温度（LST）GeoTIFF 数据计算城市热岛（UHI）强度，支持热岛分级、时序分析和专题图输出。

## 功能特性

- **UHI 强度计算**：T_城市 - T_乡村参考
- **自动乡村参考**：无掩膜时使用最冷 N% 像元
- **自定义乡村掩膜**：支持用户定义乡村参考区
- **热岛分级**：强/中/弱/无 四级分类
- **时序分析**：多期 LST 影像的季节性热岛变化
- **GeoTIFF 输出**：热岛强度和分级专题图
- **统计信息**：均值、最大最小值、分级占比

## 使用方法

```bash
# 单期 LST 计算 UHI
python urban-heat-analysis.py analyze --lst MOD11A1.tif --output uhi.tif

# 使用乡村参考掩膜
python urban-heat-analysis.py analyze --lst lst.tif --rural-mask rural.tif --output uhi.tif

# 热岛分级
python urban-heat-analysis.py classify --uhi-tif uhi.tif --output classified.tif

# 时序分析
python urban-heat-analysis.py temporal --lst-dir ./lst_data/ --output seasonal.json
```

## 数据来源

- **MODIS LST** (MOD11A1/MYD11A1) — NASA EOSDIS，公共领域
- 缩放系数：值 × 0.02 = 开尔文
- 支持 Terra (MOD) 和 Aqua (MYD) 产品

## 热岛分级标准

| UHI 强度 (°C) | 等级 |
|---------------|------|
| > 4.0 | 强热岛 |
| 2.0 至 4.0 | 中等热岛 |
| 0.0 至 2.0 | 弱热岛 |
| < 0.0 | 无热岛/冷岛 |
Urban Heat Analysis

SKILL.md

related skills
