# SVM 실습 안내

이 저장소는 SVM 핵심 개념을 4개의 실습으로 구성.

1. Ex #1. 2D Classification (Social Network Ads)
2. Ex #2. Non-linear Classification (Donut Problem)
3. Ex #3. Medical Classification (Breast Cancer)
4. Ex #4. Handwriting Classification (MNIST)

모든 명령어는 프로젝트 루트 디렉터리(`/home/kafa46/studies/udemy_svm`) 기준 작성.

## 1. 환경 준비

### 1-1. 가상환경 생성

```bash
python3 -m venv .venv
```

### 1-2. 가상환경 활성화

```bash
source .venv/bin/activate
```

### 1-3. 패키지 설치

```bash
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

### 1-4. 설치 확인

```bash
python -V
pip list
```

### 1-5. 실행 방식

가상환경 활성화 후 `python` 사용 권장. 가상환경을 활성화하지 않을 경우 `.venv/bin/python`으로 직접 실행 가능.

```bash
python 2d_classification.py
```

```bash
.venv/bin/python 2d_classification.py
```

## 2. 빠른 시작

처음 실습할 때는 아래 순서 권장.

1. `2d_classification.py`로 선형/비선형 결정 경계 확인
2. `donut.py`로 커널 SVM 필요성 확인
3. `cancer_train.py`, `cancer_inference.py`로 tabular 분류 흐름 확인
4. `mnist_train.py`, `mnist_inference.py`로 고차원 이미지 분류 확장

## 3. 실습별 안내

### Ex #1. 2D Classification (Social Network Ads)

#### 실습 목적

- `Age`, `EstimatedSalary` 두 feature만으로 이진 분류 수행
- 결정 경계, margin, support vector 시각화
- `kernel`, `C`, `gamma` 변화에 따른 경계 모양 비교

#### 입력 데이터

- 파일: `./dataset/sns_advertisements/social_network_ads.csv`
- 주요 컬럼: `Age`, `EstimatedSalary`, `Purchased`
- 타깃 의미: 광고 상품 구매 여부

#### 실행 파일

- `2d_classification.py`
- `utils.py`

#### 빠른 실행

기본 실행:

```bash
python 2d_classification.py
```

선형 커널 비교:

```bash
python 2d_classification.py --kernel linear
```

RBF 커널 실험:

```bash
python 2d_classification.py --kernel rbf --C 1.0 --gamma scale
```

결과 이미지 경로 지정:

```bash
python 2d_classification.py --output ./results/social_network_ads_svm.png
```

실행 후 화면 표시:

```bash
python 2d_classification.py --show
```

#### 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `--dataset_path` | 입력 CSV 경로 |
| `--train_ratio` | train split 비율 |
| `--kernel` | `linear`, `poly`, `rbf`, `sigmoid` 중 선택 |
| `--C` | regularization 강도 |
| `--gamma` | 커널 계수, `scale` / `auto` / 실수값 지원 |
| `--random_state` | split 재현용 시드 |
| `--output` | 시각화 이미지 저장 경로 |
| `--show` | 저장 후 이미지 창 표시 |

#### 결과 확인 포인트

- 테스트 정확도 출력 확인
- support vector 개수 확인
- 결과 이미지: `./results/social_network_ads_svm.png`

### Ex #2. Non-linear Classification (Donut Problem)

#### 실습 목적

- 선형 분리가 어려운 데이터 확인
- `rbf` 커널이 원형 클래스 구조를 어떻게 분리하는지 확인
- 커널 변경 시 성능과 결정 경계 차이 비교

#### 입력 데이터

- 외부 파일 없음
- `utils.get_donut()`이 실행 시 synthetic dataset 생성
- 데이터 구조: 안쪽 원 클래스와 바깥쪽 원 클래스

#### 실행 파일

- `donut.py`
- `utils.py`

#### 빠른 실행

기본 실행:

```bash
python donut.py
```

선형 커널 비교:

```bash
python donut.py --kernel linear
```

RBF 커널과 gamma 조정:

```bash
python donut.py --kernel rbf --gamma 0.5
```

결과 이미지 경로 지정:

```bash
python donut.py --output ./results/donut_svm.png
```

실행 후 화면 표시:

```bash
python donut.py --show
```

#### 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `--train_ratio` | train split 비율 |
| `--kernel` | `linear`, `poly`, `rbf`, `sigmoid` 중 선택 |
| `--C` | regularization 강도 |
| `--gamma` | 커널 계수, `scale` / `auto` / 실수값 지원 |
| `--random_state` | split 재현용 시드 |
| `--output` | 시각화 이미지 저장 경로 |
| `--show` | 저장 후 이미지 창 표시 |

#### 결과 확인 포인트

- 선형 커널과 RBF 커널 정확도 차이 확인
- 원형 경계가 제대로 형성되는지 확인
- 결과 이미지: `./results/donut_svm.png`

### Ex #3. Medical Classification (Breast Cancer)

#### 실습 목적

- 실제 수치형 의료 데이터 기반 이진 분류 흐름 확인
- 데이터셋 생성, train/test split 저장, 모델 학습, 단일 샘플 추론까지 한 번에 경험
- 학습 모델과 저장된 테스트 샘플을 이용한 재현 가능한 추론 수행

#### 입력 데이터

- 전체 데이터셋: `./dataset/breast_cancer/cancer.csv`
- 학습 split: `./dataset/breast_cancer/cancer_train.csv`
- 테스트 split: `./dataset/breast_cancer/cancer_test.csv`
- 클래스 의미: `malignant` / `benign`

#### 실행 파일

- `cancer_train.py`
- `cancer_inference.py`
- `utils.py`

#### 추천 흐름

1. 필요 시 전체 CSV 생성
2. 모델 학습 및 train/test split 저장
3. 저장된 test 샘플 기준 단일 추론 실행

#### 학습 usage

기본 경로에 데이터셋 생성 후 바로 학습:

```bash
python cancer_train.py --generate_dataset
```

기존 CSV로 학습:

```bash
python cancer_train.py --dataset_path ./dataset/breast_cancer/cancer.csv
```

train 비율과 모델 저장 경로 변경:

```bash
python cancer_train.py --dataset_path ./dataset/breast_cancer/cancer.csv --train_ratio 0.75 --model_output ./trained_models/cancer.model
```

다른 경로에 데이터셋 생성:

```bash
python cancer_train.py --generate_dataset ./dataset/breast_cancer/cancer.csv
```

#### 학습 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `--generate_dataset [PATH]` | breast cancer CSV 생성, 값 생략 시 기본 경로 사용 |
| `--dataset_path` | 학습용 CSV 경로 |
| `--train_ratio` | train split 비율 |
| `--model_output` | 학습 모델 저장 경로 |
| `--random_state` | split 재현용 시드 |

#### 추론 usage

첫 번째 테스트 샘플 추론:

```bash
python cancer_inference.py --sample_index 0
```

특정 모델로 추론:

```bash
python cancer_inference.py --sample_index 5 --model_path ./trained_models/cancer.model
```

특정 테스트 CSV 사용:

```bash
python cancer_inference.py --sample_index 5 --test_data ./dataset/breast_cancer/cancer_test.csv
```

선택 샘플의 전체 feature 값까지 출력:

```bash
python cancer_inference.py --sample_index 5 --show_features
```

#### 추론 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `--sample_index` | `cancer_test.csv` 기준 0-based 샘플 인덱스 |
| `--model_path` | 추론용 모델 경로 |
| `--test_data` | 추론용 테스트 CSV 경로 |
| `--show_features` | 선택 샘플의 feature 값 전체 출력 |

#### 결과 확인 포인트

- 학습 결과: 정확도, 저장된 모델 경로, train/test split CSV 생성 여부 확인
- 추론 결과: 예측 클래스, 실제 클래스, 정답 여부 확인
- 모델 파일: `./trained_models/cancer.model`

### Ex #4. Handwriting Classification (MNIST)

#### 실습 목적

- 28x28 손글씨 이미지를 784차원 벡터로 변환한 뒤 SVM 분류 수행
- 고차원 입력에 대한 SVM 적용 흐름 확인
- 추론 샘플을 PNG로 저장해 예측 결과를 눈으로 확인

#### 입력 데이터

- 학습 데이터: `./dataset/mnist/train.csv`
- 테스트 데이터: `./dataset/mnist/test.csv`
- 원본 출처: Kaggle Digit Recognizer

#### 실행 파일

- `mnist_train.py`
- `mnist_inference.py`
- `utils.py`

#### 추천 흐름

1. `train.csv` 기반 모델 학습
2. 저장된 모델로 `test.csv`의 특정 샘플 추론
3. 저장된 PNG 이미지와 예측 라벨 함께 확인

#### 학습 usage

기본 설정으로 학습:

```bash
python mnist_train.py
```

학습 데이터 경로 지정:

```bash
python mnist_train.py --train_data ./dataset/mnist/train.csv
```

train 비율 축소 후 빠른 실험:

```bash
python mnist_train.py --train_ratio 0.05
```

모델 저장 경로 지정:

```bash
python mnist_train.py --model_output ./trained_models/mnist.model
```

#### 학습 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `--train_data` | 학습용 MNIST CSV 경로 |
| `--train_ratio` | train split 비율 |
| `--model_output` | 학습 모델 저장 경로 |

#### 추론 usage

첫 번째 테스트 샘플 추론:

```bash
python mnist_inference.py 0
```

특정 모델 사용:

```bash
python mnist_inference.py 10 --model_path ./trained_models/mnist.model
```

특정 테스트 CSV 사용:

```bash
python mnist_inference.py 10 --test_data ./dataset/mnist/test.csv
```

#### 추론 주요 옵션

| 옵션 | 의미 |
| --- | --- |
| `sample_index` | `test.csv` 기준 0-based 샘플 인덱스 |
| `--model_path` | 추론용 MNIST 모델 경로 |
| `--test_data` | 추론용 MNIST test CSV 경로 |

#### 결과 확인 포인트

- 학습 결과: 정확도와 저장된 모델 경로 확인
- 추론 결과: 예측 라벨과 저장된 이미지 경로 확인
- 모델 파일: `./trained_models/mnist.model`
- 추론 이미지: `./results/mnist_sample_<index>_pred_<label>.png`

## 4. 결과 파일 정리

| 실습 | 출력 파일 |
| --- | --- |
| Ex #1 | `./results/social_network_ads_svm.png` |
| Ex #2 | `./results/donut_svm.png` |
| Ex #3 | `./trained_models/cancer.model`, `./dataset/breast_cancer/cancer_train.csv`, `./dataset/breast_cancer/cancer_test.csv` |
| Ex #4 | `./trained_models/mnist.model`, `./results/mnist_sample_<index>_pred_<label>.png` |

## 5. 실습 진행 팁

- 시각화 실습은 `--kernel`, `--C`, `--gamma` 값을 바꿔가며 비교하는 방식 추천
- 정확도만 보지 말고 support vector 수와 결정 경계 모양도 함께 확인
- MNIST는 데이터 양이 많아 학습 시간이 길 수 있으므로 첫 실험은 `--train_ratio 0.05` 또는 `0.1` 권장
- Breast Cancer 실습은 `--generate_dataset`부터 한 번 실행해 두면 이후 흐름 확인이 쉬움
