chore: add collaboration workflow and templates

Author: zheyuliu328

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: "Bug/复现问题"
+about: "报告复现失败、错误或数据异常"
+title: "[Bug] "
+labels: "bug"
+assignees: ""
+---
+
+## 问题描述
+
+请简要说明问题与影响。
+
+## 复现步骤
+
+1. ...
+2. ...
+
+## 期望结果
+
+## 实际结果
+
+## 环境信息
+
+- OS：
+- Python 版本：
+- 分支与 Commit：
+- 快照包版本（Release/zip）：
+
+## 相关日志/截图
+
+粘贴关键报错或 CSV 异常样例。

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: "需求/改进"
+about: "新增功能、研究改进或流程优化"
+title: "[Feature] "
+labels: "enhancement"
+assignees: ""
+---
+
+## 背景与目标
+
+请描述该需求的背景与预期目标。
+
+## 影响范围
+
+- 影响模块：
+- 影响命令：
+- 是否影响口径（manifest/pricing/阈值/样本/目标变量）：
+
+## 输出影响
+
+- 是否会改动输出 CSV（sample_table/stats_table）：
+
+## 验证方式
+
+提供复现步骤或验收标准。

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint-and-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install minimal tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Ruff format check
+        run: ruff format --check MethodD
+
+      - name: Smoke check (syntax)
+        run: python -m compileall MethodD

.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+.env
+.idea/
+.vscode/
+
+# MethodD snapshots & outputs
+MethodD/data/snapshots/runs/
+MethodD/outputs/
+
+# Temporary exports
+*.zip
+*.tar.gz

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# 协同贡献规范（RMSC6007 Group Project）
+
+本项目采用 **GitHub 私有仓库 + PR 审阅 + 固定产物** 的协同模式，目标是确保**同一份输入快照、同一份代码版本、同一套命令**，任何人都能复现相同的 `sample_table.csv` 与 `stats_table.csv`。
+
+## 1. 分支与发布规则
+
+- **main 分支永远保持可运行**：
+  - `python3 MethodD/tools/capture_snapshots.py ...`
+  - `python3 MethodD/experiments/run_iv_factor_study.py`
+  - main 不接受半成品或无法复现的提交。
+
+- **个人改动必须走 feature 分支 + PR**：
+  - 命名规范：`feat/<name>-<topic>`
+  - 示例：`feat/alice-report-edits`、`feat/bob-factor-v2`
+
+## 2. PR 必须回答的三件事
+
+1. **口径是否变化**
+   - manifest schema、pricing_rule、过滤阈值、样本定义、目标变量定义
+2. **可复现性是否破坏**
+   - 同一快照包 + 同一 commit 产物一致
+3. **输出是否变化**
+   - `MethodD/outputs/sample_table.csv`
+   - `MethodD/outputs/stats_table.csv`
+
+## 3. 数据快照策略
+
+- **代码仓库只保留 schema / 脚本 / 小型示例快照**。
+- **真实快照不进 Git**，使用以下方式之一：
+  1. GitHub Release 附件（zip）
+  2. 独立私有仓库：`MethodD-data`
+
+## 4. 提交规范
+
+- 每次提交尽量聚焦一个主题（单功能/单修复）。
+- 必须在 PR 描述中列出：
+  - 修改文件列表
+  - 影响的命令
+  - 是否更改口径
+  - 是否新增/修改输出 CSV
+
+## 5. 权限与角色
+
+- **Owner 权限**（你本人）保留：
+  - 合并 main 权限
+  - 修改采集口径与 manifest schema 权限
+- 其他成员只允许走 feature 分支提交 PR。
+
+## 6. 复现实验最小流程
+
+```bash
+python3 MethodD/tools/capture_snapshots.py --ticker NVDA t0
+python3 MethodD/tools/capture_snapshots.py t5
+python3 MethodD/experiments/run_iv_factor_study.py
+```
+
+产物：
+- `MethodD/outputs/sample_table.csv`
+- `MethodD/outputs/stats_table.csv`

GOOGLE_FORM_SUBMISSION.md

