# Hướng dẫn nghiệp vụ — Dự báo xác suất ngày nắng nóng cực đoan (EHD) hạn dài cho Việt Nam

*Tài liệu dành cho dự báo viên trực ca. Bản tiếng Việt là bản chính; phần tóm tắt tiếng Anh
ở cuối (English summary at the end). Cơ sở khoa học và toàn bộ điểm số kiểm định: xem
`docs/RESULTS_REPORT.md`. Mọi con số truy vết được về file nguồn trong "Evidence pack" của báo cáo đó.*

---

## 0. Sản phẩm này là gì

Dự báo **xác suất có ngày nắng nóng cực đoan (Extreme-Heat Day — EHD)** trên lưới 0,25° toàn
Việt Nam, hạn tới **45 ngày** kể từ thời điểm khởi chạy (init).

- Một ngày được coi là **EHD** khi: `Tx ≥ min(Tx90p, 35 °C)`
  (Tx = nhiệt độ tối cao ngày; Tx90p = phân vị 90 của Tx quan trắc theo ngày lịch, cơ sở
  2002–2023, cửa sổ 15 ngày quanh ngày lịch). Quy tắc `min(...)` là **cố định theo yêu cầu** —
  không thay bằng biến thể `max(Tx90p,35)` (biến thể đó chỉ dùng để chẩn đoán).
- Dự báo gộp thành **6 khối hạn cố định, không chồng lấn** (ngày kể từ init):
  **W1** 0–10 · **W2** 11–17 · **W3** 18–24 · **W4** 25–31 · **W5** 32–38 · **W6** 39–45.
- Sản phẩm chính: `prob_ehd` = **P(có ≥1 ngày EHD trong khối)**.
- Sản phẩm nhị phân: `ehd_flag` = 1 khi xác suất ≥ ngưỡng quyết định của **vùng** đó
  (ngưỡng tối ưu theo điểm Peirce, riêng cho từng vùng × khối).

Mỗi lần init sinh **một file NetCDF tuân chuẩn CF** với `prob_ehd(block,lat,lon)` và
`ehd_flag(block,lat,lon)`, lưu tại `outputs/operational/ehd_product_<YYYYMMDD>.nc`.

---

## 1. Khả năng dự báo thực tế — ĐỌC TRƯỚC KHI PHÁT BÁO

Kỹ năng (skill) đã được kiểm định chéo bỏ-một-năm (LOYO) trên 20 năm 2003–2022. Kết luận cốt lõi,
**tính trung bình toàn quốc gộp chung** (Brier Skill Score so với khí hậu; xem
`results/tables/cv_scores_by_block.csv`):

| Khối | Hạn (ngày) | BSS so khí hậu | Ý nghĩa thống kê | Khuyến nghị sử dụng |
|------|-----------|----------------|------------------|---------------------|
| W1 | 0–10  | 0,356 | Có | **Tin cậy** — dùng trực tiếp |
| W2 | 11–17 | 0,118 | Có | **Tốt** — dùng được |
| W3 | 18–24 | 0,037 | Có (biên) | **Thận trọng** — chỉ ra xu thế, nhất là miền Nam / mùa MAM |
| W4 | 25–31 | 0,014 | Không | **Không hơn khí hậu** trung bình toàn quốc |
| W5 | 32–38 | 0,004 | Không | Như trên |
| W6 | 39–45 | −0,006 | Không | Như trên |

**Câu chốt:** sản phẩm hiệu chỉnh có kỹ năng vượt khí hậu **đến hết W3 (ngày 24)**; từ W4 trở đi
(ngày ≥ 25) **không phân biệt được với khí hậu** trên trung bình toàn quốc. AUC vẫn > 0,5 ở mọi
hạn (khả năng phân biệt yếu còn tồn tại) nhưng kỹ năng xác suất (BSS) về 0 ở W4.

### Kỹ năng phụ thuộc VÙNG và MÙA (rất quan trọng khi diễn giải W3–W6)
- **Miền Nam (Tây Nguyên, Nam Bộ):** giữ kỹ năng lâu hơn — còn dương ở W4–W6. Chân trời hữu
  ích ≈ **W3+**.
- **Miền Bắc (R1–R3):** kỹ năng hết từ W3, hơi âm ở W3–W6. Chân trời hữu ích ≈ **W2**.
- **Mùa MAM (tiền gió mùa, cao điểm nắng nóng):** mùa **dễ dự báo nhất ở hạn dài** — mùa duy nhất
  còn BSS dương đến W6. DJF và JJA mất kỹ năng từ W3.

