# #1124 Forecast Experiment 구조 설계 v1.0

- 작성: 이상재 (Forecasting) · 2026-10-27 KST
- 일감: #1124 (상위 #980) · 선행: #1119 (Resolved), #991 (In Progress 70%) · 연계: #1123 (Feedback), #990/#992 (조영우)
- 원본 데이터: `OIBC_2026_DATA.zip` SHA-256 `f8b8914d1e45c7a7e8108fc2bfb2c1287373a07e2621cfe653bb3a12a438834e` (#1119~#1123과 동일 원본 확인)
- 상태: 설계 완료 (v1.0). D01~D03은 PR #188 수아 제안과 합의 방향 반영. 모델 학습·성능 평가는 범위 밖(#1125~#1127)
- 정산 기준: #991 계산기를 단일 원본으로 호출. #991 검증 완료 시 run별 `scoring_version`만 갱신되며 본 구조는 변경 없음

---

## 0. 설계 전제 — 과제 구조에서 나오는 제약

| 사실 (README·#1121·#1122) | 실험 구조에 미치는 영향 |
|---|---|
| 평가 구간 2025-06-01 01:00 ~ 2026-06-01 00:00 (8,760h) 1년치를 한 번에 제출 | 단일 모델/정책으로 **사계절 전체**를 맞춰야 함 → 검증도 계절을 덮어야 함 |
| 평가 구간에 발전량·실측 기상 없음 | **Persistence·전일 동시각·lag 계열은 제출용으로 사용 불가.** Naive는 climatology형으로 정의 (#1125) |
| 예측 시점 D-1 17:00 KST, 예보 round 10·17 모두 허용 | 입력 = 예보 A/B(30종) + 정적(용량·좌표·거리) + 달력·태양기하. round 처리 방식은 실험 축 |
| 정산 `S = Σ SMP·actual − 0.10·Σ SMP·k·|Σforecast − Σactual|` (그룹 합산 후 절대값, k=3 @ 11~15시) | 최종 지표는 **그룹 단위·SMP·k 가중 절대오차**. RMSE는 보조 |
| 구성(G1/G2)은 1년 고정, 각 ≥20,000 kW | 예측은 **발전소 단위**로 내고, 그룹 합산은 구성(조영우)에 맡김 |

## 1. 입력 / 출력

### 1.1 입력 (D03 합의 대상, #1122 feature_policy 기준)
| 구분 | 내용 | 비고 |
|---|---|---|
| 키 | `site_id`, `ts`(KST, 우측닫힘) | |
| 예보 A | `forecast_wa` (wa_station, round, ts) 10종 | `wa_temp_max/min`은 `wa_temp`와 동일 → 1개만 사용 |
| 예보 B | `forecast_wb` (wb_station, round, ts) 20종 | 풍속 단위 km/h (A는 m/s) |
| 정적 | `capacity_kw`, `lat`, `lon`, `wa_dist`, `wb_dist` | `current_group`은 입력 제외 |
| 파생 | 태양 고도·방위·cosZ(구간 중앙 −30분), hour, doy sin/cos, month | 공식 baseline.py와 동일 방식 |
| 제외 | 발전량 lag, 실측 기상, SMP | 평가 구간에 없음 / 정산 전용 |

### 1.2 학습 타깃
- `cf = energy / capacity_kw` (설비이용률) 를 기본 타깃으로, 예측 후 `× capacity_kw`로 kWh 복원
  - 이유: 발전소 간 스케일 통일 → 짧은 이력 발전소(1월 fold 154h)도 전체 발전소 모델로 커버 (D02)
- 야간(태양고도 ≤ 0)은 0으로 고정, 학습에서 제외
- 출력 후처리: `prediction_kwh = clip(pred, 0, capacity_kw)` (음수 금지는 제출 규칙, 상한은 정책 — 이상 9행 확인 필요)

### 1.3 출력 산출물 (#1123 D06 계약안 수용)
| 산출물 | 컬럼 | 용도 |
|---|---|---|
| `oof_predictions.parquet` (검증) | site_id, ts, fold, actual_kwh, prediction_kwh, residual_kwh, round_policy, model_version, data_version, split_version, feature_version | 지표 계산, **조영우 #992 residual 입력** |
| `test_predictions.parquet` (제출용) | site_id, ts, prediction_kwh, model_version, … | 실적 없음 → actual/residual 컬럼 없음 |
| `group_forecast.csv` | group, ts, forecast_kwh | 구성(composition) 확정 후 합산해 제출 형식 생성 |

- `residual_kwh = actual_kwh − prediction_kwh` (양수 = 과소예측). #991·#1123과 동일
- 검증 산출물과 test 산출물은 파일·디렉터리 분리 (test에 정답/잔차 생성 금지)

## 2. 검증 구조 (D02)

### 2.1 #1121 설계안 v1 수용 + 계절 fold 추가 제안
| Fold | 학습 | 검증 대상일 | 검증 행 | 253개소 커버 | 출처 |
|---|---|---|---:|---|---|
| DEV_JUL24 *(PR #188 D02)* | 2023-06-01 ~ 2024-06-30 00:00 | 2024-07-01 ~ 07-31 | 166,656 | 고정 224개소 / 36,300.895 kW (744h 완전 + 사전 이력) | 추가 |
| DEV_OCT24 *(PR #188 D02)* | 2023-06-01 ~ 2024-09-30 00:00 | 2024-10-01 ~ 10-31 | 187,488 | 고정 252개소 / 41,379.75 kW | 추가 |
| DEV_JAN | ~ 2024-12-31 00:00 | 2025-01-01 ~ 01-30 | 182,160 | 253 | #1121 |
| DEV_FEB | ~ 2025-01-31 00:00 | 2025-02-01 ~ 02-27 | 163,944 | 253 | #1121 |
| HOLDOUT | ~ 2025-02-28 00:00 | 2025-03-01 ~ 05-31 | 558,624 | 253 | #1121 (선택에 사용 금지) |

- 검증 행 수(DEV_JAN/FEB/HOLDOUT)는 원본에서 재계산해 #1121과 일치 확인
- 추가 이유: 평가 구간이 1년(여름 피크 포함)인데 #1121안은 겨울·봄만 검증 → 여름·가을 일반화 미검증 (#1121 위험 항목과 동일)
- 계절 fold는 발전소 집합이 253개소와 다르므로 **발전소 단위 지표(wMAE_site 등)만** 비교에 사용. 특히 7월 224개소는 36,300.895 kW로 2×20,000 kW 구성 자체가 불가 → 정산 검증 불가 (PR #188)
- 7월 부분 기록 26개소는 평가 cohort에서 제외하되 학습에는 사용 가능
- 공통 규칙: expanding window(시작 2023-06-01 고정), fold 경계일 하루 정답 집계 제외(#1121), 전처리·스케일러는 fold 학습 구간에서만 fit

### 2.2 최종 학습
- 모델·feature·round 정책 확정 후 2023-06-01 ~ cutoff 전체로 재학습 → test 예측
- cutoff 해석(D04: 공식 첫 예측 2025-05-31 17:00 vs #1121 보수안 00:00)은 문길래 확인 후 확정

## 3. 평가 Metric

| 레벨 | 지표 | 정의 | 용도 |
|---|---|---|---|
| **주 지표** | **W_ref** (그룹 페널티) | `0.10·Σ_g Σ_t SMP·k·|Σ_site∈g residual|` — 참조 구성(current_group) 기준 | 모델 선택 1순위. #991 계산기로 산출 |
| 보조 | W_greedy | 동일, #990 greedy 구성 기준 | 구성 의존성 점검 (순위가 뒤집히는지) |
| 보조 | wMAE_site | `Σ SMP·k·|residual| / Σ SMP·k·actual` (발전소 단위) | 구성 무관 비교, 계절 fold 비교 |
| 보조 | nMAE, nRMSE, bias | 용량 정규화, 주간(elev>0)만 | 진단·발표용 |
| 슬라이스 | 시간대(11~15시 vs 그외), 월, round, 단기이력 발전소 | | 원인 분석 |

- 검증 SMP는 `train/smp.csv`, k는 `ts.hour ∈ [11,15] → 3`으로 생성 (#991 derive_from_hour와 동일)
- 절대오차 기반 비용이므로 손실함수 후보로 **L1/Huber + SMP·k 가중**을 #1127에서 비교
- 정산 계산은 자체 구현하지 않고 **#991 계산기를 호출** (단일 scoring 원본 유지). 각 run의 metrics에 사용한 `scoring_version`을 기록하고, #991 검증 완료 후의 run만 공식 비교 기준으로 사용

## 4. 실험 실행 구조

```
config (yaml) ─► data loader ─► feature builder ─► fold runner ─► model (fit/predict)
                (hash 검증)     (feature_version)   (split_config)     │
                                                                       ▼
                       registry ◄── metrics (#991 호출) ◄── oof / test artifacts
```

- **config 1개 = run 1개**: model, feature_set, round_policy, target, folds, seed
- **model 인터페이스**: `fit(X, y, weight)` / `predict(X)` — Naive·MLR·LightGBM·XGBoost·CatBoost 동일 시그니처
- **round_policy** 실험 축: `r17` / `r10` / `avg(10,17)` (공식 baseline) / `both_as_features`
- **결측 예보 (D01)**: 같은 제공사·관측소·대상시각의 다른 round로 대체하고 플래그 기록. 평가 A 264개 조합 누락 대비 필수 (두 round 동시 누락은 학습·평가 모두 0건 확인, 발생 시 학습 구간 중앙값 후보)
- 재현성: seed 고정, `git_sha`, 입력 파일 SHA-256 기록. 원본 데이터는 git 미포함

## 5. 결과 저장 방식 (Experiment Registry, #1128과 연결)

```
runs/<run_id>/            run_id = YYYYMMDD-HHMMSS-<model>-<tag>
  config.yaml
  metrics.json            fold별 + 전체
  oof_predictions.parquet
  test_predictions.parquet (최종 후보만)
  model/                  (선택)
registry.csv              run 1행
```

registry 필드 (WBS §12 기준):
`run_id, created_at, owner, git_sha, data_version, feature_version, split_version, model_name, hyperparameters, round_policy, train_range, validation_range, prediction_artifact, residual_artifact, vpp_assignment_version, scoring_version, RMSE, MAE, bias, wMAE_site, gross_sales, error_penalty, net_settlement_revenue, notes, status(PLANNED|RUNNING|VALIDATED|REJECTED|CANDIDATE|FINAL)`

## 6. 후속 일감 연결

| 일감 | 이 설계에서 넘기는 것 |
|---|---|
| #1125 Naive | climatology 정의(발전소별 month×hour 평균 CF), 공식 baseline.py 재현을 기준선 0으로 등록 |
| #1126 MLR | 동일 feature·fold·metric으로 비교 |
| #1127 비선형 | round_policy, 손실함수(L1/가중), global vs plant 비교 축 |
| #1128 Registry/Residual | 5장 registry 스키마, 1.3 oof 계약 → #992 |

## 7. 결정 필요 사항

| ID | 내용 | 제안 | 확인 대상 |
|---|---|---|---|
| D01 | 결측 예보 처리 | 17시 우선, 없으면 동일 제공사·관측소·대상시각 10시로 대체 + 대체 플래그 (avg/both 정책은 역방향도 동일) | 황수아 (PR #188 방향 일치) |
| D02 | 검증 구간 | #1121안 + 7월(224개소)·10월(252개소) 고정 cohort 추가, 3~5월 holdout 유지 | 황수아·튜터 (PR #188 방향 일치) |
| D03 | 입력 목록 | 예보·설비·달력. 발전량 lag는 평가 구간에 데이터가 없어 제외 확정, 학습 구간 통계(발전소별 CF)는 사용. `wa_temp_max/min` 중복 제거 | 황수아 (PR #188 방향 일치, lag 문구 조정 요청) |
| D04 | 최종 학습 cutoff | 공식 해석 확인 | 문길래 |
| D05 | scoring_version | #991 계산기 호출, 정본 확인 후 승격 | 조영우·문길래 |
| — | 예측 상한(capacity clip) | 9행 초과 사례 원인 확인 후 확정 | 황수아 |
