lopezalmeidaalvaro/DataDriven-Weather-Demand
GitHub: lopezalmeidaalvaro/DataDriven-Weather-Demand
一个面向酒店收益管理的数据工程项目，通过自动化ETL管道和统计建模，验证天气异常对预订需求的实际影响，帮助酒店基于数据而非直觉制定定价策略。
Stars: 0 | Forks: 0
# 🏝️ 数据驱动的收益管理：气象因素对酒店需求的影响
### *酒店行业端到端 ETL 与统计分析管道（大加那利岛）*
    
## 🎯 1. 业务背景与问题陈述
在酒店行业，定价弹性模型往往受到启发式偏见或“直觉”的影响，而非基于实证数据。加那利群岛的酒店总经理们普遍认为 **Calima（撒哈拉尘暴）事件会显著降低最后一刻预订的需求**。
这一假设历史上导致了：
1. **反应性低价抛售：** 为刺激感知中的低需求而不必要地降低 ADR（平均每日房价）。
2. **低效的 CAC（获客成本）：** 将营销预算重新分配给“恐慌性”营销活动。
3. **收益不稳定：** 基于气象警报而非实际预订进度导致的利润侵蚀。
**目标：** 构建一个可复用的数据管道，通过编程方式提取、清洗并关联外部气象数据与内部预订指标，以验证或反驳这一假设。
## 🏗️ 2. 数据管道架构 (ETL)
本项目依赖于一个可编程的 **Extract-Transform-Load (ETL)** 管道，该管道设计具有幂等性，并能抵御脏数据的影响。
```
graph TD
%% Sources
A[AEMET OpenData API] -->|JSON| B(extract_aemet_api.py)
C[ISTAC Microdata] -->|CSV| D(etl_pipeline_analytics.py)
%% Storage
B -->|Raw Data| E[(data/raw/)]
D -->|Raw Data| E
%% Processing & Quality
E --> F{Data Quality Gate}
F -->|Validation Fail| G[Logging & Halt]
F -->|Validation Pass| H[Transformation & Harmonization]
%% Engineering
H --> I[Dynamic Thresholding Algorithm]
I --> J[Analytical Dataset - Parquet]
%% Output
J --> K[Statistical Modeling - Pearson R]
K --> L[Executive Insights / ADR Protection]
style F fill:#f96,stroke:#333,stroke-width:2px
style G fill:#f66,stroke:#333,stroke-width:2px
```
#### **A. 数据提取与摄入**
* **气象数据 (AEMET API):** 从 **C629X (Puerto de Mogán)** 站点自动提取每日时间序列数据。实施了指数退避策略和批量请求处理，以严格遵守 API 速率限制并确保 100% 的摄入成功率。
* **旅游微数据 (ISTAC):** 高保真摄入交易性调查数据（>3,500 条记录）。数据经过编程过滤，仅保留 **大加那利岛的四星级酒店细分市场**，以确保与特定业务竞争集保持一致。
#### **B. 转换与数据完整性策略**
* **数据协调：** 将欧洲数字格式和区域设置标准化为 IEEE 754 浮点变量，以实现跨平台兼容性。
* **空值处理与聚合：** 实施严格的计数逻辑以处理不同季度间报告不一致的 ID。通过将记录存在性与指标可用性解耦，管道防止了因稀疏调查回复而产生的偏差平均值。
* **关系合并：** 跨不同的时间维度（月/OLA）执行多键 Left Join，确保来自主要业务指标（即“黄金记录”）的数据不丢失。
## 🛡️ 3. 数据质量与可靠性（数据契约）
```
graph LR
Input[Data Input] --> Raw[Raw Check: Nulls & Types]
Raw --> Domain[Domain Check: T > -5ºC & RH < 100%]
Domain --> Outlier[Outlier Detection: Z-Score > 3]
Outlier -->|Valid| Analytics[Process for Pearson]
Outlier -->|Invalid| Log[Log Incident & Sanitize]
```
统计模型的质量取决于输入数据的质量（**Garbage In, Garbage Out**）。为了确保 Pearson 相关系数 ($r$) 的完整性，管道在任何分析处理发生之前实施了多层 **数据质量门控**：
* **模式强制与漂移保护：** 系统验证强制维度（`tmax`、`fecha`、`hrMin`）和指标的存在性。这充当了一种契约，确保如果 AEMET API 或 ISTAC 微数据结构发生变化，管道会附带描述性错误而显式失败，而不是产生静默的损坏结果。
* **物理领域约束：** 我们应用了针对加那利群岛亚热带气候的气象逻辑。
* $T_{max}$ 必须位于 [-5°C, 55°C] 范围内。
* 相对湿度 ($RH$) 严格在 [0, 100] 范围内进行验证。
* 超出这些界限的记录被标记为传感器故障并进行清洗，以防止离群值偏差。
* **可靠性阈值（空值处理）：** 管道监控“信噪比”。如果时间序列识别出超过 10% 的缺失值（**严重空值**），执行将停止。这可以防止月度平均值因不完整的时间窗口而产生偏差。
* **幂等提取：** `extract_aemet_api.py` 脚本设计为幂等的。它会在发起网络请求之前验证 `data/raw/` 目录的本地状态，保护 API 配额并确保管道可以在任何环境中安全地重新运行。
## 🧠 4. 高级特征工程：动态异常检测
静态温度阈值（例如 $T > 27.5^\circ C$）在亚热带气候中在统计上是不可靠的，因为存在严重的 **季节性偏差**（在 8 月份会产生 100% 的假阳性）。
为了分离 *真正的* 撒哈拉尘暴入侵，我设计了一种 **动态阈值算法**。当且仅当某月 $m$ 中的某天 $i$ 超过其特定月份的历史滚动平均值，并结合湿度的急剧下降时，才会被标记为 Calima 异常 ($C_i$)：
$$
C_i = (T_{max, i} \ge \bar{T}_{max, m} + 4.5^\circ C) \land (RH_{min, i} \le 55\text{\%})
$$
*其中：*
* $\bar{T}_{max, m}$ = 月度滚动平均最高温度。
* 这种动态启发式方法成功过滤掉了夏季热浪，准确隔离了真正的尘暴事件，并提高了数据集的信噪比。
## 🧮 5. 统计建模与结果
我们使用 **Pearson 相关系数** 评估了 Calima 日 ($X$) 与最后一刻预订比率 ($Y$) 之间的关系：
$$
r = \frac{\sum (X_i - \bar{X})(Y_i - \bar{Y})}{\sqrt{\sum (X_i - \bar{X})^2 \sum (Y_i - \bar{Y})^2}}
$$
#### 📊 执行摘要与业务影响
与行业“直觉”相反，数据表明预订行为对短期不利气象事件具有 **刚性**。
| 指标 | 结果 | 解释 | 收益行动 |
| :--- | :--- | :--- | :--- |
| **Pearson (r)** | `0.268` | 弱正相关 | **维持 ADR：** 不要降价。 |
| **P-Value** | `0.40` | 无统计显著性 | **避免误报：** 忽略天气警报。 |
| **弹性** | **无弹性** | 客户忽略尘暴 | **避免反应性折扣。** |
**科学复盘：** 尽管 $r = 0.2678$ 暗示了微弱的正相关，但 $p\text{-value}$ 为 $0.40$ 表明在当前样本量下无法拒绝零假设。这证实了收益经理应优先考虑预订进度而非气象警报，因为与季节性趋势相比，天气影响在统计上可以忽略不计。
## 📂 6. 仓库结构
```
DataDriven-Weather-Demand/
├── .venv/ # Auto-generated isolated virtual environment
├── data/
│ └── raw/ # Source CSVs (ISTAC & AEMET)
├── docs/
│ ├── executive_summary.md # Business-facing insights
│ ├── personal_study_notes.md # Personal study guide
│ └── technical_annex.md # Mathematical proofs & methodology
├── scripts/
│ ├── etl_pipeline_analytics.py # Main ETL logic with Data Quality Gates
│ └── extract_aemet_api.py # Idempotent API extraction script
├── .env.example # Template for API credentials
├── .gitignore # Ensures .venv and secrets are not tracked
├── .python-version # Defines exact Python interpreter (3.12+)
├── pyproject.toml # Project metadata & dependency definitions
├── uv.lock # Deterministic lockfile for 100% reproducibility
└── README.md # Core project documentation
```
## 🚀 7. 可复现性与安装
本项目使用 **`uv`**（下一代 Python 包管理器）来确保 100% 可复现的执行环境。通过利用 `uv.lock` 文件，我们消除了“依赖地狱”，并保证管道在任何机器或操作系统上的运行完全一致。
### 安装与执行
1. **克隆仓库：**
git clone [https://github.com/lopezalmeidaalvaro/DataDriven-Weather-Demand.git](https://github.com/lopezalmeidaalvaro/DataDriven-Weather-Demand.git)
cd DataDriven-Weather-Demand
2. **同步环境：**
如果你已安装 uv，只需运行：
```
uv sync
```
此命令会自动创建一个虚拟环境 并在几毫秒内安装所有依赖项（Pandas、Requests 等）的确切版本。
3. **运行数据管道：**
```
uv run scripts/etl_pipeline_analytics.py
```
工程说明：对于旧环境，可以使用 `uv export --format requirements-txt > requirements.txt` 生成标准的 requirements.txt，尽管使用原生 uv.lock 是确定性构建推荐的专业标准。
### ⚖️ 8. 工程权衡
作为一名资深工程师，每一个技术选择都是一种妥协。以下是本架构中所做的 *权衡*：
* **Pandas vs. Polars:** 选择 **Pandas** 是因为它与 `scipy.stats` 进行 Pearson 系数和 P 值计算的成熟原生集成。对于超过 10GB 的数据集，该架构设计为通过抽象验证模式来切换到 **Polars**。
* **本地 Parquet vs. SQL:** 没有使用沉重的关系型数据库，而是使用 **Parquet** 进行中间存储。这允许高效的列式压缩，并且对于分析工作负载，I/O 读取速度比 CSV/SQLite 快约 40%。
* **运行时验证 vs. 自动修补：** 我优先考虑 **“快速失败”** 方法，而不是自动数据清洗。如果 AEMET 数据违反契约（例如，湿度 > 100%），管道将停止。这确保了最终的相关系数 100% 可靠，避免了“修补”或合成数据的偏差。
## 🔮 9. 未来扩展性（后续步骤）
要将此概念验证扩展为企业级产品：
* **云端编排：** 将 Python 脚本迁移到 Apache Airflow（或 AWS Step Functions）以进行自动化每日运行和监控。
* **机器学习：** 整合航班定价数据 (AENA) 以训练 Random Forest 回归器，通过结合天气异常和连通性因素准确预测最后一刻的需求量。
👨💻 架构与开发：Álvaro López Almeida
Capstone 项目 — 数据工程与收益分析
标签：AEMET API, ETL管道, ISTAC, Python, REST API集成, RevPAR优化, 加那利群岛, 平均房价(ADR), 异常检测, 弹性分析, 撒哈拉沙尘, 数据工程, 数据科学项目, 数据驱动决策, 旅游业分析, 无后门, 时序数据分析, 格兰加那利, 气象数据分析, 统计相关性分析, 自动化数据流, 获客成本(CAC), 逆向工具, 酒店收益管理, 酒店预订需求