⇒ Sản phẩm đáng tin ở hạn dài **đúng vào mùa MAM và ở miền Nam** — cũng là nơi/lúc nắng nóng cực
đoan nguy hại nhất. Nguồn: `cv_scores_by_region_block.csv`, `cv_scores_by_season_block.csv`.

### Cảnh báo về cờ nhị phân `ehd_flag`
Ở hạn dài, cờ nhị phân **dự báo thừa** (frequency bias 1,2–1,6 ở W4–W6). **Luôn đọc cờ cùng với
trường xác suất `prob_ehd`** và bảng kỹ năng §1 ở trên — không dùng cờ một mình cho W4–W6.

---

## 2. Quy trình chạy nghiệp vụ

```bash
conda activate ehd     # /home/tanpv/.conda/envs/ehd, Python 3.11
cd /home/tanpv/Progs/claude/QG_1
```

### 2.1 Huấn luyện mô hình sản xuất (chạy MỘT LẦN, hoặc khi cập nhật cơ sở)
```bash
python scripts/10_operational_product.py train
```
Khớp mô hình sản xuất trên **toàn bộ 20 năm**: trường ngưỡng Tx90p cả kỳ, một bộ HGB + hiệu chỉnh
isotonic mỗi khối, và ngưỡng quyết định Peirce theo vùng × khối. Kết quả lưu ở
`outputs/production_model/` (`ehd_production_model.joblib`, `tx90p_threshold.nc`, `manifest.json`).

> Lưu ý về kỹ năng: đây là bản khớp-lại-trên-toàn-bộ để **triển khai**. Kỹ năng trung thực của nó
> là ước lượng LOYO ở §1, **không** phải điểm khớp trong mẫu.

### 2.2 Sinh sản phẩm cho một nguồn dự báo
```bash
python scripts/10_operational_product.py produce --year YYYY
# tuỳ chọn: --max-inits N   (giới hạn số init, dùng để thử nghiệm)
```
Chấm điểm mọi init trong file dự báo của năm YYYY qua mô hình đã lưu và ghi một NetCDF/ init vào
`outputs/operational/ehd_product_<YYYYMMDD>.nc`.

### 2.3 Kiểm tra nhanh một file sản phẩm
```bash
python -c "import xarray as xr; ds=xr.open_dataset('outputs/operational/ehd_product_20220102.nc'); print(ds)"
```
Kỳ vọng: dims `block=6, lat=65, lon=41`; `Conventions='CF-1.8'`; `prob_ehd` trong [0,1];
`ehd_flag` ∈ {0,1} trên đất liền, `NaN`/`-1` ngoài biển.

---

## 3. Đọc file sản phẩm

| Biến / toạ độ | Ý nghĩa |
|---------------|---------|
| `prob_ehd(block,lat,lon)` | Xác suất có ≥1 ngày EHD trong khối. Biển = `NaN`. |
| `ehd_flag(block,lat,lon)` | 1 = xác suất ≥ ngưỡng quyết định vùng; 0 = dưới ngưỡng; `-1`/`NaN` = biển. |
| `block` (1..6) | Chỉ số khối; tên khối ở thuộc tính `block_names`. |
| `block_day_start/end` | Ngày hạn đầu/cuối của khối (ngày sau init). |
| `init` | Ngày khởi chạy dự báo (forecast_reference_time). |
| thuộc tính toàn cục | `comment` ghi định nghĩa EHD, cơ sở Tx90p; `model_version`, `family`. |

**Diễn giải cho người dùng cuối:** `prob_ehd` cao ở W1–W2 = tín hiệu mạnh, dùng được. Ở W3 xem
như xu thế (ưu tiên miền Nam / mùa MAM). Ở W4–W6: chỉ tham khảo bối cảnh, **không** phát cảnh báo
dựa riêng vào cờ.

---

## 4. Đường chạy thời gian thực (real-time) — BẮT BUỘC đọc

Mô hình dùng đặc trưng từ **một thành phần điều khiển (control, 1 member)** — vì reforecast chỉ có
control. Khi chạy real-time:

1. **Cấp đúng một thành phần control**, dựng **giống hệt** lúc huấn luyện:
   daily Tx = max của 4 giá trị `mx2t6` 6-giờ; **bỏ 29/2**; khớp theo (tháng, ngày).
