xgboost

.old/spec.md

@@ -0,0 +1,70 @@
+# 학습 
+## CLI
+- cli로 학습할 수 있는 쉘 스크립트를 작성한다.
+- argument
+    - script_dir
+    - working_dir
+    - data_dir
+    - train_data_count = 100
+    - validate_data_count = 20
+    - margin = 0.5
+    - validate_iterations = 5
+
+## 학습 모델
+- **추천:** PyTorch 기반의 **Deep MLP** (Dropout 및 Weight Decay 필수 적용)
+- **과적합 방지 전략:**
+    - **Dropout (0.3 ~ 0.5):** 학습 시 뉴런을 의도적으로 꺼서 특정 데이터 암기를 방지한다.
+    - **L2 Regularization (Weight Decay):** 가중치가 비정상적으로 커지는 것을 막는다.
+    - **Output Mapping:** 최종 출력에 `Sigmoid`를 걸고 (y * 11) + 1을 적용해 [1, 12] 범위를 강제한다.
+
+## 학습 과정
+1. `{data_dir}/tja`의 tja를 파싱한다. (`{script_dir}/parse.ts`)
+2. `oni`와 `edit` course를 factorize하여 `{working_dir}/factors.json`에 저장한다.
+    - 이미 존재하면 생략하되, Factor 로직 수정 시 삭제 후 재실행한다.
+3. 데이터 표준화(Standardization)를 위한 스케일링 파라미터를 계산하고 `{working_dir}/scaler.json`에 저장한다.
+4. **학습 단계:** 전체 데이터 중 `train_data_count`만큼 데이터를 랜덤하게 추출하여 학습을 진행한다.
+    - `edit` 코스는 `ura`와 매칭하여 오차를 계산한다.
+    - 모델이 충분히 수렴할 때까지 학습을 수행하며, 기존 모델 존재 시 가중치를 로드하여 업데이트한다.
+5. **검증 단계:** 학습이 완료된 모델을 대상으로 아래 과정을 수행한다.
+    - `validate_data_count`만큼의 데이터를 랜덤하게 추출하여 오차를 계산하고 `validate_result_{n}.csv`에 저장한다.
+    - 이 과정을 `validate_iterations` 횟수만큼 반복한다.
+    - **재시도 조건:** 검증 루프 도중 단 한 번이라도 Mean Absolute Error(MAE)가 `margin`보다 크다면, 즉시 검증을 중단하고 4번(학습 단계)으로 돌아가 데이터를 새로 샘플링하여 재학습한다.
+6. **성공 및 종료:** 모든 `validate_iterations` 회차에서 MAE가 `margin` 이하일 경우에만 학습 성공으로 간주하고 최종 모델 파일을 저장한다.
+
+### 유의 사항
+- 모든 데이터는 `working_dir`에 저장한다.
+- Apple Silicon 환경에서 `mps` 디바이스를 할당하여 GPU 가속을 사용한다.
+
+# 예측
+## CLI
+- argument: `working_dir`, `tja`, `difficulty` (oni | edit)
+
+## 예측 과정
+- 로드된 모델과 학습 시 사용했던 스케일링 파라미터(Mean, Std)를 동일하게 적용하여 예측을 진행한다.
+
+# Factor
+## 추천 Factor 세트 (난이도 결정 핵심 지표)
+1.  **density_avg**: 평균 노트 밀도 (총 노트 수 / 곡 길이)
+2.  **density_peak**: 1초당 최대 밀도 (가장 촘촘한 구간의 노트 수)
+3.  **bpm_avg**: 곡의 평균 BPM
+4.  **bpm_change**: BPM 변화율 (BPM 변속의 다양성)
+5.  **note_count**: 총 노트 수
+6.  **complexity**: 동캇 꼬임
+
+## Factor 계산 로직
+- **밀도 계열**: 
+    - 노트 간 시간 간격을 `delta`라고 할 때, `1 / delta`로 순시 밀도를 구한 뒤 최대값(`peak`)과 평균값(`avg`)을 도출합니다.
+- **패턴 계열**:
+    - 노트 타입을 배열로 매핑(예: 0=none, 1=don, 2=ka, 3=big_don, 4=big_ka)합니다.
+    - 슬라이딩 윈도우(예: 4~8개 노트)를 사용하여 인접한 노트의 타입 변화가 잦은 구간을 복합 패턴으로 판정(`complex_ratio`)합니다.
+- **연타 계열**:
+    - `#ROLL` 명령 혹은 특정 시간 내에 입력이 몰려있는 노트를 연타로 간주하여 카운트합니다.
+
+## 구현 가이드
+- `factorize.ts`에서 각 곡의 `Course` 데이터를 순회하며 위 지표들을 계산합니다.
+- 계산된 값은 `Record<string, number>` 형태로 반환하여 학습기에 입력합니다.
+- 모든 Factor는 이상치(Outlier) 처리를 위해 학습 단계에서 `StandardScaler` 또는 `RobustScaler`를 반드시 거쳐야 합니다.
+
+# Scripts
+- `parse.ts`: TJA 문자열을 `Course` 객체로 변환.
+- `factorize.ts`: `Course`를 입력받아 확장된 `Factor` 세트를 반환.