lightgbm

.gemini/difficulty-factors.md

@@ -1,28 +1,23 @@
-# TJA 난이도 산정 핵심 요소 (Technical Factors)
+# TJA 난이도 산정 피처 (Features)
 
-학습 모델(DifficultyNet)에 입력되는 8가지 핵심 지표입니다. (spec.md 업데이트 반영)
+`preprocess/featurize.ts`에서 추출되는 8가지 핵심 피처입니다.
 
-## 1. 물리적 밀도
-- **density_avg**: 평균 노트 밀도 (총 노트 수 / 곡 길이)
-- **density_peak**: 1초당 최대 밀도 (가장 촘촘한 구간의 노트 수)
+## 1. 양적 지표
+- **note_count**: 총 노트 수. 곡의 길이에 따른 절대적인 노트 양.
 
-## 2. BPM 및 속도 변화
-- **bpm_avg**: 곡의 평균 BPM
-- **bpm_var**: BPM 변화율 (BPM 변속의 다양성)
+## 2. 밀도 지표
+- **density_avg**: 평균 NPS. `(총 노트 수 / 곡의 총 소요 시간) * 1000`.
+- **density_peak**: 순간 최대 밀도. 임의의 노트를 기준으로 1초 이내에 포함된 최대 노트 수.
 
-## 3. 구조적 특징
-- **note_count**: 총 노트 수
-- **long_note_duration**: 전체 대비 긴 노트(지속형) 점유율
+## 3. 속도 변화 지표
+- **bpm_avg**: 노트별 BPM의 단순 산술 평균.
+- **bpm_change**: BPM 변동 횟수. 인접한 두 노트 간 BPM 차이가 1.5 이상일 때 카운트.
+- **scroll_change**: 시각적 속도(`BPM * Scroll`) 변동 횟수. 차이가 1.5 이상일 때 카운트.
 
-## 4. 패턴 및 연타
-- **complex_ratio**: 복합 패턴(큰 북/작은 북 혼합) 비율
-- **roll_count**: 연타(Roll) 노트의 총 개수
+## 4. 구조적 복잡도
+- **rhythm_complexity**: 리듬의 정규성. 인접한 노트 간 시간 간격의 비율이 2의 거듭제곱(1, 0.5, 2 등)에 가까운 횟수를 카운트.
+    - *참고: 현재 코드는 정규 리듬일 때 증가하며, 문서와 실제 로직의 방향성이 반대일 수 있음.*
+- **color_complexity**: 색상 배치 복잡도. 인접 노트의 색상(Don/Ka)이 바뀔 때, 그 간격의 제곱의 역수($1/\Delta t^2$)를 누적. 간격이 좁을수록 수치가 급격히 상승.
 
-## 계산 로직
-- **밀도 계열**: 노트 간 시간 간격(`delta`)의 역수(`1/delta`)로 순시 밀도를 계산하여 `avg`/`peak` 도출.
-- **BPM 계열**: `#BPM` 및 `#STOP` 명령을 기반으로 시간 축 전개 후 평균 및 표준편차(`var`) 계산.
-- **패턴 계열**: 슬라이딩 윈도우(4~8개 노트)에서 노트 타입 변화(`d↔k`) 횟수를 측정하여 비율 산정.
-- **연타 계열**: `#ROLL` 명령 및 입력 밀집 구간 카운트.
-
-## 중요 주의사항
-- 모든 Factor는 모델 학습 전 `StandardScaler` 또는 `RobustScaler`를 통해 반드시 이상치를 처리해야 합니다.
+## 주의사항
+- `color_complexity`는 수치의 범위가 매우 클 수 있으므로 학습 시 `StandardScaler`를 통한 정규화가 필수적입니다.