2. Nếu bản real-time là **tổ hợp (ensemble)**: rút về **control/trung bình** trước khi đưa vào mô
   hình. **Không** dùng tỷ lệ vượt ngưỡng của tổ hợp làm P(EHD).
3. **Kiểm tra phiên bản mô hình** vận hành có khớp với reforecast dùng để hiệu chỉnh không; nếu
   lệch, **ghi rõ trong báo cáo** (đây là hạn chế đã biết — xem MEMORY.md L-01).
4. Lưới dự báo đã ở 0,25° trùng lưới quan trắc — **không có bước hạ quy mô** (nội suy thượng nguồn
   là hạn chế đã ghi nhận).

---

## 5. Hạn chế cần nêu khi phát báo / trong báo cáo

1. **Không có tổ hợp** — xác suất từ MOS đơn thành phần, không phải độ tán tổ hợp.
2. **Nội suy thượng nguồn về 0,25°** đã nằm trong dữ liệu, không thể gỡ.
3. **Trạm ấm hơn ô lưới +1,5…+2,2 °C** → rủi ro EHD điểm-trạm cao hơn sản phẩm lưới (dùng trạm làm
   kiểm chứng độc lập, không phải mục tiêu; xem `docs/OBS_RECONCILIATION.md`).
4. **Chân trời kỹ năng ngắn** — W1–W3 gộp, phụ thuộc vùng/mùa; W4–W6 tương đương khí hậu trên trung
   bình toàn quốc.
5. **Cờ nhị phân dự báo thừa ở hạn dài** (frequency bias > 1) — đọc cùng điểm số.
6. **Shapefile vùng `7,NB_region.shp` bị hỏng** — bản đồ dùng mask lưới `reg` + đường bờ biển.

---

## 6. Xử lý sự cố nhanh

| Triệu chứng | Nguyên nhân / cách xử lý |
|-------------|--------------------------|
| `produce` báo thiếu model | Chưa chạy `train`; chạy `10_operational_product.py train` trước. |
| Mở NetCDF lỗi giải mã thời gian | File cũ sinh trước bản vá đơn vị khối; sinh lại bằng `produce`. |
| `prob_ehd` toàn NaN | Sai năm / thiếu `outputs/forecast_daily_tx/fc_daily_tx_<year>.nc`. |
| Muốn kiểm chứng lại điểm số cốt lõi | Chạy `scripts/11_independent_validator.py` (in PASS/FAIL). |
| Nghi ngờ rò rỉ dữ liệu (leakage) | Quy tắc leakage ở CLAUDE.md; validator §7 báo cáo tự kiểm tra. |

---

## English summary

**Product.** Calibrated S2S probability of an **extreme-heat day (EHD)** over Vietnam on the 0.25°
grid, to 45 days lead. EHD ⇔ `Tx ≥ min(Tx90p, 35 °C)`. Aggregated into six fixed lead blocks
(W1 0–10 … W6 39–45 days). Each init → one CF-NetCDF `ehd_product_<YYYYMMDD>.nc` with
`prob_ehd(block,lat,lon)` (P of ≥1 EHD in the block) and `ehd_flag` (prob ≥ the region's
Peirce-optimal decision threshold).

**Trustworthy horizon (LOYO cross-validation, BSS vs climatology).** Significant skill **through W3
(day 24)**; W4–W6 are climatology-equivalent on the national pooled mean. Skill is **region- and
season-dependent**: the tropical **south** keeps skill to W4–W6 and the **MAM** pre-monsoon season
is the most predictable at long range (positive BSS to W6), while the **north** loses skill by W3.
The binary flag **over-forecasts at long lead** (frequency bias 1.2–1.6 at W4–W6) — always read it
together with `prob_ehd` and the skill table, never alone beyond W3.

**Run.** `conda activate ehd`; then
`python scripts/10_operational_product.py train` (once) and
`python scripts/10_operational_product.py produce --year YYYY`.
Validate the headline numbers anytime with `python scripts/11_independent_validator.py`.

**Real-time.** The model consumes a single **control** member built exactly as in training (daily
Tx = max of four 6-hourly `mx2t6`, drop 29 Feb, match on month/day). Reduce any real-time ensemble
to the control/mean first; check the operational model version matches the reforecast and document
any mismatch.

**Limitations.** Control-only (single-member MOS, no ensemble spread); upstream 0.25° interpolation
baked in (no downscaling); stations run +1.5…+2.2 °C warmer than their grid cell; short skill
horizon; long-lead flag over-forecasts. Full evidence and scores: `docs/RESULTS_REPORT.md`.