analyze-silver-miner-metal-ratio

<essential_principles>

礦業股/金屬比率（Miner-to-Metal Ratio）：

ratio_t = miner_price_t / metal_price_t

其中：

• miner_price：銀礦股代表（ETF 如 SIL/SILJ，或自建礦業股指數）
• metal_price：白銀價格（期貨 SI=F、現貨 XAGUSD、ETF SLV）

此比率衡量「礦業股相對於金屬本體」的估值水位：

• 比率高：礦業股相對白銀偏貴（可能過度樂觀、槓桿溢價高）
• 比率低：礦業股相對白銀偏便宜（可能被低估、或反映成本/股權稀釋風險）

使用歷史分位數（Percentile Rank）判斷當前比率位置：

分位數區間	標籤	直覺
≤ 20%	bottom (底部)	礦業股相對白銀歷史上很便宜
20-40%	low (偏低)	礦業股相對估值偏低
40-60%	neutral (中性)	歷史中位區間
60-80%	high (偏高)	礦業股相對估值偏高
≥ 80%	top (頂部)	礦業股相對白銀歷史上很貴

底部區間不等於白銀必漲：可能是礦業股因成本/稀釋被合理定價。

當出現「比率低 + 白銀高」的組合：

• 比率處於底部區：礦業股相對白銀偏便宜
• 白銀處於高位：金屬價格已在歷史高檔

此「背離」意味著：

1. 礦業股可能有追趕空間（均值回歸邏輯）
2. 或礦業股正確反映了結構性問題（成本、稀釋、地緣風險）

需結合基本面交叉驗證，而非盲目視為買入訊號。

目標：若比率要回到歷史頂部（或中位），需要什麼條件？

假設當前比率 = 1.14，目標比率（頂部門檻）= 2.45：

情境 A：白銀不變，礦業股需漲多少？

miner_multiplier = target_ratio / current_ratio
                 = 2.45 / 1.14 = 2.15x (需漲 115%)

情境 B：礦業股不變，白銀需跌多少？

metal_multiplier = current_ratio / target_ratio
                 = 1.14 / 2.45 = 0.46 (需跌 54%)

此推演提供「極端情境」的量化參考，非預測。

• 頻率選擇：長週期訊號建議使用週頻（1wk）或月頻（1mo）
• 平滑視窗：可選 4 週或 3 個月移動平均降低雜訊
• 事件去重：類比事件間隔需 ≥ min_separation_days（如 180 天）

本 skill 使用 yfinance 取得 ETF/期貨數據，預設週頻對齊。

</essential_principles>

1. 數據整合：取得礦業股代理與白銀價格序列
2. 比率計算：計算相對比率並可選平滑
3. 分位數判斷：當前比率在歷史的位置
4. 類比事件：歷史底部區間的事件識別
5. 前瞻驗證：底部事件後白銀的 1/2/3 年表現
6. 情境推演：礦業股需漲多少 / 白銀需跌多少才回到頂部

輸出：當前狀態、歷史類比、情境推演、風險提示。

<quick_start>

最快的方式：執行預設情境分析

cd skills/analyze-silver-miner-metal-ratio
pip install pandas numpy yfinance matplotlib  # 首次使用
python scripts/ratio_analyzer.py --quick

生成視覺化圖表（基本版）

python scripts/ratio_plotter.py --quick --output-dir ../../output

生成完整版圖表（含底部事件、前瞻報酬統計）

python scripts/ratio_plotter.py --comprehensive --start-date 2010-01-01 --output-dir ../../output

圖表輸出路徑：

• 基本版：output/sil_silver_ratio_YYYY-MM-DD.png
• 完整版：output/sil_silver_ratio_comprehensive_YYYY-MM-DD.png

輸出範例：

{
  "skill": "analyze_silver_miner_metal_ratio",
  "current": {
    "ratio": 1.14,
    "ratio_percentile": 18.7,
    "zone": "bottom",
    "bottom_threshold": 1.16,
    "top_threshold": 2.45
  },
  "history_analogs": {
    "bottom_event_dates": ["2010-08-06", "2016-01-29", "2020-03-20"],
    "forward_metal_returns": {
      "252": {"count": 3, "median": 0.42, "win_rate": 1.0}
    }
  },
  "scenarios": {
    "target": "return_to_top",
    "miner_multiplier_if_metal_flat": 2.15,
    "metal_drop_pct_if_miner_flat": 0.54
  }
}

完整情境分析：

python scripts/ratio_analyzer.py \
  --miner-proxy SIL \
  --metal-proxy SI=F \
  --start-date 2008-01-01 \
  --freq 1wk \
  --smoothing-window 4 \
  --bottom-quantile 0.20 \
  --top-quantile 0.80 \
  --output result.json

</quick_start>

1. 快速分析 - 使用預設參數（SIL / SI=F）計算當前比率狀態
2. 完整分析 - 自訂參數進行情境分析（可選擇礦業股/金屬代理、分位門檻）
3. 視覺化圖表 - 生成比率走勢圖，標記當前位置與分位數區間
4. 歷史驗證 - 查看底部區間事件的前瞻報酬統計
5. 情境推演 - 計算「回到頂部」需要的礦業股漲幅或白銀跌幅
6. 方法論學習 - 了解比率邏輯與分位數解讀

請選擇或直接提供分析參數。