Upload README.md

README.md

@@ -1,69 +1,272 @@
-# 시정 예측 모델링 프로젝트
+### 가시거리(Visibility) 예측 모델링 프로젝트
 
-이 프로젝트는 대기질 데이터를 분석하고 예측하는 머신러닝/딥러닝 모델을 개발하는 것을 목표로 합니다.
+기상·대기오염·항공정보(ASOS, DataOn, TAF)를 통합해 가시거리(`visi`)를 예측합니다. 불균형 데이터를 SMOTENC/CTGAN으로 보강하고, GBDT(LightGBM/XGBoost)와 탭울러 딥러닝(ResNet-like, FT-Transformer, DeepGBM)을 결합해 다중/이진 분류를 수행합니다.
 
-## 프로젝트 구조
+### 기술 스택(Tech Stack)
 
+- 데이터 처리: `pandas`, `numpy`
+- EDA/시각화: `matplotlib`, `seaborn`
+- 샘플링/불균형 처리: `imbalanced-learn (SMOTENC)`, `CTGAN`, `Optuna`(CTGAN 하이퍼파라미터), 지역/연도 기반 분할
+- 모델링(GBDT): `LightGBM`, `XGBoost`(GPU 옵션 포함, 사용자 정의 CSI 평가)
+- 모델링(딥러닝): `PyTorch` 기반 `ResNetLike`, `FTTransformer`, `DeepGBM`
+- 최적화: `hyperopt`(LightGBM/XGBoost), `Optuna`(CTGAN)
+- 유틸/저장: `joblib`
+
+### 시스템 아키텍처(파이프라인)
+
+1) 데이터 수집/적재: `data/ASOS`, `data/dataon`, `data/data_for_TAF`
+2) 병합/전처리: `0.air_data_merge.ipynb` → `1.data_merge.ipynb` → `2.eda_preproccesing.ipynb`
+3) 데이터 증강(불균형 처리): `Analysis_code/make_oversample_data/` 내 `SMOTENC` → `CTGAN(+Optuna)` → 규칙 기반 필터링
+4) 데이터 분할: 지역별(`*_train.csv`, `*_test.csv`), 연도 기반 3-Fold 홀드아웃
+5) 학습: GBDT(`optima/*.py`)와 딥러닝 노트북(`deeplearning_model_*`)
+6) 평가/분석: 사용자 정의 `CSI` + F1/Accuracy, `model_visualize.ipynb`, `find_reason/*`(트렌드, 분포 비교)
+7) 앙상블/최종: `model_voting_test_best_sample/*`, `final_test/final.ipynb`
+
+### TL;DR (빠른 시작)
+
+1) 파이썬 환경 준비 후 필수 패키지 설치
+
+```bash
+pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+pip install pandas numpy scikit-learn matplotlib seaborn imbalanced-learn optuna ctgan xgboost lightgbm joblib
 ```
-paper/
-├── Analysis_code/          # 분석 및 모델링 코드
-│   ├── find_reason/       # 원인 분석 코드
-│   ├── optima/           # 최적화 관련 코드
-│   ├── sampling_data_test/ # 샘플링 테스트 코드
-│   ├── final_test/       # 최종 테스트 코드
-│   ├── make_oversample_data/ # 오버샘플링 데이터 생성
-│   ├── save_model/       # 저장된 모델
-│   ├── model_result/     # 모델 결과
-│   ├── models/          # 모델 구현 코드
-│   └── model_voting_test_best_sample/ # 앙상블 모델 테스트
-└── data/                # 데이터 파일
+
+2) 데이터 배치
+- 원천/중간 산출물을 `data/` 하위에 배치. 학습용 CSV/feather는 `data/data_for_modeling/` 참고.
+
+3) 오버샘플링 수행(SMOTE/CTGAN)
+
+```bash
+cd Analysis_code/make_oversample_data
+python smote_sample_1.py
+python oversampling_code.py
 ```
 
