gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Detail multi-model consensus scoring, Open-Meteo API architecture, airport-aligned NWP queries, and ensemble divergence detection.

Browse Source
This commit is contained in:
AmandaloveYang
2026-02-22 10:01:32 +08:00
parent 6cc16c938d
commit f1d1279ac6
2 changed files with 99 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -10
View File
@@ -98,29 +98,63 @@ py -3.11 run.py
| Source | Role | Coverage | Strength |
| :---------------------- | :---------------------- | :-------------- | :-------------------------------------------------------------------------- |
| **Multi-Model (5 NWP)** | **Consensus Scoring** | Global | ECMWF, GFS, ICON, GEM, JMA — 5 fully independent NWP models via Open-Meteo |
| **Open-Meteo** | Base Forecast | Global | 72h hourly curves, sunrise/sunset, **sunshine duration**, **shortwave radiation** |
| **Open-Meteo Ensemble** | **Uncertainty Range** | Global | 51-member ensemble: median, P10, P90 spread for confidence assessment |
| **Meteoblue (MB)** | **Precision Consensus** | London Only | Multi-model aggregation; excellent for microclimates |
| **Meteoblue (MB)** | Precision Consensus | London Only | Multi-model aggregation; excellent for microclimates |
| **METAR** | **Settlement Standard** | Global Airports | Polymarket settlement source; real-time airport observations |
| **NWS** | Official (US) | US Only | US National Weather Service high-fidelity forecasts |
| **MGM** | Official (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall |
| **MGM** | Observations (Turkey) | Ankara Only | Turkish State Met Service: pressure, cloud cover, feels-like, 24h rainfall |
> ⚠️ **All NWP model queries use airport coordinates** (matching METAR station), not city center. This eliminates systematic bias between forecast and settlement locations.
**Open-Meteo API Architecture**: Three API calls go through the same platform, each serving a different purpose:
```
Open-Meteo (API Platform)
│
┌─────────────┼─────────────┐
│ │ │
┌──────┴──────┐ │ ┌──────┴──────┐
│ /forecast │ │ │ /forecast │
│ (default) │ │ │ ?models=... │
│ = best_match│ │ │ = multi-model│
└──────┬──────┘ │ └──────┬──────┘
│ │ │
▼ │ ▼
Auto-selects best │ Returns each model
model (≈ ECMWF) │ ECMWF / GFS / ICON
→ Hourly curves │ GEM / JMA
→ Sunrise/sunset │ → Consensus scoring
→ Sunshine/radiation │
┌──────┴──────┐
│ /ensemble │
│ 51 members │
└──────┬──────┘
│
▼
Median / P10 / P90
→ Uncertainty range
```
> 💡 The OM default forecast is essentially **one of the 5 models** (auto-selected), so it is **excluded from consensus scoring** to avoid double-counting.
### 2. ⚡ Ultra-Fresh Data (Zero-Cache)
- **Dynamic Timestamps**: Every API request includes a unique token to force servers to bypass CDN caches.
- **MGM Real-time Sync**: Specialized header camouflaging and timezone correction for Turkish API.
### 3. 🎯 Model Consensus Scoring (NEW)
### 3. 🎯 Multi-Model Consensus Scoring
The bot automatically rates how well different forecast sources agree, using a three-tier system:
The bot queries **5 independent NWP models** (ECMWF, GFS, ICON, GEM, JMA) to rate forecast agreement:
| Level | Condition (°C / °F) | Meaning |
|:---|:---|:---|
| 🎯 **High** | Spread ≤ 0.8°C / 1.5°F | All models converge — high confidence, low risk |
| 🎯 **High** | Spread ≤ 0.8°C / 1.5°F | All 5 models converge — high confidence, low risk |
| ⚖️ **Medium** | Spread ≤ 1.5°C / 3.0°F | Minor disagreement — moderate confidence |
| ⚠️ **Low** | Spread > 1.5°C / 3.0°F | Major divergence — high uncertainty, wait for more data |
Sources compared: Open-Meteo (OM), Meteoblue (MB), NWS, MGM — only **independent** forecast sources. Ensemble median is deliberately excluded to avoid double-counting with Open-Meteo.
Primary models: **ECMWF IFS** (Europe), **GFS** (US NOAA), **ICON** (Germany DWD), **GEM** (Canada), **JMA** (Japan). Plus Meteoblue (London) and NWS (US) when available. Ensemble median is excluded to avoid double-counting.
### 4. 📊 Ensemble Forecast Spread (NEW)
@@ -130,6 +164,8 @@ Fetches 51-member ensemble forecasts from Open-Meteo to quantify prediction unce
A tight range = high confidence in the forecast. A wide range = the atmosphere is chaotic, higher risk.
**Deterministic vs Ensemble Divergence Detection**: When the OM deterministic forecast exceeds the ensemble P90 or falls below P10, the bot flags it. If actual observations later verify the forecast, the warning upgrades to a ✅ **Forecast Verified** message.
### 5. ⏰ Entry Timing Signal (NEW)
A composite score combining three factors to advise on betting timing:
@@ -190,11 +226,12 @@ graph TD
Bot --> Collector[WeatherDataCollector]
subgraph "Data Engine"
Collector --> OM[Open-Meteo API]
Collector --> MM[Multi-Model API<br/>ECMWF/GFS/ICON/GEM/JMA]
Collector --> OM[Open-Meteo Forecast]
Collector --> ENS[Open-Meteo Ensemble]
Collector --> MB[Meteoblue API]
Collector --> NOAA[METAR / NOAA]
Collector --> MGM[Turkish MGM API]
Collector --> MGM[MGM Observations]
Collector --> NWS[US NWS API]
end
@@ -205,7 +242,9 @@ graph TD
- **Logic Decoupling**: `weather_sources.py` handles data fetching & parsing; `bot_listener.py` handles analysis & rendering.
- **City Config**: `city_risk_profiles.py` contains all METAR station mappings and risk assessments.
- **Ensemble Integration**: 51-member ensemble contributes to consensus scoring and provides P10/P90 uncertainty bands.
- **Multi-Model Consensus**: 5 independent NWP models (ECMWF, GFS, ICON, GEM, JMA) for robust consensus scoring.
- **Ensemble Integration**: 51-member ensemble provides P10/P90 uncertainty bands and divergence detection.
- **Airport-Aligned Coordinates**: All NWP queries target METAR station coordinates, not city centers.
---
@@ -222,4 +261,4 @@ graph TD
---
_Last updated: 2026-02-21_
_Last updated: 2026-02-22_
README_ZH.md
+50 -11
View File
@@ -98,31 +98,65 @@ py -3.11 run.py
| 数据源 | 数据角色 | 覆盖范围 | 优势 |
| :---------------------- | :------------- | :--------- | :----------------------------------------------------------- |
| **多模型 (5 NWP)** | **共识评分** | 全球 | ECMWF、GFS、ICON、GEM、JMA — 5 个完全独立的数值预报模型，经 Open-Meteo 统一获取 |
| **Open-Meteo** | 基础预测 | 全球 | 72h 逐小时温度曲线、日出日落、**日照时长**、**短波辐射** |
| **Open-Meteo Ensemble** | **不确定性区间** | 全球 | 51 成员集合预报：中位数、P10、P90 散度用于置信度评估 |
| **Meteoblue (MB)** | **高精度共识** | 仅限伦敦 | 聚合多家模型，对微气候处理极佳 |
| **Meteoblue (MB)** | 高精度共识 | 仅限伦敦 | 聚合多家模型，对微气候处理极佳 |
| **METAR** | **结算标准** | 全球机场 | Polymarket 结算参考的绝对真理，实时机场观测 |
| **NWS** | 官方预测(美) | 仅限美国 | 美国国家气象局高精度预报 |
| **MGM** | 官方预测(土) | 仅限安卡拉 | 土耳其气象局：气压、云量、体感温度、24h 降水 |
| **MGM** | 实测数据(土) | 仅限安卡拉 | 土耳其气象局：气压、云量、体感温度、24h 降水 |
> ⚠️ **所有 NWP 模型查询使用机场坐标**（与 METAR 站点一致），而非市中心。这消除了预报位置与结算位置之间的系统性偏差。
**Open-Meteo API 架构关系**：三个 API 调用都经过 Open-Meteo 平台，但获取的是不同维度的数据：
```
Open-Meteo (API 平台)
│
┌─────────────┼─────────────┐
│ │ │
┌──────┴──────┐ │ ┌──────┴──────┐
│ /forecast │ │ │ /forecast │
│ (默认模式) │ │ │ ?models=... │
│ = best_match│ │ │ = 多模型模式 │
└──────┬──────┘ │ └──────┬──────┘
│ │ │
▼ │ ▼
自动选最佳模型 │ 返回每个模型单独结果
(通常 ≈ ECMWF) │ ECMWF / GFS / ICON
→ 逐小时曲线 │ GEM / JMA
→ 日出日落 │ → 共识评分
→ 日照/辐射 │
┌──────┴──────┐
│ /ensemble │
│ 51成员集合 │
└──────┬──────┘
│
▼
中位数 / P10 / P90
→ 不确定性区间
```
> 💡 OM 默认预报本质上是 5 个模型中的**某一个**（自动选择），因此**不参与共识评分**，避免双重计数。
### 2. ⚡ 超新鲜数据 (零缓存)
- **动态时间戳**：每个 API 请求都附带唯一令牌，强制服务器绕过 CDN 缓存。
- **MGM 实时同步**：针对土耳其 MGM API 做了专门的 Header 伪装和时区校正。
### 3. 🎯 模型共识评分（新功能）
### 3. 🎯 多模型共识评分
机器人自动评估各预报源的一致程度，分为三个等级：
机器人同时查询 **5 个独立 NWP 模型**（ECMWF、GFS、ICON、GEM、JMA）来评估预报一致性：
| 等级 | 条件（摄氏/华氏） | 含义 |
|:---|:---|:---|
| 🎯 **高共识** | 极差 ≤ 0.8°C / 1.5°F | 所有模型高度收敛 — 高置信，低风险 |
| 🎯 **高共识** | 极差 ≤ 0.8°C / 1.5°F | 5 个模型高度收敛 — 高置信，低风险 |
| ⚖️ **中共识** | 极差 ≤ 1.5°C / 3.0°F | 轻微分歧 — 中等置信 |
| ⚠️ **低共识** | 极差 > 1.5°C / 3.0°F | 模型严重分歧 — 不确定性大，建议观察 |
参与评分的数据源：Open-Meteo (OM)、Meteoblue (MB)、NWS、MGM — 仅限**独立**预报源。集合预报中位数不参与共识评分，避免与 Open-Meteo 确定性预报双重计数。
主要模型：**ECMWF IFS**（欧洲）、**GFS**（美国 NOAA）、**ICON**（德国 DWD）、**GEM**（加拿大）、**JMA**（日本）。伦敦额外有 Meteoblue，美国城市额外有 NWS。集合预报中位数不参与评分，避免双重计数。
**核心逻辑**：当 3 个及以上模型在温度区间上高度收敛，而市场定价尚未反映时，这就是典型的**结构性定价错误**——低风险套利的黄金机会。
**核心逻辑**：当 5 个独立模型在温度区间上高度收敛，而市场定价尚未反映时，这就是典型的**结构性定价错误**——低风险套利的黄金机会。
### 4. 📊 集合预报散度（新功能）
@@ -132,6 +166,8 @@ py -3.11 run.py
区间窄 = 大气状态明确，预报可信。区间宽 = 大气混沌，风险高。
**确定性 vs 集合偏差检测**：当 OM 确定性预报超过集合 P90 或低于 P10 时，机器人会发出警告。如果实测数据随后验证了预报，警告会升级为 ✅ **预报验证** 消息。
### 5. ⏰ 入场时机信号（新功能）
综合三个因子打分，给出入场建议：
@@ -195,11 +231,12 @@ graph TD
Bot --> Collector[WeatherDataCollector]
subgraph "数据引擎"
Collector --> OM[Open-Meteo API]
Collector --> MM[多模型 API<br/>ECMWF/GFS/ICON/GEM/JMA]
Collector --> OM[Open-Meteo 预报]
Collector --> ENS[Open-Meteo Ensemble]
Collector --> MB[Meteoblue API]
Collector --> NOAA[METAR / NOAA]
Collector --> MGM[Turkish MGM API]
Collector --> MGM[MGM 实测数据]
Collector --> NWS[US NWS API]
end
@@ -210,7 +247,9 @@ graph TD
- **逻辑解耦**：`weather_sources.py` 负责数据获取与解析；`bot_listener.py` 负责分析与渲染。
- **城市配置**：`city_risk_profiles.py` 包含所有 METAR 机场映射和风险评估。
- **集合预报集成**：51 成员集合预报参与共识评分，并提供 P10/P90 不确定性区间。
- **多模型共识**：5 个独立 NWP 模型（ECMWF、GFS、ICON、GEM、JMA）提供稳健的共识评分。
- **集合预报集成**：51 成员集合预报提供 P10/P90 不确定性区间和偏差检测。
- **机场坐标对齐**：所有 NWP 查询均使用 METAR 机场坐标，而非市中心。
---
@@ -227,4 +266,4 @@ graph TD
---
_最后更新: 2026-02-21_
_最后更新: 2026-02-22_