# 詳細檔案使用結構報告
## Financial Volatility Analysis Project

**生成時間**: 2025-07-26
**工作目錄**: /Users/apple/Downloads/zzz
**總檔案數**: 400+ 檔案
**項目性質**: 學術研究 - 股票收益波動率預測分析

---

## 1. 主要目錄結構分析

### 📁 核心程式檔案 (Root Level)

/Users/apple/Downloads/zzz/
├── 🔥 academic_parallel_pipeline.py        # 主要學術分析管線
├── 🔥 complete_volatility_analysis_pipeline.py  # 完整分析管線
├── 🔥 main.py                             # 主執行檔案
├── 📋 CLAUDE.md                           # 專案指令與規範
├── 📋 INITIAL.md                          # 初始設計文件
├── 📋 pyproject.toml                      # UV專案配置
└── 📋 uv.lock                             # 依賴鎖定檔案

### 📁 models/ - 波動率模型實現 (8個模型)

models/
├── 🧠 base.py                    # 基礎模型類別
├── 🧠 garch.py                   # GARCH(1,1) 模型
├── 🧠 gjr_garch.py               # GJR-GARCH 模型
├── 🧠 har_rv.py                  # HAR-RV 模型
├── 🧠 garch_midas.py             # GARCH-MIDAS 模型
├── 🧠 regarch.py                 # REGARCH 基準模型
├── 🧠 regarch_emd.py             # REGARCH-EMD 主模型
├── 🧠 regarch_emd_amp.py         # REGARCH-EMD 振幅變體
├── 🧠 regarch_emd_freq.py        # REGARCH-EMD 頻率變體
├── 🧠 regarch_rv.py              # REGARCH-RV 變體
├── 🧠 regarch_u.py               # REGARCH-U 變體
└── 🧠 sandwich_estimator.py      # Sandwich標準誤估計器

### 📁 data/ - 數據檔案

data/
├── raw/
│   └── 📊 cleaned_data.csv       # 主要數據檔案 (8730筆觀測值)
└── .DS_Store

### 📁 preprocessing/ - 數據預處理模組

preprocessing/
├── 🔧 data_loader.py             # 數據載入器
├── 🔧 emd_processor.py           # EMD分解處理器
└── 🔧 feature_engineering.py     # 特徵工程

### 📁 evaluation/ - 評估系統

evaluation/
├── 📊 metrics.py                 # 評估指標計算
├── 📊 rolling_forecast.py        # 滾動窗口預測器
└── 📊 statistical_tests.py       # 統計檢定測試

### 📁 visualization/ - 視覺化系統

visualization/
├── 📈 base_chart.py              # 基礎圖表類別
└── charts/
    ├── 📈 time_series_chart.py        # 時間序列圖
    ├── 📈 imf_decomposition_chart.py  # EMD分解圖
    ├── 📈 aggregate_signals_chart.py  # 聚合信號圖
    └── 📈 prediction_comparison_chart.py # 預測比較圖

### 📁 reporting/ - 報告生成系統

reporting/
├── 📋 base_table.py              # 基礎表格類別
├── 📋 report_generator.py        # 報告生成器
├── 📋 equation_formatter.py      # 方程式格式化
└── tables/
    ├── 📋 descriptive_statistics_table.py    # 基本統計表
    ├── 📋 model_estimation_table.py          # 模型估計表
    ├── 📋 performance_comparison_table.py    # 績效比較表
    └── 📋 statistical_tests_table.py         # 統計檢定表

---

## 2. 檔案分類統計

| 檔案類別 | 數量 | 用途說明 |
|---------|------|----------|
| **Python 模型檔案** | 12 | 實現8個波動率模型及輔助工具 |
| **分析腳本** | 50+ | 各種測試、除錯、分析執行腳本 |
| **配置檔案** | 8 | 專案配置、設定檔案 |
| **文檔檔案** | 15+ | 說明文件、報告、總結 |
| **測試檔案** | 30+ | 模型測試、功能驗證檔案 |
| **輸出結果** | 200+ | 分析結果、圖表、表格 |
| **記憶檔案** | 80+ | Serena MCP 記憶儲存 |

