train

GUIDE.md

@@ -0,0 +1,53 @@
+# fumen-analyze 파이프라인 사용 가이드
+
+이 프로젝트는 TJA 채보 데이터를 분석하여 난이도(상수)를 예측하는 머신러닝 모델을 구축하고 사용합니다.
+
+## 1. 모델 학습 및 업데이트 (`run_pipeline.sh`)
+
+기존 모델을 유지하면서 새로운 데이터나 더 많은 반복 학습을 통해 모델을 강화합니다.
+
+```bash
+./run_pipeline.sh
+```
+
+### 내부 동작
+- **TJA Factorization**: `datas/tja` 폴더의 채보에서 30개 이상의 세부 지표(NPS, 구간별 밀도, 패턴 복잡도, 기믹 등)를 추출합니다.
+- **Incremental Training**: 기존에 학습된 `model/constant_predictor.joblib`이 있다면 이를 불러와 **Warm Start** 방식으로 학습을 이어갑니다. 
+- **Batch Sampling**: 매 회차마다 전체 데이터 중 랜덤하게 200개의 코스를 선택하여 학습함으로써 데이터의 다양성을 확보하고 과적합을 방지합니다.
+
+### 팁
+- 오차를 더 줄이고 싶다면 `./run_pipeline.sh`를 여러 번 반복 실행하세요. 학습이 누적되면서 MAE(평균 절대 오차)가 점진적으로 하락합니다.
+
+---
+
+## 2. 난이도 상수 예측 (`run_predict.sh`)
+
+학습된 모델을 사용하여 특정 TJA 파일의 예상 상수를 즉시 계산합니다.
+
+```bash
+./run_predict.sh <TJA_파일_경로> [difficulty]
+```
+
+### 인자 설명
+- **TJA_파일_경로**: 예측할 `.tja` 파일의 경로입니다.
+- **difficulty** (선택 사항): 예측할 난이도 코스입니다.
+  - `oni`: 귀신 (기본값)
+  - `edit`: 우라/에디트
+
+### 실행 예시
+```bash
+# 귀신 난이도 예측
+./run_predict.sh datas/tja/123.tja
+
+# 우라 난이도 예측
+./run_predict.sh datas/tja/123.tja edit
+```
+
+---
+
+## 3. 주요 피처 (Features) 소개
+현재 모델은 채보의 다음 요소들을 종합적으로 분석합니다:
+- **물리적 밀도**: Global NPS, Effective NPS, 구간별(1/4) NPS 분포, 피크 NPS(1s, 2s, 5s).
+- **지구력**: 스트림 비율, 평균/최대 스트림 길이, 회복 구간(Rest) 비율.
+- **배치 복잡도**: Don/Ka 비율, 색상 전환 빈도, 3노트 단위 패턴 복잡도, 손 배치 전환 지수.
+- **리듬 및 기믹**: 엇박 비율, 리듬 표준편차, SV/BPM 변동성 및 변화 빈도.