-## 주요 파일 설명
+4) GBDT 최적화/학습 예시(서울시)
+
+```bash
+cd ../optima
+python LGB_smote_seoul.py
+python XGB_smote_seoul.py
+```
+
+5) 딥러닝 모델 학습/평가: 노트북 실행(`Analysis_code/` 내 `.ipynb`)
+
+---
+
+### 프로젝트 구조
+
+```
+visibility_prediction/
+├── Analysis_code/
+│   ├── 0.air_data_merge.ipynb
+│   ├── 1.data_merge.ipynb
+│   ├── 2.eda_preproccesing.ipynb
+│   ├── 3.oversampling.ipynb
+│   ├── deeplearning_model_binary.ipynb
+│   ├── deeplearning_model_multi.ipynb
+│   ├── make_train_test.ipynb
+│   ├── model_visualize.ipynb
+│   ├── final_test/
+│   │   └── final.ipynb
+│   ├── find_reason/                # 지역별 트렌드/원인 분석 노트북
+│   ├── sampling_data_test/         # 샘플링 데이터 성능 테스트 노트북
+│   ├── model_voting_test_best_sample/
+│   │   └── ensemble__voting_best_sample.ipynb
+│   ├── make_oversample_data/
+│   │   ├── oversampling_code.py    # SMOTENC+CTGAN 파이프라인
+│   │   ├── smote_sample_1.py       # 연도/전처리 포함 SMOTE 샘플
+│   │   └── (gan_sample_*.py 등)
+│   ├── optima/                     # GBDT 하이퍼파라미터 탐색/학습 스크립트
+│   │   ├── LGB_smote_seoul.py
+│   │   └── XGB_smote_seoul.py
+│   ├── models/
+│   │   ├── best_resnet_model.pth
+│   │   └── tabnet_model.zip
+│   ├── deepgbm.py
+│   ├── ft_transformer.py
+│   └── resnet_like.py
+├── data/
+│   ├── ASOS/                       # 기상
+│   ├── dataon/                     # 대기오염(대용량 일자별 CSV)
+│   ├── data_for_modeling/          # 지역별 train/test CSV 및 feather
+│   ├── data_for_demo/
+│   ├── data_for_TAF/               # 공항 TAF(항공기상) CSV
+│   └── data_oversampled/
+│       ├── smote/
+│       ├── ctgan7000/
+│       ├── ctgan10000/
+│       └── ctgan20000/
+└── README.md
+```
+
+---
+
+### 데이터 및 변수(Variables)
+
+- 목표 변수
+  - `visi`: 가시거리(연속값). 합성 표본 필터링 규칙에서 확인되는 구간 예시: class 0은 [0,100), class 1은 [100,500), class 2는 그 외 구간으로 사용됩니다.
+  - `multi_class`: 다중 분류 라벨(정수 0/1/2)
+  - `binary_class`: 이진 라벨. 규칙: `binary_class = 0 if multi_class == 2 else 1`
+
+- 주요 피처 그룹(코드 기준)
+  - 기상(ASOS): `temp_C`, `precip_mm`, `wind_speed`, `wind_dir`(정온→0 치환), `hm`, `vap_pressure`, `dewpoint_C`, `loc_pressure`, `sea_pressure`, `solarRad`, `snow_cm`, `cloudcover`(int), `lm_cloudcover`(int), `low_cloudbase`, `groundtemp`
+  - 대기오염(DataOn): `O3`, `NO2`, `PM10`, `PM25`
+  - 시간/주기: `year`(int), `month`(int), `hour`(int), `hour_sin`, `hour_cos`, `month_sin`, `month_cos`
+  - 파생: `ground_temp - temp_C`(지면-기온 차)
+
+- 범주형 변수(모델/샘플링 관점)
+  - `wind_dir`, `cloudcover`, `lm_cloudcover`, 그리고 `int` 타입의 시간 변수(`year`, `month`, `hour`)는 SMOTENC/GBDT에서 범주형으로 취급됨(코드에서 `float64`가 아닌 열 인덱스 자동 탐지)
+
+- 전처리 규칙(발췌)
+  - `wind_dir` 중 `'정온'`은 "0"으로 치환 후 정수형 변환
+  - `cloudcover, lm_cloudcover` 정수형 변환
+  - 학습 시 타깃/보조 열(`multi_class, binary_class`) 분리 후 필요 시 재계산
+
+---
+
+### EDA 및 전처리
+
+- 병합/정리
+  - 인덱스 열 제거: `Unnamed: 0` 드롭
+  - 자료형 정합성: `cloudcover`, `lm_cloudcover` 정수형; `year`, `month`, `hour` 정수형
+  - 특수값 치환: `wind_dir == '정온'` → "0" 후 정수형 변환
+
+- 특징 공학
+  - 주기형 인코딩: `hour_sin`, `hour_cos`, `month_sin`, `month_cos`
+  - 차분형 파생: `ground_temp - temp_C`
+
+- 분포/트렌드 분석
+  - 지역별 시계열 트렌드: `find_reason/*_trend.ipynb`
+  - 분포 비교/변화 감지: `find_reason/wasserstein_distance.ipynb`(Wasserstein 거리 기반 분포 차이 정량화)
+
+- 데이터 분할
+  - 지역 단위 데이터셋(`*_train.csv`, `*_test.csv`)
+  - 연도 기반 홀드아웃 3-Fold(2018–2020 조합)로 일반화 성능 검증
+
+### 불균형 처리 및 합성 샘플링
+
+- SMOTENC
+  - 범주형 인덱스: 입력 특성 중 `float64`가 아닌 열의 위치 인덱스 사용
+  - 샘플링 전략 예시: `{0: 10000, 1: 10000, 2: 기존 개수}` 또는 데이터 규모에 따라 `{0: 500/1000, 1: ceil(n1/100)*100, 2: n2}`
+  - 재계산: 샘플링 후 `multi_class`에서 `binary_class` 및 주기/차분 파생을 복구
+
+- CTGAN(+Optuna)
+  - 클래스 0, 1을 대상으로 Optuna로 `embedding_dim, generator_dim, discriminator_dim, pac, batch_size, discriminator_steps` 탐색 후 합성
+  - 생성 표본 품질 필터: `class 0 → 0 ≤ visi < 100`, `class 1 → 100 ≤ visi < 500`
+  - 최종 합본 후 파생/보조 피처(`binary_class`, 주기/차분 항목) 복구
+
+- 산출물
+  - `data/data_oversampled/smote/`, `ctgan7000/`, `ctgan10000/`, `ctgan20000/` 하위에 지역별 CSV 저장
+
+---
+
+### 모델 아키텍처(상세)
+
+- 딥러닝(tabular)
+  - `resnet_like.py`
+    - 입력: `x_num [B, N_num]`, `x_cat [B, N_cat]` → concat → 입력선형(`d_main=128`) → 잔차블록(`n_blocks=4`, `d_hidden=64`, `dropout_first=0.25`) → 출력층
+    - 출력: `num_classes == 2 → 1 로짓`, `> 2 → K 로짓`
+  - `ft_transformer.py`
+    - 수치: Linear(`num_features → d_token=192`), 범주: `cat_cardinalities`별 `nn.Embedding(d_token)` 후 합성
+    - 인코더: `TransformerEncoderLayer(d_model=d_token, nhead=8, dropout≈0.2)` × `n_blocks=6` → 평균 풀링 → 분류 헤드
+  - `deepgbm.py`
+    - 수치 Linear(`d_main=128`) + 범주 임베딩 합산 → 잔차 MLP 블록(`n_blocks=4`, `d_hidden=64`, `dropout≈0.2`) → 분류 헤드
+
+- GBDT
+  - LightGBM(`optima/LGB_smote_seoul.py`): `objective='multiclassova'`, `n_estimators≈4000`, 조기종료, GPU 옵션 예시 존재, `hyperopt`로 `max_depth, min_child_weight, num_leaves, subsample, learning_rate` 탐색
+  - XGBoost(`optima/XGB_smote_seoul.py`): `objective='multi:softprob'`, `tree_method='hist'`, `enable_categorical=True`, GPU 옵션, `hyperopt`로 핵심 하이퍼파라미터 탐색, `eval_metric=CSI`
+
+---
+
+### 학습/검증 전략
+
+- 연도 기반 홀드아웃 3-Fold(예시)
+  - Fold1: Train 2018–2019 → Val 2020
+  - Fold2: Train 2018–2020 → Val 2019
+  - Fold3: Train 2019–2020 → Val 2018
+- 지역 단위로 별도 학습(예: `seoul_train.csv` 등)
+
+---
+
+### 평가 지표
+
+- 사용자 정의 CSI(Critical Success Index) 다중분류 버전
+
+```python
+H = cm[0, 0] + cm[1, 1]
+F = (cm[1, 0] + cm[2, 0] + cm[0, 1] + cm[2, 1])
+M = (cm[0, 2] + cm[1, 2])
+CSI = H / (H + F + M + 1e-10)
+```
+
+- 그 외: 정확도, F1 등 노트북/��크립트에서 병행 확인
+
+---
+
+### 실행 방법(상세)
+
+- 환경 준비
+  - Python 3.8+ 권장, CUDA 지원 시 GPU 사용 가능(CTGAN/GBDT 속도 향상)
+  - LightGBM GPU가 미설치라면 `pip install lightgbm`으로 CPU 버전 사용 또는 GPU 빌드 필요
+
+- 데이터 준비
+  - `data/ASOS/`: 연도별 기상 원천
+  - `data/dataon/`: 대기오염 일자별 CSV(대용량)
+  - `data/data_for_modeling/`: 지역별 학습/평가 세트(`*_train.csv`, `*_test.csv`, `df_*.feather`)
+  - `data/data_for_TAF/`: 공항별 TAF(항공기상)
+
+- 전처리/탐색
+  - `Analysis_code/0.air_data_merge.ipynb` → `1.data_merge.ipynb` → `2.eda_preproccesing.ipynb`
+
+- 오버샘플링
+  - `Analysis_code/make_oversample_data/`에서 스크립트 실행(상단 TL;DR 참조)
+
+- GBDT 최적화/학습
+  - `Analysis_code/optima/LGB_smote_seoul.py`, `XGB_smote_seoul.py` 실행
+  - 산출 모델은 `Analysis_code/save_model/` 하위에 `.pkl`로 저장
+
+- 딥러닝 학습
+  - `deeplearning_model_*` 노트북에서 탭울러 모델 학습/평가, `model_visualize.ipynb`로 시각화
+
+- 앙상블/최종 평가
+  - `model_voting_test_best_sample/ensemble__voting_best_sample.ipynb`
+  - `final_test/final.ipynb`
+
+---
+
+### 모델 입출력 규격(요약)
+
+- 수치 입력 `x_num`: `float32` 텐서 `[batch, num_numeric_features]`
+- 범주 입력 `x_cat`: 정수 인덱스 텐서 `[batch, num_categorical_features]`
+- 출력: 이진(1 로짓) 또는 다중분류(K 로짓). 손실/임계값은 노트북 내 설정 참고
 