---

## 3. 最新分析結果 (🔥 熱門輸出)

### 📁 empirical_results/parallel_analysis_20250726_105721/

🆕 最新完成分析 (2025-07-26 10:57-11:02)
├── 📊 figures/                  # 9個學術圖形
│   ├── figure1_time_series.png
│   ├── figure2_emd_decomposition.png
│   ├── figure3a_aggregate_signals_phase.png
│   ├── figure3b_aggregate_signals_freq.png
│   ├── figure3c_aggregate_signals_amp.png
│   ├── figure4-1_insample_rv5_comparison.png
│   ├── figure4-2_insample_r5sq_comparison.png
│   ├── figure5-1_outsample_rv5_comparison.png
│   └── figure5-2_outsample_r5sq_comparison.png
├── 📋 tables/                   # 8個學術表格
│   ├── table1_descriptive_statistics.csv
│   ├── table3-1_insample_rv5.csv
│   ├── table3-2_insample_r5sq.csv
│   ├── table4-1_outsample_rv5.csv
│   ├── table4-2_outsample_r5sq.csv
│   ├── table5-1_rv5_model_comparison.csv
│   ├── table5-2_r5sq_model_comparison.csv
│   └── all_performance_tables.md
├── 📈 performance/              # 分析效能記錄
├── 📄 reports/                  # 最終報告
└── 🔄 analysis_state.pkl        # 完整狀態保存

### 📁 歷史分析結果目錄

outputs/
├── complete_pipeline_20250725_172207/    # 完整管線分析
├── complete_pipeline_20250725_170731/    # 管線測試版本
├── dual_target_analysis_20250725_112430/ # 雙目標分析
├── robust_dual_analysis_20250725_114742/ # 穩健雙目標分析
├── outsample_analysis/                   # 樣本外分析
├── statistical_tests/                   # 統計檢定結果
└── reports/                             # 各版本報告

---

## 4. 目錄樹結構完整展示

### 🌳 完整專案結構樹

📦 Financial Volatility Analysis Project
┣ 📂 data/                              # 數據層
┃ ┗ 📂 raw/
┃   ┗ 📊 cleaned_data.csv              # 8730筆股票數據
┣ 📂 models/                           # 模型層 (12個檔案)
┃ ┣ 🧠 Base Model Framework
┃ ┣ 🧠 GARCH Series (GARCH, GJR-GARCH)
┃ ┣ 🧠 Advanced Models (HAR-RV, GARCH-MIDAS)
┃ ┗ 🧠 REGARCH Family (5個變體)
┣ 📂 preprocessing/                     # 預處理層
┃ ┣ 🔧 Data Loading & EMD Processing
┃ ┗ 🔧 Feature Engineering
┣ 📂 evaluation/                       # 評估層
┃ ┣ 📊 Rolling Window Forecasting
┃ ┣ 📊 Performance Metrics
┃ ┗ 📊 Statistical Testing Framework
┣ 📂 visualization/                    # 視覺化層
┃ ┗ 📂 charts/
┃   ┣ 📈 Time Series Visualization
┃   ┣ 📈 EMD Decomposition Charts
┃   ┣ 📈 Signal Aggregation Charts
┃   ┗ 📈 Prediction Comparison Charts
┣ 📂 reporting/                        # 報告層
┃ ┗ 📂 tables/
┃   ┣ 📋 Academic Table Generators
┃   ┣ 📋 Statistical Result Tables
┃   ┗ 📋 LaTeX/Markdown Formatters
┣ 📂 empirical_results/                # 🔥 最新結果
┃ ┗ 📂 parallel_analysis_20250726_105721/
┃   ┣ 📊 figures/ (9個PNG圖形)
┃   ┣ 📋 tables/ (8個CSV表格)
┃   ┣ 📈 performance/ (效能分析)
┃   ┗ 📄 reports/ (學術報告)
┣ 📂 outputs/                          # 歷史結果
┃ ┣ 📂 complete_pipeline_* (多個版本)
┃ ┣ 📂 dual_target_analysis_*/
┃ ┣ 📂 statistical_tests/
┃ ┗ 📂 reports/
┣ 📂 tests/                           # 測試層
┃ ┣ 📂 models/ (模型測試)
┃ ┣ 📂 evaluation/ (評估測試)
┃ ┗ 📂 preprocessing/ (預處理測試)
┣ 📂 config/                          # 配置層
┃ ┣ ⚙️ settings.yaml
┃ ┗ ⚙️ config.py
┣ 📂 utils/                           # 工具層
┃ ┣ 🔧 logger.py
┃ ┗ 🔧 helpers.py
┣ 📂 .serena/                         # Serena MCP
┃ ┣ 📂 memories/ (80+記憶檔案)
┃ ┗ 📂 cache/
┗ 🔥 Root Analysis Scripts (50+)
  ┣ 📄 academic_parallel_pipeline.py   # 主要分析管線
  ┣ 📄 complete_volatility_analysis_pipeline.py
  ┗ 📄 Various test and debug scripts

