elderly-heat-warning/CLAUDE.md

CLAUDE.md

项目概述

本科毕业设计：银发群体高温多时间尺度预警和服务优化可视化研究。为焦作市和郑州市老年群体构建基于 ERA5-Land 气象数据的高温健康风险预警模型（XGBoost + LSTM-Attention），并开发 Flask+ECharts 可视化大屏。

技术栈

• Python 3.13（uv 管理虚拟环境 .venv）
• PyTorch 2.12.0+cu126（GPU 训练，RTX 4060 Laptop 8GB）
• XGBoost 2.0+ / Scikit-learn 1.3+
• Flask 3.0+ / ECharts 5.5
• LaTeX（XeLaTeX + ctexbook，中文字体 STSong/Noto Sans SC/FangSong）
• xarray + h5netcdf + h5py（NetCDF4 读取）

常用命令

# 环境
uv sync                    # 同步依赖（含 CUDA PyTorch）
uv run python -c "..."     # 运行 Python 代码

# 数据管线
uv run python -m src.data.download_era5    # CDS API 下载 ERA5
uv run python -m src.data.extract_zips     # ZIP→NetCDF 解压
uv run python -m src.data.preprocess       # 预处理管线

# 模型
uv run python -m src.models.train          # 训练 LSTM
uv run python -m src.models.evaluate       # 评估 + XGBoost 训练

# Web
uv run python -m src.web.app               # 启动 Flask (localhost:5005)

# 论文
cd thesis && xelatex -interaction=nonstopmode main && xelatex -interaction=nonstopmode main

# Git
git push origin main     # 推送到 Gitea

项目结构

src/
├── data/
│   ├── download_era5.py       # CDS API 逐月下载（360文件）
│   ├── extract_zips.py        # ZIP 解压（CDS 新格式适配）
│   ├── preprocess.py          # 8步预处理管线（597行）
│   └── collect_mortality.py   # 死亡率/人口数据整理
├── models/
│   ├── lstm_attention.py      # LSTM-Attention 模型（983K参数）
│   ├── xgboost_baseline.py    # XGBoost 三分类器基线
│   ├── train.py               # 训练脚本（Focal Loss + 早停）
│   └── evaluate.py            # 评估对比 + 图表生成
├── web/
│   ├── app.py                 # Flask 4端点 (predict/history/stats/index)
│   └── static/index.html      # ECharts 6面板大屏（~800行）
└── utils/config.py            # 全局配置（城市坐标/超参数/路径）

关键路径

路径	说明
data/raw/era5/{city}/	每城 180 个 NetCDF 月文件
data/processed/	NPZ 序列 + CSV 特征（gitignored）
outputs/models/best_model.pt	LSTM 最佳 checkpoint（12MB，gitignored）
outputs/figures/	评估图表（PNG, 300dpi）
outputs/logs/	训练日志
thesis/main.pdf	编译后 PDF（56页）

运行注意事项

• CDS 下载很慢（约5天），使用单线程 + 5次指数退避重试，中断后可直接重启（已存在文件自动跳过）
• CDS 迁移后返回 ZIP 格式，需要 extract_zips.py 解压（文件头魔数检测 PK→ZIP）
• NetCDF 读取用 h5netcdf 引擎，不要用 netcdf4（Windows 需额外 DLL）
• 论文编译需 XeLaTeX + STSong/Noto Sans SC/FangSong 字体（Windows 自带或在系统字体目录）
• 类别极度不平衡（低风险 94-96%），LSTM 多次调优未收敛，XGBoost 为主力模型

远程仓库

Gitea: git@lhy-git.liuhangyv.top:Serendipity/elderly-heat-warning.git