FX Hedge Ratio Optimization with HMM + DQN

데이터기반학습 Term Project 제출용 저장소입니다. S&P 500 투자 시 환헤지 비율을 HMM 국면 탐지와 DQN 강화학습으로 동적으로 결정합니다.

Directory Structure

LFDTermProject/
├── README.md                  # 실행 안내
├── requirements.txt           # Python 의존성
├── run.py                     # 제출용 단일 실행 파일
├── data/
│   ├── raw/                   # 원천 CSV
│   └── processed/             # 전처리/HMM 중간 산출물
├── outputs/
│   ├── figures/               # 결과 그래프
│   ├── tables/                # 결과 CSV
│   ├── models/                # HMM/DQN 모델
│   └── logs/                  # 학습 로그
└── fx_hedge/
    ├── config.py              # 경로, 기간, seed, hyperparameter
    └── src/                   # 구현 코드

Data

원천 데이터는 반드시 프로젝트 루트의 data/raw/ 아래에 둡니다.

data/raw/
├── S&P 500.csv
├── 원달러환율.csv
├── CD금리.csv
├── TB3MS.csv
├── VIXCLS.csv
└── DXY.csv

data/processed/는 실행 중 자동 생성되는 중간 산출물 위치입니다.

Setup and Run

채점자는 먼저 아래 Setup 과정을 1회 수행한 뒤 run.py를 실행하면 됩니다. VS Code의 Run Code 버튼은 사용 중인 터미널과 Python 인터프리터 설정에 따라 달라질 수 있으므로, 아래 명령어 실행 방식을 권장합니다.

Windows PowerShell

프로젝트 루트에서 아래 명령을 순서대로 실행합니다. 가상환경을 별도로 activate하지 않고 .venv 안의 Python을 직접 사용하므로 PowerShell 실행 정책 문제를 피할 수 있습니다.

cd C:\path\to\LFDTermProject
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py

Windows에서 python 명령이 인식되지 않는 경우에는 설치된 Python 실행 파일 경로를 사용합니다.

cd C:\path\to\LFDTermProject
& "C:\Users\FORYOUCOM\AppData\Local\Programs\Python\Python312\python.exe" -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py

macOS / Linux / WSL

cd /path/to/LFDTermProject
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python run.py

Re-run Evaluation Only

저장소에는 제출 결과 재현을 위한 전처리/HMM 산출물(data/processed/), 학습 완료 DQN/HMM 모델(outputs/models/), 학습 로그(outputs/logs/)가 포함되어 있습니다. 제출 결과와 동일한 모델로 평가 산출물만 재생성하려면:

python run.py --skip-train

Windows PowerShell에서 activate 없이 실행하는 경우에는:

.\.venv\Scripts\python.exe run.py --skip-train

전처리/HMM/DQN 산출물이 모두 존재하면 python run.py도 기존 산출물을 재사용합니다. 단, --force-data, --force-hmm, --force-train을 주면 해당 단계를 다시 계산하므로 환경에 따라 미세한 수치 차이가 생길 수 있습니다.

Troubleshooting

• ModuleNotFoundError: No module named 'sklearn': 의존성이 설치되지 않은 상태입니다. Setup의 pip install -r requirements.txt 명령을 먼저 실행합니다.
• source : 'source' 용어가 ... 인식되지 않습니다: source .venv/bin/activate는 macOS/Linux/WSL용 명령입니다. Windows PowerShell에서는 위의 Windows PowerShell 명령을 사용합니다.
• bash: C:Users...python.exe: command not found: Windows Python 실행 명령이 bash 터미널에 들어간 상태입니다. PowerShell 터미널을 새로 열어 Windows PowerShell 명령을 사용합니다.
• >>> 프롬프트만 보이는 경우: run.py가 실행된 것이 아니라 Python 대화형 모드가 열린 상태입니다. exit()로 빠져나온 뒤 위의 실행 명령을 사용합니다.

Outputs

주요 결과는 모두 루트 outputs/ 아래에 저장됩니다.

Path	Description
outputs/tables/results_validation.csv	검증 구간 성능표
outputs/tables/results_test.csv	테스트 구간 성능표
outputs/figures/	국면, 헤지비율, 누적수익률 그래프
outputs/models/	HMM 및 DQN 학습 모델
outputs/logs/	DQN 학습 로그

Notes

• run.py는 누락된 전처리/HMM/DQN 산출물을 생성하고 최종 결과표와 그래프를 재생성합니다.
• 제출 결과를 그대로 확인하려면 포함된 모델을 사용하는 python run.py --skip-train 실행을 권장합니다.
• SEED, HEDGE_GRID, 학습 기간, 보상 설정 등 실험 상수는 fx_hedge/config.py에서 관리합니다.
• fx_hedge/는 구현 코드 패키지이며, 채점자가 직접 들어가서 실행할 필요는 없습니다.