# 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 변동성 및 변화 빈도.