-### 데이터 전처리 및 분석
-- `0.air_data_merge.ipynb`: 대기질 데이터 병합
-- `1.data_merge.ipynb`: 추가 데이터 병합
-- `2.eda_preproccesing.ipynb`: 탐색적 데이터 분석 및 전처리
-- `3.oversampling.ipynb`: 데이터 오버샘플링
+---
 
-### 모델링
-- `deeplearning_model_binary.ipynb`: 이진 분류 딥러닝 모델
-- `deeplearning_model_multi.ipynb`: 다중 분류 딥러닝 모델
-- `model_visualize.ipynb`: 모델 결과 시각화
-- `make_train_test.ipynb`: 학습/테스트 데이터 분할
+### 재현성/시드
 
-### 모델 구현
-- `resnet_like.py`: ResNet 기반 모델 구현
-- `deepgbm.py`: DeepGBM 모델 구현
-- `ft_transformer.py`: Feature Transformer 모델 구현
+- `random_state=42`(SMOTENC), 모델 스크립트 내 `random_state=120` 등의 고정값 사용
+- 데이터/하드웨어 차이에 따라 재현률이 다를 수 있으므로 fold/seed를 명시적으로 설정 권장
 
-### 저장된 모델
-- `best_model_f1.pth`: 최고 성능 F1 모델
-- `best_deepgbm_model.pth`: 최고 성능 DeepGBM 모델
+---
 