@@ -0,0 +1,153 @@
+# Google Form Submission Templates
+
+## 选择方案后，直接复制对应的文本到Google Form
+
+---
+
+## 📋 方案A：VaR/ES 风险度量与回测框架
+
+### Proposed Topic
+Unified VaR/ES Risk Measurement and Backtesting Framework in Python (Integrating QuantStats, arch, vectorbt)
+
+### Objectives
+• Objective 1: Build a unified Python pipeline that computes Value-at-Risk (VaR) and Expected Shortfall (ES) using multiple methods, including Historical Simulation, Parametric (Gaussian), Monte Carlo, and GARCH-based approaches.
+
+• Objective 2: Implement standard backtesting procedures for VaR forecasts, including coverage tests (e.g., Kupiec POF) and independence tests (e.g., Christoffersen), and produce comparable diagnostics across methods.
+
+• Objective 3: Generate reproducible risk reports (tables and visualizations) and a single-click notebook workflow that benchmarks methods across assets and market regimes.
+
+### Data to be Analyzed
+• Source 1: Daily adjusted close prices for 5–10 major equity indices or broad-market ETFs (e.g., S&P 500, Hang Seng, Nikkei 225 equivalents) downloaded via Yahoo Finance using yfinance; sample period fixed (e.g., 2015–2025).
+
+• Source 2: Optional risk-free rate series from FRED via pandas-datareader for risk-adjusted metrics (Sharpe and excess-return calculations).
+
+• Preprocessing: Align trading calendars, handle missing values (forward-fill where appropriate), compute log returns, and standardize rolling-window splits for in-sample fitting and out-of-sample evaluation.
+
+### Possible Comparisons
+• Comparison 1: Compare VaR/ES estimates across methods by realized exceedances, coverage ratios, and backtesting p-values under a consistent rolling-window protocol.
+
+• Comparison 2: Stress-period robustness comparison by segmenting the sample into regimes (e.g., calm vs. crisis periods) and evaluating model stability and conservativeness.
+
+• Comparison 3: Cross-asset comparison of tail risk: examine how tail behavior differs across markets and whether GARCH-based VaR improves performance during volatility clustering.
+
+### Expected Outcomes
+• Outcome 1: A modular, well-documented Python package with a unified API (single function call to compute VaR/ES + backtests) and reproducible notebooks.
+
+• Outcome 2: An empirical benchmark report showing which VaR/ES methods are most accurate and robust across assets and regimes, with clear interpretation of backtesting results.
+
+• Outcome 3: Engineering deliverables including tests (80%+ coverage), environment specification (requirements/lockfile), and an automated HTML/markdown risk report.
+
+### Possible Extensions
+• Extension 1: Add portfolio-level risk aggregation (multi-asset VaR/ES) and compare equal-weight vs. optimized portfolios using PyPortfolioOpt.
+
+• Extension 2: Extend volatility modeling (EGARCH/GJR-GARCH) and evaluate incremental benefits over standard GARCH for VaR prediction.
+
+• Extension 3: Provide a lightweight dashboard (e.g., Streamlit) for interactive exploration of risk forecasts and backtesting outcomes.
+
+---
+
+## 📈 方案B：GARCH 波动率预测与VaR链条
+
+### Proposed Topic
+Volatility Forecasting with GARCH-family Models and Its Impact on VaR Forecast Accuracy
+
+### Objectives
+• Objective 1: Implement and compare GARCH-family models (GARCH, EGARCH, GJR-GARCH) to capture volatility clustering and asymmetry in financial returns.
+
+• Objective 2: Translate conditional volatility forecasts into forward-looking VaR forecasts and evaluate accuracy using rolling out-of-sample backtesting.
+
+• Objective 3: Produce a reproducible benchmark notebook and report that explains model choice, parameter stability, and forecast performance across assets and regimes.
+
+### Data to be Analyzed
+• Source 1: Daily return series for a set of indices/ETFs or a diversified basket of liquid large-cap stocks from Yahoo Finance using yfinance, covering 2015-2025.
+
+• Source 2: Optional volatility index proxies (e.g., VIX-like series when available) for external comparison and validation of GARCH-implied volatility.
+
+• Preprocessing: Stationarity checks (ADF test), return transformation, rolling-window splits, and consistent forecasting horizon settings (1-day, 5-day, 20-day ahead).
+
+### Possible Comparisons
+• Comparison 1: Model selection comparison using AIC/BIC and forecast error metrics (RMSE, MAE) for realized volatility proxies.
+
+• Comparison 2: VaR backtesting comparison between GARCH-based VaR and simpler VaR approaches (historical/parametric) using Kupiec and Christoffersen tests.
+
+• Comparison 3: Asset-class/market comparison of asymmetry and leverage effects across different equity indices and sectors.
+
+### Expected Outcomes
+• Outcome 1: A validated GARCH-based risk forecasting pipeline with clear documentation and reproducible experiments across multiple assets.
+
+• Outcome 2: Evidence-based conclusions on when sophisticated volatility models materially improve VaR performance vs. simpler methods.
+
+• Outcome 3: A reusable codebase for volatility modeling and risk forecasting tasks with 80%+ test coverage.
+
+### Possible Extensions
+• Extension 1: Multivariate correlation dynamics (DCC-GARCH) for portfolio-level risk and contagion analysis.
+
+• Extension 2: Regime-switching volatility models for crisis detection and adaptive risk management.
+
+• Extension 3: Link volatility forecasts to dynamic asset allocation constraints and portfolio optimization.
+
+---
+
+## 💼 方案C：因子暴露与风险归因分析
+
+### Proposed Topic
+Factor Exposure Estimation and Risk Attribution with Rolling CAPM/Fama-French Models in Python
+
+### Objectives
+• Objective 1: Estimate time-varying factor exposures using rolling regressions under CAPM and Fama-French models to quantify systematic risk contributions.
+
+• Objective 2: Perform risk attribution to decompose portfolio variance into factor-driven and idiosyncratic components, enabling targeted risk management.
+
+• Objective 3: Backtest risk forecasts derived from factor models and compare against naive historical-volatility baselines to validate predictive power.
+
+### Data to be Analyzed
+• Source 1: Daily returns for a portfolio of stocks/ETFs from Yahoo Finance via yfinance, covering 2015-2025 across multiple sectors.
+
+• Source 2: Factor return series (Fama-French 3-factor and 5-factor models) from Kenneth French's data library, aligned by date; risk-free rate from FRED for excess returns.
+
+• Preprocessing: Date alignment across sources, winsorization of extreme returns (beyond 5 standard deviations), rolling-window estimation choices, and out-of-sample evaluation design.
+
+### Possible Comparisons
+• Comparison 1: CAPM vs. FF3/FF5 explanatory power (R², alpha significance, residual volatility) to assess incremental value of multi-factor models.
+
+• Comparison 2: Risk forecast comparison between factor-based and historical-volatility approaches using rolling backtesting.
+
+• Comparison 3: Style/sector portfolio comparison of factor exposures and risk contributions to identify which factors drive risk in different investment styles.
+
+### Expected Outcomes
+• Outcome 1: A reproducible framework that outputs rolling betas, factor contributions, and risk decomposition tables/plots for any portfolio.
+
+• Outcome 2: Quantified evidence of which factors drive risk across portfolios and regimes, with clear interpretation of results.
+
+• Outcome 3: Clean, documented code with notebooks demonstrating end-to-end factor risk analytics and actionable insights.
+
+### Possible Extensions
+• Extension 1: Incorporate macro factors (interest rates, inflation) and PCA-based dynamic factors for broader economic risk modeling.
+
+• Extension 2: Conditional factor models where factor loadings depend on market conditions (volatility regime, business cycle phase).
+
+• Extension 3: Multi-asset risk attribution (equity + bond + commodity) with cross-asset factor exposures.
+
+---
+
+## 📝 Team Information Template
+
+**Group Leader Name:** [填写]  
+**Group Leader Student ID:** [填写]  
+**Group Leader Email:** [填写]
+
+**Member 2 Name:** [填写]  
+**Member 2 Student ID:** [填写]  
+**Member 2 Email:** [填写]
+
+**Member 3 Name:** [填写]  
+**Member 3 Student ID:** [填写]  
+**Member 3 Email:** [填写]
+
+**Member 4 Name (if applicable):** [填写]  
+**Member 4 Student ID:** [填写]  
+**Member 4 Email:** [填写]
+
+**Member 5 Name (if applicable):** [填写]  
+**Member 5 Student ID:** [填写]  
+**Member 5 Email:** [填写]