Serendipity/elderly-heat-warning
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新 README.md 反映项目现状, 新增项目 CLAUDE.md

Browse Source
This commit is contained in:
刘航宇
2026-05-28 14:19:14 +08:00
parent a352fbfe4c
commit 29bd19bae4
2 changed files with 182 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+83
View File
@@ -0,0 +1,83 @@
# 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 读取）
## 常用命令
```bash
# 环境
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`
README.md
+91 -78
View File
@@ -2,57 +2,56 @@
本科毕业设计 — 河南理工大学计算机科学与技术学院 本科毕业设计 — 河南理工大学计算机科学与技术学院
## 概述 ## 项目概述
本项目针对焦作市和郑州市老年群体，构建了基于 LSTM-Attention 的多时间尺度高温健康风险预警模型，并开发了 ECharts 可视化大屏系统。 针对焦作市和郑州市老年群体，利用 ERA5-Land 气象再分析数据（2010-2024年），构建了基于 XGBoost 和 LSTM-Attention 的多时间尺度高温健康风险预警模型，并开发了 ECharts 可视化大屏系统。
### 核心功能 ### 核心成果
- **多时间尺度预警**：短期（1-3天）、中期（7天）、长期（30天）三级高温健康风险预测 - **数据集**：109.6万条序列样本（14天×19特征），覆盖短期(3d)/中期(7d)/长期(30d)预测
- **深度学习模型**：BiLSTM + Multi-Head Attention，三头输出同时预测三个时间尺度 - **XGBoost 模型**：短期 F1=0.933，中期 F1=0.920，长期 F1=0.858（主力模型）
- **基线对比**：XGBoost 三分类器，验证深度学习方法有效性 - **LSTM-Attention 模型**：983K 参数，BiLSTM+MHA，Focal Loss 训练（受限于类别不平衡）
- **可视化大屏**：6 面板深色科技蓝风格 Web 大屏，含温度趋势、风险预警、人口统计等 - **可视化大屏**：Flask + ECharts 5.5，深色科技蓝风格，6 面板
- **完整论文**：LaTeX 学位论文，含 7 个章节 + 参考文献 + 附录 - **学位论文**：LaTeX 编写的 7 章本科毕业论文，56 页，GB/T 7714 参考文献
### 技术栈 ### 技术栈
| 层 | 技术 | | 层 | 技术 |
|----|------| |----|------|
| 数据处理 | Python, xarray, pandas, numpy | | 数据获取 | ERA5-Land (CDS API), cdsapi 0.7.7 |
| 气象数据 | ERA5-Land (CDS API) | | 数据处理 | Python 3.13, xarray, h5netcdf, h5py, pandas, numpy |
| 深度学习 | PyTorch 2.12, CUDA 12.6 | | 深度学习 | PyTorch 2.12.0+cu126 (CUDA 12.6) |
| 传统模型 | XGBoost, scikit-learn | | 传统模型 | XGBoost 2.0+, scikit-learn 1.3+ |
| Web 后端 | Flask | | Web 后端 | Flask 3.0+ |
| 可视化 | ECharts 5.5 | | 前端 | ECharts 5.5, CSS Grid, Glassmorphism |
| 包管理 | uv | | 包管理 | uv |
| 论文 | LaTeX (XeLaTeX + ctexbook) | | 论文 | LaTeX (XeLaTeX + ctexbook), GB/T 7714 |
## 环境配置 ## 环境配置
### 系统要求 ### 系统要求
- Python 3.13 - Python 3.13
- NVIDIA GPU (推荐，RTX 4060 或以上) - NVIDIA GPU（推荐 RTX 4060+，8GB VRAM；CPU 也可运行但训练较慢）
- Windows 11 / Linux - Windows 11 / Linux
### 安装 ### 安装
```bash ```bash
# 创建虚拟环境 # 创建虚拟环境
uv venv --python "D:\settings\Language\Python\Python 3.13.13\python.exe" uv venv
# 安装依赖（含 CUDA PyTorch）
# 安装依赖 uv sync
uv pip install -e .
``` ```
### CDS API 配置（数据下载必需） ### ERA5 数据下载配置
1. 注册 Copernicus CDS 账号：https://cds.climate.copernicus.eu/ 1. 注册 Copernicus CDS 账号：https://cds.climate.copernicus.eu/
2. 获取 API Key 2. 接受 ERA5-Land 数据许可协议
3. 创建 `~/.cdsapirc`： 3. 创建 `~/.cdsapirc`：
``` ```
url: https://cds.climate.copernicus.eu/api url: https://cds.climate.copernicus.eu/api
key: <UID>:<API_KEY> key: <your-api-key>
``` ```
## 运行指南 ## 运行指南
@@ -60,115 +59,129 @@ key: <UID>:<API_KEY>
### 1. 数据获取与预处理 ### 1. 数据获取与预处理
```bash ```bash
# 下载 ERA5 气象数据（需要 CDS API 配置） # 下载 ERA5 数据（焦作+郑州，各180个月，预计耗时约5天）
python -m src.data.download_era5 python -m src.data.download_era5
# 收集死亡率与人口数据 # 解压 ZIP 格式 NetCDF 文件（CDS 新格式）
python -m src.data.collect_mortality python -m src.data.extract_zips
# 运行预处理管道 # 运行预处理管线（耗时约27分钟）
python -m src.data.preprocess python -m src.data.preprocess
``` ```
### 2. 探索性数据分析 ### 2. 模型训练与评估
```bash
jupyter notebook notebooks/eda.ipynb
```
### 3. 模型训练
```bash ```bash
# 训练 LSTM-Attention 模型 # 训练 LSTM-Attention 模型
python -m src.models.train python -m src.models.train
# 模型评估与对比 # 模型评估（含 XGBoost 训练 + 对比图表生成）
python -m src.models.evaluate python -m src.models.evaluate
``` ```
### 4. 启动可视化大屏 ### 3. 启动可视化大屏
```bash ```bash
python -m src.web.app python -m src.web.app
# 浏览器打开 http://localhost:5005 # 浏览器访问 http://localhost:5005
``` ```
### 5. 论文编译 ### 4. 编译论文
```bash ```bash
cd thesis cd thesis
make xelatex -interaction=nonstopmode main
# 或手动: xelatex main && biber main && xelatex main && xelatex main xelatex -interaction=nonstopmode main
# 或使用 Makefile: make
``` ```
## 项目结构 ## 项目结构
``` ```
project/
├── data/ ├── data/
│ ├── raw/era5/ # ERA5 原始 NetCDF 文件 │ ├── raw/era5/ # ERA5 NetCDF 文件（焦作180+郑州180）
│ ├── processed/ # 预处理后 CSV 和 NPZ 序列 │ ├── processed/ # 预处理后 NPZ 序列和 CSV 特征
│ └── external/ # 死亡率/人口/暴露反应数据 │ └── external/ # 死亡率/人口/暴露反应数据
├── src/ ├── src/
│ ├── data/ # 数据获取与预处理 │ ├── data/
│ │ ├── download_era5.py │ │ ├── download_era5.py # CDS API 下载
│ │ ├── collect_mortality.py │ │ ├── extract_zips.py # ZIP→NetCDF 解压
│ │ └── preprocess.py │ │ ├── preprocess.py # 预处理管线（597行, 8步）
│ ├── models/ # 模型定义与训练 │ │ └── collect_mortality.py # 死亡率数据整理
│ │ ├── lstm_attention.py │ ├── models/
│ │ ├── xgboost_baseline.py │ │ ├── lstm_attention.py # LSTM-Attention 模型定义
│ │ ├── train.py │ │ ├── xgboost_baseline.py # XGBoost 基线
│ │ └── evaluate.py │ │ ├── train.py # 训练脚本（365行）
│ ├── web/ # Web 可视化 │ │ └── evaluate.py # 评估脚本（295行）
│ │ ├── app.py │ ├── web/
│ │ └── static/index.html │ │ ├── app.py # Flask 后端（4 API）
│ │ └── static/index.html # ECharts 大屏（6面板）
│ └── utils/ │ └── utils/
│ └── config.py # 全局配置 │ └── config.py # 全局配置常量
├── notebooks/ ├── notebooks/
│ └── eda.ipynb # 探索性数据分析 │ └── eda.ipynb # 探索性数据分析
├── outputs/ ├── outputs/
│ ├── models/ # 训练好的模型权重 │ ├── models/ # best_model.pt (12MB)
│ ├── figures/ # 论文和评估图表 │ ├── figures/ # 混淆矩阵/模型对比图
│ └── logs/ # 训练日志 │ └── logs/ # 训练日志
├── thesis/ # LaTeX 学位论文 └── thesis/ # LaTeX 学位论文（56页）
│ ├── main.tex ├── main.tex # 主文件（~130行结构）
│ ├── chapters/ # 各章节 tex 文件 ├── chapters/ # 12个章/附录 tex 文件
│ ├── refs.bib # 参考文献 │ ├── abstract.tex
│ └── Makefile │ ├── ch1-intro.tex ~ ch7-conclusion.tex
└── docs/superpowers/ # 设计文档和计划 │ ├── references.tex
│ ├── acknowledgments.tex
│ └── appendix-*.tex # 附录A~C
└── refs.bib
``` ```
## 模型架构 ## 模型架构
``` ```
输入 (14天气象序列) 输入 (14天 × 19特征)
→ Linear 嵌入 (16 → 128) → Linear 投影 (19 → 128)
→ 2层 BiLSTM (128, dropout=0.3) → 2层 BiLSTM (128, dropout=0.3)
→ Multi-Head Attention (4 heads) → Multi-Head Self-Attention (4 heads, d_k=32)
→ Linear 投影 (256 → 128) → LSTM 投影 (256 → 128)
→ 三头输出 → 三头输出
├── 短期头 (128→64→4) ├── 短期头 (128→64→4)
├── 中期头 (128→64→4) ├── 中期头 (128→64→4)
└── 长期头 (128→64→4) └── 长期头 (128→64→4)
``` ```
总参数量：983,628
总参数量：~983K ## 实验结果
| 时间尺度 | 指标 | XGBoost | LSTM-Attention |
|---------|------|---------|----------------|
| 短期(3d) | Accuracy | **0.9908** | 0.9263 |
| 短期(3d) | F1-Macro | **0.9325** | 0.2404 |
| 中期(7d) | Accuracy | **0.9886** | 0.9259 |
| 中期(7d) | F1-Macro | **0.9195** | 0.2404 |
| 长期(30d)| Accuracy | **0.9782** | 0.9260 |
| 长期(30d)| F1-Macro | **0.8576** | 0.2404 |
XGBoost 在三个时间尺度上均大幅领先。LSTM 受限于极度类别不平衡（低风险类占94-96%），经6轮调优未收敛。
## 风险等级定义 ## 风险等级定义
| 等级 | 条件 | 颜色 | | 等级 | 体感温度 | 颜色 |
|------|------|------| |------|---------|------|
| 低风险 | 体感温度 < 32°C | 绿 | | 0级 低风险 | HI < 32°C | 绿 |
| 中风险 | 体感温度 32-35°C | 黄 | | 1级 中风险 | 32 ≤ HI < 35°C | 黄 |
| 高风险 | 体感温度 35-38°C 或连续 3 天 >35°C | 橙 | | 2级 高风险 | 35 ≤ HI < 38°C | 橙 |
| 严重风险 | 体感温度 >= 38°C 且连续 3 天 >35°C | 红 | | 3级 严重风险 | HI ≥ 38°C | 红 |
## 数据来源 ## 数据来源
| 数据 | 来源 | 时间范围 | | 数据 | 来源 | 时间范围 |
|------|------|----------| |------|------|----------|
| 气象数据 | ERA5-Land (Copernicus CDS) | 2010-2024 | | 气象数据 | ERA5-Land (Copernicus CDS) | 2010-2024 |
| 死亡率 | 中国卫生健康统计年鉴 | 2010-2023 | | 体感温度 | NOAA Rothfusz 公式 | — |
| 暴露反应曲线 | Chen et al. (2018) Lancet Planet Health | — | | 相对湿度 | Magnus 公式 | — |
| 暴露反应曲线 | Chen et al. (2018) Lancet Planetary Health | — |
| 人口数据 | 第七次全国人口普查 (2020) | 2020 | | 人口数据 | 第七次全国人口普查 (2020) | 2020 |
| 老龄化率 | 河南省统计年鉴 | 2010-2023 |
## 仓库
https://lhy-git.liuhangyv.top/Serendipity/elderly-heat-warning