-## 사용 방법
+### 주의/트러블슈팅
 
-1. 데이터 준비
-   - `data/` 폴더에 필요한 데이터 파일을 위치시킵니다.
+- `optima/LGB_smote_seoul.py`의 `sys.path.append(...)`는 환경 의존적 경로입니다. 일반 환경에서는 제거해도 `from lightgbm import LGBMClassifier`가 동작해야 합니다.
+- 스크립트는 상대 경로를 가정합니다. 실행 전 현재 작업 디렉터리가 `Analysis_code/*` 하위인지 확인하세요.
+- `wind_dir`의 `'정온'` 값 치환/형변환이 누락되면 GBDT/XGB에서 오류가 발생할 수 있습니다.
+- `dataon/`은 매우 대용량입니다. 메모리 여유를 확보하거나 연도/지역 단위로 처리하세요.
 
-2. 데이터 전처리
-   - `0.air_data_merge.ipynb`부터 순서대로 실행하여 데이터를 준비합니다.
+---
 
-3. 모델 학습
-   - `deeplearning_model_binary.ipynb` 또는 `deeplearning_model_multi.ipynb`를 실행하여 모델을 학습합니다.
+### 의존성
 
-4. 결과 분석
-   - `model_visualize.ipynb`를 실행하여 모델 결과를 분석합니다.
+- Python 3.8+
+- PyTorch, pandas, numpy, scikit-learn, imbalanced-learn, optuna, ctgan, xgboost, lightgbm, joblib, matplotlib, seaborn
 
-## 요구사항
+---
 
-- Python 3.8 이상
-- PyTorch
-- pandas
-- numpy
-- scikit-learn
-- matplotlib
-- seaborn
+### 라이선스/인용
 
-## 라이선스
+- 라이선스: 추후 업데이트 예정
+- 본 프로젝트/결과물을 인용 시 `visibility_prediction` 저장소와 사용된 데이터 소스(ASOS, DataOn, TAF)를 명시해 주세요.