Mizrhan/visibility_prediction_with_B.-G.Shin

가시거리(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. 파이썬 환경 준비 후 필수 패키지 설치

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

2. 데이터 배치

• 원천/중간 산출물을 data/ 하위에 배치. 학습용 CSV/feather는 data/data_for_modeling/ 참고.

3. 오버샘플링 수행(SMOTE/CTGAN)

cd Analysis_code/make_oversample_data
python smote_sample_1.py
python oversampling_code.py

4. GBDT 최적화/학습 예시(서울시)

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}로 초기 증강 후 CTGAN으로 최종 증강 (<-> 155행)
  • 재계산: 샘플링 후 multi_class에서 binary_class 및 주기/차분 파생을 복구

• CTGAN(+Optuna)

  • 클래스 0, 1의 초기 데이터 샘플 수 확보를 위해 SMOTENC를 사용한 1차 증강을 수행한 뒤, CTGAN을 적용하여 최종 데이터 증강을 진행 (<-> 151행)
  • 클래스 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) 다중분류 버전

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 로짓). 손실/임계값은 노트북 내 설정 참고

---

재현성/시드

• random_state=42(SMOTENC), 모델 스크립트 내 random_state=120 등의 고정값 사용
• 데이터/하드웨어 차이에 따라 재현률이 다를 수 있으므로 fold/seed를 명시적으로 설정 권장

---

주의/트러블슈팅

• optima/LGB_smote_seoul.py의 sys.path.append(...)는 환경 의존적 경로입니다. 일반 환경에서는 제거해도 from lightgbm import LGBMClassifier가 동작해야 합니다.
• 스크립트는 상대 경로를 가정합니다. 실행 전 현재 작업 디렉터리가 Analysis_code/* 하위인지 확인하세요.
• wind_dir의 '정온' 값 치환/형변환이 누락되면 GBDT/XGB에서 오류가 발생할 수 있습니다.
• dataon/은 매우 대용량입니다. 메모리 여유를 확보하거나 연도/지역 단위로 처리하세요.

---

의존성

• Python 3.8+
• PyTorch, pandas, numpy, scikit-learn, imbalanced-learn, optuna, ctgan, xgboost, lightgbm, joblib, matplotlib, seaborn

---

라이선스/인용

• 라이선스: 추후 업데이트 예정
• 본 프로젝트/결과물을 인용 시 visibility_prediction 저장소와 사용된 데이터 소스(ASOS, DataOn, TAF)를 명시해 주세요.