---

## 5. 檔案關係分析

### 🔗 主要 Python 模組依賴關係

#### 核心依賴鏈

graph TD
    A[academic_parallel_pipeline.py] --> B[models/]
    A --> C[evaluation/rolling_forecast.py]
    A --> D[visualization/charts/]
    A --> E[reporting/tables/]
    
    B --> F[models/base.py]
    F --> G[models/garch.py]
    F --> H[models/regarch_emd.py]
    
    C --> I[evaluation/metrics.py]
    C --> J[evaluation/statistical_tests.py]
    
    D --> K[visualization/base_chart.py]
    E --> L[reporting/base_table.py]

#### 數據流向

data/raw/cleaned_data.csv 
  ↓ (DataLoader)
preprocessing/data_loader.py
  ↓ (EMD Processing)
preprocessing/emd_processor.py
  ↓ (Model Training)  
models/* (8個波動率模型)
  ↓ (Rolling Forecast)
evaluation/rolling_forecast.py
  ↓ (Performance Evaluation)
evaluation/metrics.py & statistical_tests.py
  ↓ (Visualization & Reporting)
visualization/* & reporting/*
  ↓ (Final Output)
empirical_results/parallel_analysis_*/

### 🎯 輸出檔案與分析結果對應關係

| 輸出類型 | 檔案位置 | 對應分析內容 |
|---------|----------|-------------|
| **圖1** | figures/figure1_time_series.png | r₅、r₅²、RV₅、RV₅(sd) 時間序列 |
| **圖2** | figures/figure2_emd_decomposition.png | EMD分解所有IMF分量 |
| **圖3a-c** | figures/figure3*_aggregate_signals_*.png | 相位/頻率/振幅聚合信號 |
| **圖4** | figures/figure4-*_insample_*.png | 樣本內預測比較 (RV₅ & r₅²) |
| **圖5** | figures/figure5-*_outsample_*.png | 樣本外預測比較 (RV₅ & r₅²) |
| **表1** | tables/table1_descriptive_statistics.csv | 基本統計量 (樣本內外) |
| **表3** | tables/table3-*_insample_*.csv | 樣本內預測績效 |
| **表4** | tables/table4-*_outsample_*.csv | 樣本外預測績效 |
| **表5** | tables/table5-*_model_comparison.csv | 統計檢定與模型比較 |

### ⚙️ 配置檔案影響範圍

| 配置檔案 | 影響範圍 | 說明 |
|---------|----------|------|
| **CLAUDE.md** | 整個專案 | 專案規範、模型方程式、輸出要求 |
| **config/settings.yaml** | 全域設定 | 模型參數、路徑配置、計算設定 |
| **pyproject.toml** | Python環境 | UV依賴管理、專案元資料 |
| **.serena/project.yml** | Serena MCP | 上下文管理、記憶體設定 |

