Quant Research Lab
섹터 ETF 할당 및 종목-요인 선택을 위한 공유 월간 연구 프레임워크입니다.
4명의 팀원이 협력하여 개발했습니다.
우리는 공분산 추정(covariance estimation)이 섹터 ETF 할당에 미치는 영향과 가격/거래량 요인 순위(price/volume factor rankings)가 종목 포트폴리오에 미치는 영향을 연구합니다. 두 전략 계열 모두 동일한 리밸런싱, 거래 비용(transaction-cost), 포트폴리오 회계(portfolio-accounting) 관례를 사용하므로 방법론적 차이를 쉽게 검토할 수 있습니다. 엔지니어링 재현성(Engineering reproducibility)과 예측 성능은 별도로 평가됩니다.
현재 버전: **v0.11 (패키지 버전 0.11.0)**입니다. 여기에는 이전에 v0.1.1로 논의되었던 연구 검증 마일스톤이 포함되며, 11개 섹터 페이지와 포터블 리프레시 기능이 추가되었습니다. 일별 의사결정은 v1.0, 시간별 의사결정은 v2.0, AI 지원 분/초 단위 의사결정은 v3.0으로 남아 있으며 버전 로드맵에서 향후 작업으로 예정되어 있습니다.
새 컴퓨터에서의 원클릭 리포트
인터페이스, 리포트, 코드 식별자, CLI 메시지 및 문서의 기본 언어는 영어입니다. 중국어 보조 보고서는 언어 전환을 통해 계속 사용할 수 있습니다. 개요(overview), ETF 백테스트 또는 종목 백테스트 페이지에서 XLK와 같은 ETF를 클릭하면 해당 섹터의 종목 순위가 열립니다. 연결된 페이지는 구성된 연구 샘플을 보여주며, 펀드의 전체 또는 과거 보유 내역을 포함한다고 주장하지 않습니다.
Windows에서는 소스 번들을 추출하고 **START_V011.cmd**를 더블클릭합니다. 이는 부트스트랩 다운로드를 확인하고, 프로젝트 로컬 Python 및 종속성을 설치하며, 현재 가격을 다운로드하고, 모든 리포트를 재계산한 후 결과를 엽니다. 원본 컴퓨터의 환경에 의존하지 않습니다. 공식 소프트웨어 소스 및 Yahoo에 대한 인터넷 접속이 필요하며, 오류는 로그를 유지하고 성공적인 새로 고침으로 간주되지 않습니다. macOS/Linux용으로는 bash START_V011.sh가 있으며, 이 운영체제에서는 작성만 되었을 뿐 테스트되지는 않았습니다.
- 개요 및 11개 섹터 페이지에는 각 섹터별로 수정 가능한 샘플 종목 5개(총 55개)가 포함되어 있습니다.
이것은 전체 시장 또는 역사적 지수 멤버십을 의미하지 않습니다.
- 100개 요인 정의, 공식, 방향 및 상태 필드가 모두 표시됩니다. 65개의 가격/거래량 요인은 계산된 값을 가지며; 35개의 재무 요인은 시점별 기초 데이터가 준비되는 대로 이용할 수 없습니다. 모든 지표를 오름차순 또는 내림차순으로 정렬할 수 있으며, 누락된 값은 항상 마지막에 위치하고 순위가 매겨지지 않습니다. 표시되는 정렬 방식이 전략을 변경하지는 않습니다.
- 중국어 보조 자료와 함께 영어 대시보드, ETF/주식 백테스트 및 검증 보고서가 제공되며, CSV/JSON으로 내보내기가 가능합니다. 모든 계산된 성과 지표와 자산 가중치 통계는 백테스트 보고서에 나타납니다.
- 각 실행은 클럭을 재설정합니다: 5년간의 연구 기간, 그보다 3년 전의 예열 기간, 그리고 후행하는 24개월의 시간적 홀드아웃(holdout)이 있습니다. 완료된 뉴욕 세션과 2시간의 데이터 소스 버퍼만 사용되며; 순위는 완전히 완료된 거래소 달력 월을 기준으로 합니다.
- 미리 정의된 9가지 실험은 5/10/20 bp 비용, 보유 종목 수, 순위 기간(ranking windows), 그리고 각 요인 그룹 점수 기여도를 제거하는 것을 다룹니다. 모든 성공과 실패가 저장됩니다. 시간적 홀드아웃이 보지 못한 데이터로 인증되는 것은 아닙니다.
configs/refresh.json을 편집하여 샘플 및 창(windows)을 변경하십시오. 각 실행은 outputs/v011/runs/<run-id>/에 보존되며; outputs/v011/report.html은 가장 최근에 완전히 성공한 실행을 가리킵니다. 원본 소스 테이블, SQLite 배치, 가격 샘플, 달력 커버리지, 실험 계획 및 SHA-256 해시가 유지됩니다. 이것은 가격을 다운로드하고 연구 보고서를 생성하지만, 회사 연간 보고서나 SEC 제출 텍스트를 다운로드하지는 않습니다.
Python이 설치되어 있다면, python -m quant_research refresh --open을 실행하십시오. 선택적 --as-of YYYY-MM-DD는 과거의 특정 시점을 재현하며; 이를 생략하면 현재 시간을 사용합니다. 명시적인 오프라인 데모는 refresh --demo --output outputs/v011_demo를 사용하여 수행되며 합성(synthetic)으로 표시됩니다. refresh --prices path.csv는 구성된 모든 주식과 11개 ETF가 필요합니다. 휴대용 가이드를 참조하십시오.
언어: English (주요) · 중국어 보조
읽기 가이드: 빠른 시작 · 영어 일반 텍스트 · 방법론 · 팩터 카탈로그 · 검증 · 로드맵 · GitHub 업그레이드 가이드
구현 범위
| 전략군 | 입력 및 방법 | 공유 기능 |
|---|
| 섹터 ETF | 11개 섹터 ETF로 구성된 고정 유니버스; 동일 가중치(equal weight), 샘플 공분산 최소 분산(sample-covariance minimum variance), 상수 상관관계 축소 최소 분산(constant-correlation shrinkage minimum variance) 적용 | |
| 세션 검증, 월말 신호, 다음 세션 마감 시점 실행, 포지션/현금/비용 원장, 일일 NAV 및 성과 지표 | | |
| 주식 | 일별 OHLCV 및 조정 종가; 가격/거래량 팩터 순위화 후 최고 순위 주식에 동일 가중치 적용 | |
| ETF 코어의 월간 일정 및 포트폴리오 회계, 통합 명령줄 인터페이스(command-line interface), 보고서 내보내기 기능 | | |
ETF군은 equal_weight, sample_min_variance, shrinkage_min_variance를 비교합니다. 기본 유니버스는 XLB, XLC, XLE, XLF, XLI, XLK, XLP, XLRE, XLU, XLV, XLY입니다.
주식군은 설정된 유니버스에 걸쳐 equal_weight와 multifactor_top_n을 비교합니다. 후자는 상위 N개 주식에 동일 가중치를 부여합니다. v0.11의 refresh는 55개의 샘플 주식을 사용합니다. 구 버전인 demo/run --family stocks는 10개 주식 예제(AAPL, MSFT, GOOGL, AMZN, NVDA, META, JPM, JNJ, XOM, PG)를 유지합니다. 이들은 과거 지수 구성원이 아닌 고정 연구 샘플입니다. 두 전략 모두 매월 리밸런싱되며 거래 비용이 발생합니다. 아래 수동 설정에 명시된 고정 날짜는 demo/run에 적용되며, refresh는 자체 롤링 윈도우 설정을 통해 날짜를 도출합니다.
팩터 카탈로그에는 100개의 후보가 포함되어 있으며, 그중 65개가 구현되었습니다: 모멘텀(momentum) 20개, 반전(reversal) 10개, 위험(risk) 15개, 유동성(liquidity) 20개 팩터.
남은 35개의 후보 요인—가치(value) 15개, 품질(quality) 10개, 성장(growth) 10개 요인으로 구성됨—은 역사적 가용 타임스탬프를 가진 금융 데이터가 필요합니다. 이들은 구현되지 않았으며 0으로 대체되지 않습니다. 요인 카탈로그를 참조하십시오. 요인의 방향 및 그룹 가중치는 테스트할 가설이며, 요인의 개수가 예측력을 확립하는 것은 아닙니다.
기본 주식 파이프라인은 65개 모든 요인이 유효해야 하며, 이들의 방향을 조정하고, 섹션별 백분위수를 계산하며, 그룹 내에서 평균을 내고, 모멘텀/반전(reversal)/위험(risk)/유동성(liquidity)을 각각 30%/10%/40%/20%의 가중치로 결합합니다. 이후 세 개 연속 월에 걸쳐 순위 백분위수를 평균하고, 다시 순위를 매긴 후, 상위 4개 주식에 동일한 가중치를 부여합니다. 최종 동점은 오름차순 티커(ticker)로 처리됩니다. 공식 및 선택 다이어그램은 방법론에 있습니다.
'월별(Monthly)'은 의사결정 빈도를 설명합니다. 일일 관측치는 위험 추정 및 포트폴리오 회계에 사용됩니다. 원장은 조정된 가격을 기반으로 하는 합성 분수 단위를 보유하며, 매수, 매도 및 초기 진입 비용을 포함합니다. 이는 원본 주식 수량 및 현금 배당에 대한 독립적으로 인증된 장부는 아닙니다.
공유 워크플로우 (Shared workflow)
flowchart TD
A["Price CSV or synthetic demo"] --> B["Validate fields, universe and sessions"]
B --> C["Month-end signals and next-session schedule"]
...
두 연구 브랜치 모두 타겟 가중치를 evaluate_targets에 공급하며, 실행 및 회계(accounting)를 공유합니다. 월별 결정은 여전히 일일 관측치를 사용합니다.
빠른 시작 (Quick start)
Python 3.11 이상이 필요하며, 로컬 검증과 CI 설정에는 Python 3.13을 사용합니다. 초기 의존성 설치 시 인터넷 접속이 필요할 수 있습니다. 설치 후에는 데모를 실행하는 데 시장 데이터 다운로드나 시장 데이터 계정이 필요하지 않습니다.
Windows PowerShell에서 프로젝트 루트 디렉토리에서 다음 명령어를 실행하십시오. 활성화 스크립트는 필요하지 않습니다:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
.\.venv\Scripts\python.exe -m quant_research demo --output outputs/demo
...
macOS/Linux에서:
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/python -m quant_research demo --output outputs/demo
...
이후 예제들에서는 python이 이 환경의 인터프리터를 의미합니다. 전체 경로를 계속 사용해도 됩니다. 환경을 활성화한 후에는 quant-research가 python -m quant_research를 대체할 수 있습니다.
두 데모 모두 로컬에서 결정론적(deterministic) 합성 가격(synthetic prices)을 생성합니다. 결과를 보려면 출력된 report.html 경로를 브라우저에서 여십시오. 이전 실험을 유지하려면 출력 디렉터리가 새로 생성되었거나 비어 있어야 합니다. 각 데모는 demo_prices.csv를 저장하며, 이는 run --prices에 전달될 수 있습니다. 이 데이터는 합성 데이터입니다. 합성 결과는 소프트웨어 파이프라인을 검증하는 것이며 시장 성과, 전략의 효과 또는 투자 수익률에 대한 증거가 아닙니다.
통합 인터페이스는 현지화된 제목, 차트, 표, 지표 설명, 방법론 및 증거 한계가 포함된 **중국어 보고서(report_zh.html)**와 **영어 보고서(report_en.html)**를 생성합니다. report.html은 기본적으로 영어 보고서를 열며, 언어 링크를 사용하여 중국어로 전환할 수 있습니다. 두 보고서는 동일한 계산 결과를 사용하며, 프로그래밍적 사용을 위해 CSV 및 JSON 필드 이름은 영어로 유지됩니다.
검증된 Windows/Python 3.13 의존성 스냅샷은 requirements-lock-py313-windows.txt에 있습니다. 해당 환경을 재현하려면 python -m pip install -r requirements-lock-py313-windows.txt를 실행한 다음, python -m pip install . --no-deps를 실행하십시오. 다른 플랫폼은 자체적인 검증이 필요합니다. 위의 표준 설치도 지원됩니다.
사용자 데이터 사용하기
run은 기존 CSV 파일을 읽으며 시장 데이터를 다운로드하지 않습니다. 사용 권한이 있는 일관되게 정의된 데이터를 확보하십시오. 레거시(legacy) 다운로드 및 스냅샷 파이프라인에는 별도의 진입점이 있습니다.
ETF 입력은 date,ticker,adj_close라는 필수 열을 가진 장형 CSV 파일이며, 날짜는 YYYY-MM-DD 형식을 사용합니다.
예를 들어:
date,ticker,adj_close
2020-12-30,XLB,70.12
2020-12-30,XLC,65.87
이 조각은 형식만을 보여주며 백테스트(backtest)를 수행하기에는 불충분합니다. 입력 티커는 구성과 정확히 일치해야 하며, 날짜/티커당 한 행, 그리고 입력 간격의 모든 정규 XNYS 세션에 대한 관측치가 포함되어야 합니다. 기본적으로 초기 신호 날짜까지 최소 505개의 가격 관측치가 필요하여 504개의 수익률(return) 관측치를 형성합니다.
python -m quant_research run --family etf --prices prices.csv --config configs/sector_monthly.json --output outputs/etf
python -m quant_research run --family stocks --prices stock_prices.csv --config configs/stock_monthly.json --top-n 4 --ranking-window 3 --output outputs/stocks
주식 입력에는 date,ticker,open,high,low,close,adj_close,volume가 필요합니다. 가격은 유효해야 하며 거래량(volume)은 음수가 아니어야 합니다. 누락된 세션을 채우거나 복사된 가격으로 숨기지 마십시오. 통합 백테스트는 ETF의 세션 프록시를 포함하여 정규 XNYS 세션 캘린더를 사용합니다. 레거시 홍콩 순위(ranking) 진입점은 rank_report.py에 남아 있으며, 이 미국 백테스트 캘린더를 해당 시장에 직접 적용해서는 안 됩니다.
ETF 구성과 주식 구성을 참조하십시오. 최상위 레벨의 config.json은 레거시 파이프라인에 속하며 통합 백테스트 명령어에서는 사용되지 않습니다.
| 매개변수 (Parameter) | 기본값 (Default) | 의미 및 제약 조건 (Meaning and constraint) |
|---|
tickers | 위에 나열된 ETF 또는 주식 유니버스 | 최소 두 개의 고유 티커; CSV와 정확히 일치해야 함 |
lookback | 504 | 수익률 관측치의 개수; 자산 개수를 초과해야 함. |
주식도 자체적인 팩터 워밍업 기간과 연속 순위 지정 월이 필요합니다 |
| research_start | 2021-01-01 | 월의 첫 달력일이어야 하며, 초기 신호는 이전 달 마지막 세션을 사용합니다 |
| holdout_start | 2024-01-01 | 리서치 시작일을 따라와야 합니다. 보고 기간을 분할하지만 보지 못한 테스트 세트를 설정하지는 않습니다 |
| cost_bps | 5.0 | 두 가족 모두 매수 및 매도 시 5 bp를 부과합니다: 각 측의 명목 금액의 0.05% |
| max_weight | 0.25 | 자산별 목표 가중치 상한선; 1 / asset_count와 1 사이여야 합니다 |
| initial_cash | 1.0 | 양수 시작 자본금; 기본값은 정규화된 제시를 지원합니다 |
| --top-n | 4 | 주식 전용; 유니버스 크기보다 클 수 없으며, 1 / top_n <= max_weight여야 합니다 |
| --ranking-window | 3 | 주식 전용; 현재 신호 월을 포함하여 최소 한 개의 연속된 유효한 달이 필요합니다 |
주식 그룹 가중치는 현재 Python 인터페이스를 통해 제공될 수 있으며, 통합 CLI에는 해당 옵션이 없습니다. 공유되는 lookback을 변경한다고 해서 t