backsolve-miner-vs-metal-ratio-with-fundamentals

<essential_principles>

礦業股/金屬價格比率可分解為四大基本面因子：

R_t ≈ K × M_t × (1-L_t) × C_t × D_t

其中：

• K: 校準常數（由觀測值估計）
• M_t: 倍數因子（EV/EBITDA）
• (1-L_t): 槓桿因子（1 - NetDebt/EV）
• C_t: 成本因子（1 - AISC/S_t）
• D_t: 稀釋因子（Shares_base / Shares_t）

此拆解讓「比率變動」有可歸因的量化解釋。

全維持成本（AISC）是礦業股估值的核心驅動：

優先級	來源	方法
1	MD&A / 財報附註	關鍵字抽取：「AISC」「all-in sustaining」
2	年報簡報 PDF	解析表格：$/oz 或 $/ounce
3	Proxy 回算	(OpCost + SustCapex + G&A - Byproduct) / Oz

當直接揭露不可得時，以 proxy 回算補缺；記錄 aisc_method 以標註來源。

目標：給定目標比率 R*（如歷史頂部 1.7），反推需要哪些因子條件。

單因子反推：假設其他因子不變，只調整單一因子

M* = M_now × (R*/R_now)         # 需要的倍數
(1-L*) = (1-L_now) × (R*/R_now) # 需要的去槓桿
C* = C_now × (R*/R_now)         # 需要的成本改善 → 反推 AISC*
D* = D_now × (R*/R_now)         # 需要的稀釋折扣

雙因子組合：以網格列舉可行組合（如倍數 +20% + 白銀 -15%）。

識別「比率落入底部分位」的歷史事件，回看事件當期的四大因子狀態：

1. AISC 是否上升：成本壓力
2. NetDebt/EV 是否惡化：槓桿壓力
3. EV/EBITDA 是否壓縮：倍數壓力
4. Shares 是否上升：稀釋壓力

排名「哪個因子貢獻最大」，識別驅動底部的主因。

遵循「結構化優先」原則：

1. SEC XBRL (10-K/10-Q)：直接取欄位（債務、現金、股數、CFO、Capex）
2. SEDAR+ (加拿大)：銀礦公司常在加拿大上市
3. 公司 IR 年報/MD&A：補齊 AISC、產量等非標準欄位
4. ETF Holdings：官方 CSV 或 SEC N-PORT

抓取時使用 Selenium 模擬人類行為，避免被封鎖。

</essential_principles>

1. 數據整合：抓取價格、ETF 持股、財務報表、營運揭露
2. 因子計算：計算 AISC、槓桿、倍數、稀釋四大因子
3. 比率拆解：建立 R_t ≈ K × M × (1-L) × C × D 近似式
4. 門檻反推：給定目標比率，反推需要的因子組合
5. 事件研究：歷史底部事件的因子驅動分析
6. 輸出報告：結構化 JSON 與可讀 Markdown

目標用戶：看到 SIL/白銀比率極端時，想用「真實財報」驗證驅動因素。

<quick_start>

最快的方式：使用預設參數分析

cd skills/backsolve-miner-vs-metal-ratio-with-fundamentals
pip install pandas numpy yfinance matplotlib  # 首次使用
python scripts/fundamental_analyzer.py --quick

完整分析（含財報抓取）

python scripts/fundamental_analyzer.py \
  --metal-symbol SI=F \
  --miner-universe etf:SIL \
  --region-profile us_sec \
  --start-date 2015-01-01 \
  --output result.json

生成視覺化儀表板

python scripts/visualize_factors.py --quick --output output/
# 輸出: output/sil_silver_factor_analysis_YYYY-MM-DD.png

視覺化儀表板包含四個面板：

1. 比率時間序列：歷史走勢 + 分位數區間（底部/頂部）
2. 因子雷達圖：四大因子健康度一覽
3. 因子評分長條圖：成本、槓桿、倍數、稀釋各項評分
4. 情境熱力圖：倍數擴張 × 白銀變動的組合分析

共同上漲情境模擬

python scripts/scenario_path_simulator.py --quick --output output/
# 輸出: output/scenario_path_YYYY-MM-DD.png + return_heatmap_YYYY-MM-DD.png

核心公式：礦業股漲幅 = (1 + 銀價漲幅) × (R₁/R₀) - 1

自訂參數：

python scripts/scenario_path_simulator.py \
  --silver-monthly 5 \      # 銀價每月漲幅 5%
  --ratio-start 1.10 \      # 比率起點
  --ratio-end 1.20 \        # 比率終點
  --months 6 \              # 模擬 6 個月
  --heatmap                 # 同時生成熱力圖

輸出範例：

{
  "now": {
    "metal_price": 94.4,
    "miner_price": 103.4,
    "ratio": 1.13,
    "ratio_percentile": 0.111
  },
  "thresholds": {
    "bottom_ratio": 1.20,
    "top_ratio": 1.70,
    "median_ratio": 1.51
  },
  "fundamentals_weighted": {
    "aisc_usd_per_oz": 28.0,
    "net_debt_to_ev": 0.25,
    "ev_to_ebitda": 6.4,
    "shares_yoy_change": 0.12
  },
  "factors_now": {
    "cost_factor_C": 0.7034,
    "leverage_factor_1_minus_L": 0.75,
    "multiple_M": 6.4,
    "dilution_discount_D": 0.89
  },
  "backsolve_to_top": {
    "multiple_only_need": 9.1,
    "deleverage_only_need_1_minus_L": 1.12,
    "cost_only_implied_aisc": 15.6,
    "dilution_only_need_D": 1.26
  }
}

</quick_start>

1. 快速分析 - 使用預設參數（SIL / SI=F）計算當前因子狀態
2. 完整分析 - 抓取財報、計算因子、反推門檻
3. 因子拆解 - 深入了解四大因子的計算邏輯
4. 門檻反推 - 給定目標比率，計算需要的因子組合
5. 事件研究 - 歷史底部事件的因子驅動排名
6. 方法論學習 - 了解回算邏輯與數據來源
7. 視覺化 - 生成四面板儀表板圖表
8. 共同上漲情境 - 模擬銀價與礦業股同漲時的比例關係與路徑