---

## 6. 檔案使用頻率與重要性評級

### 🔥 高頻率使用檔案 (核心檔案)
- ⭐⭐⭐ `academic_parallel_pipeline.py` - 主要分析管線
- ⭐⭐⭐ `models/regarch_emd.py` - 核心REGARCH-EMD模型
- ⭐⭐⭐ `evaluation/rolling_forecast.py` - 滾動窗口預測
- ⭐⭐⭐ `data/raw/cleaned_data.csv` - 主要數據源

### 📊 中頻率使用檔案 (支援檔案)
- ⭐⭐ `models/garch.py`, `models/gjr_garch.py` - 基準模型
- ⭐⭐ `visualization/charts/*.py` - 圖表生成器
- ⭐⭐ `reporting/tables/*.py` - 表格生成器
- ⭐⭐ `evaluation/metrics.py` - 評估指標

### 🧪 低頻率使用檔案 (測試檔案)
- ⭐ `test_*.py` (30+檔案) - 各種測試腳本
- ⭐ `debug_*.py` (10+檔案) - 除錯腳本
- ⭐ `generate_*.py` (20+檔案) - 輸出生成腳本

---

## 7. 關鍵路徑分析

### 🚀 主要執行路徑 (學術分析)

開始: academic_parallel_pipeline.py
  ↓
數據載入: preprocessing/data_loader.py
  ↓
EMD分解: preprocessing/emd_processor.py  
  ↓
模型訓練: models/* (8個模型並行)
  ↓
滾動預測: evaluation/rolling_forecast.py
  ↓
績效評估: evaluation/metrics.py & statistical_tests.py
  ↓
結果輸出: visualization/* & reporting/*
  ↓
完成: empirical_results/parallel_analysis_*/

### 📈 輸出生成路徑

分析完成
  ↓
visualization/charts/ → figures/*.png (9個圖形)
  ↓
reporting/tables/ → tables/*.csv (8個表格)
  ↓
reporting/report_generator.py → reports/*.md (最終報告)

---

## 8. 檔案完整性檢查

### ✅ 完整檔案類型統計
- **Python 檔案**: 150+ (.py)
- **數據檔案**: 50+ (.csv, .pkl)
- **圖形檔案**: 100+ (.png)
- **文檔檔案**: 80+ (.md, .tex, .html)
- **配置檔案**: 10+ (.yaml, .json, .toml)

### 🔍 檔案大小分析
- **最大檔案**: empirical_results/*/analysis_state.pkl (~3.4MB)
- **主要數據**: data/raw/cleaned_data.csv (~500KB)
- **典型圖形**: figures/*.png (~100-500KB)
- **記憶檔案**: .serena/memories/*.md (~1-10KB)

---

## 9. 建議與總結

### 📋 檔案組織優化建議
1. **清理歷史檔案**: 可考慮歸檔舊版本outputs目錄
2. **測試檔案整理**: 將test_*.py檔案移入tests/目錄
3. **文檔集中**: 將散落的.md檔案整理到docs/目錄
4. **配置標準化**: 統一使用config/目錄管理所有設定

### 🎯 關鍵檔案保護
**絕對不可刪除的核心檔案**:
- `data/raw/cleaned_data.csv` (唯一數據源)
- `academic_parallel_pipeline.py` (主要分析程式)
- `models/*.py` (所有模型實現)
- `CLAUDE.md` (專案規範)
- 最新結果: `empirical_results/parallel_analysis_20250726_105721/`

### 📊 專案健康度評估
- **完整性**: ✅ 所有必要檔案齊全
- **一致性**: ✅ 輸出格式統一標準
- **可重現性**: ✅ 完整的狀態保存與恢復
- **學術品質**: ✅ 符合學術論文要求

---

**報告生成完成** | 檔案追蹤與記錄系統 | 2025-07-26