SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscompute-precious-miner-gross-margin

compute-precious-miner-gross-margin

General & other

View repository

Updated 10-15 21:41

About this skill

<essential_principles>

The mining gross margin proxy (Margin Proxy) uses a simplified formula:

gross_margin_proxy = (metal_price - unit_cost) / metal_price

Where:

  • metal_price: Metal spot price or front-month futures price
  • unit_cost: AISC (All-In Sustaining Cost), cash cost (C1), or all-in cost

This indicatoris not equivalent to the gross margin in accounting statements, but it can quickly capture marginal changes in the price-cost relationship.

Basis Included items Use case
Cash Cost (C1) On-site mining + processing + site administration Cash flow stress testing
AISC C1 + sustaining capital expenditure + exploration + administration Industry standard (WGC definition)
All-In Cost (AIC) AISC + growth capital expenditure Full economic cost

It is recommended to prioritize AISC, because it has the best comparability and high data availability.

Method Formula Intuition
equal_weight Σ margin_i / N Simple average, equal weight per company
production_weighted Σ (margin_i × prod_i) / Σ prod_i Production-weighted, reflecting "industry gross margin"
marketcap_weighted Σ (margin_i × mcap_i) / Σ mcap_i Market-cap weighted, reflecting "equity exposure"

It is recommended to use production_weighted to more accurately reflect the overall industry gross margin structure.

  • Metal prices: daily frequency or monthly average prices
  • Mining costs: quarterly (most companies only disclose AISC in quarterly reports)
  • Alignment method：
    • Forward-fill costs to each period within the quarter
    • or use the same-quarter average price (cleaner)

This Skill recommends using quarterly frequency as the baseline to avoid excessive smoothing.

This skill usespublic data：

  • Gold price: LBMA Gold Price / COMEX front-month futures
  • Silver price: LBMA Silver Price / COMEX front-month futures
  • AISC: company IR investor presentations / quarterly report MD&A / press releases
  • Production: same as above, unit oz / GEO / AgEq oz

The script is located in the scripts/ directory and can be run directly.

</essential_principles>

  1. Data integration: fetch metal price series and mining cost/production data
  2. Calculate gross margin proxy: single-company level + basket aggregation
  3. Historical percentiles: determine the position of the current level within the historical range
  4. Driver decomposition: distinguish price-driven vs cost-driven
  5. Signal generation: mark extreme high/low ranges

Output: gross margin time series, historical percentiles, driver decomposition, trading/research links.

<quick_start>

The fastest way: run the preset scenario analysis

cd skills/compute-precious-miner-gross-margin
pip install pandas numpy requests yfinance beautifulsoup4 lxml  # 首次使用
python scripts/margin_calculator.py --quick --metal gold

Example output:

{
  "skill": "compute_precious_miner_margin_proxy",
  "metal": "gold",
  "frequency": "quarterly",
  "cost_metric": "AISC",
  "basket": {
    "miners": ["NEM", "GOLD", "AEM"],
    "aggregation": "production_weighted"
  },
  "latest": {
    "date": "2025-Q4",
    "metal_price_usd_oz": 2650.0,
    "unit_cost_proxy_usd_oz": 1320.0,
    "gross_margin_proxy": 0.502,
    "history_percentile": 0.78,
    "regime_label": "high_margin"
  }
}

Full scenario analysis：

python scripts/margin_calculator.py \
  --metal silver \
  --miners CDE,HL,AG \
  --start-date 2015-01-01 \
  --frequency quarterly \
  --cost-metric AISC \
  --aggregation production_weighted \
  --output result.json

</quick_start>

  1. Quick calculation - calculate the gross margin proxy for the main mining basket using default parameters
  2. Full analysis - customize parameters for scenario analysis (can select metal, mining, cost basis)
  3. Data research - learn how to obtain AISC / cost data (crawler design)
  4. Signal Generation - Convert gross margin into trading/research signals
  5. Methodology Learning - Understand the calculation logic and data sources

Please select or directly provide analysis parameters.

After routing, read the corresponding document and execute.

<directory_structure>

compute-precious-miner-gross-margin/
├── SKILL.md                           # 本文件（路由器）
├── skill.yaml                         # 前端展示元數據
├── manifest.json                      # 技能元數據
├── workflows/
│   ├── analyze.md                     # 完整情境分析工作流
│   ├── data-research.md               # 數據源研究與爬蟲設計
│   └── signal-generation.md           # 訊號生成工作流
├── references/
│   ├── data-sources.md                # 數據來源與獲取方式
│   ├── methodology.md                 # 方法論與計算邏輯
│   └── input-schema.md                # 完整輸入參數定義
├── templates/
│   ├── output-json.md                 # JSON 輸出模板
│   └── output-markdown.md             # Markdown 報告模板
├── scripts/
│   └── margin_calculator.py           # 主計算腳本
└── examples/
    └── sample-output.json             # 範例輸出

</directory_structure>

<reference_index>

Methodology: references/methodology.md

  • Definition of gross margin proxy
  • Analysis of cost basis hierarchy
  • Aggregation methods and intuition
  • Historical quantile calculation

Data Sources: references/data-sources.md

  • Gold and silver price data sources
  • AISC / cash cost data sources
  • Production data sources
  • Crawler design guidelines

Input Parameters: references/input-schema.md

  • Complete parameter definitions
  • Default values and recommended ranges
  • Default mining basket

</reference_index>

<workflows_index>

Workflow Purpose When to use
analyze.md Complete scenario analysis Need to calculate gross margin with custom parameters
data-research.md Data source research Learn how to obtain cost data
signal-generation.md Signal generation Convert gross margin into trading/research signals
</workflows_index>

<templates_index>

Template Purpose
output-json.md JSON output structure definition
output-markdown.md Markdown report template
</templates_index>

<scripts_index>

Script Command Purpose
margin_calculator.py --quick --metal gold Quick calculation for gold mining
margin_calculator.py --quick --metal silver Quick calculation for silver mining
margin_calculator.py --miners NEM,GOLD --freq Q Custom mining and frequency
margin_calculator.py --decompose Driver decomposition analysis
</scripts_index>

<input_schema_summary>

Core Parameters

Parameter Type Default value Description
metal string gold Target metal (gold/silver)
miners array Default basket Mining ticker list
start_date string 10 years ago Calculation start date (YYYY-MM-DD)
end_date string today Calculation end date
frequency string quarterly Frequency (daily/weekly/monthly/quarterly)
cost_metric string AISC Cost basis
aggregation string production_weighted Aggregation method

Advanced Parameters

Parameter Type Default value Description
price_series string spot Price basis
fx_mode string none Exchange rate handling
outlier_rule string winsorize_1_99 Outlier handling
history_window_years int 20 Historical quantile window

See the complete parameter definitions in references/input-schema.md。

</input_schema_summary>

<output_schema_summary>

{
  "skill": "compute_precious_miner_margin_proxy",
  "metal": "silver",
  "frequency": "quarterly",
  "cost_metric": "AISC",
  "basket": {
    "miners": ["CDE", "HL", "AG"],
    "aggregation": "production_weighted"
  },
  "latest": {
    "date": "2025-Q4",
    "metal_price_usd_oz": 31.50,
    "unit_cost_proxy_usd_oz": 6.30,
    "gross_margin_proxy": 0.80,
    "history_percentile": 0.94,
    "regime_label": "extreme_high_margin"
  },
  "decomposition": {
    "last_3m_price_change_pct": 0.12,
    "last_3m_cost_change_pct": -0.03,
    "driver": "mostly_price_up"
  },
  "notes": [
    "gross_margin_proxy 使用 (price - AISC)/price 作為近似；不等同會計報表的毛利率口徑。",
    "若成本為季度資料，已以季度內 forward-fill/同季均價對齊。"
  ],
  "recommended_next_checks": [
    "用同一套 margin proxy 對照 SIL/SILJ 或個股的 3/6/12 個月前瞻報酬（事件研究）",
    "檢查是否出現資本開支/併購升溫、或成本再通膨（柴油/工資/試劑）導致毛利回落"
  ]
}

See the complete output structure in templates/output-json.md。 </output_schema_summary>

<success_criteria> Successful execution should produce:

  • Gross margin proxy time-series data
  • Unit cost and gross margin for each mining company
  • Basket aggregate gross margin
  • Historical quantiles and interval labels (extreme_high/high/neutral/low/extreme_low)
  • Driver decomposition (price-driven vs cost-driven)
  • Results output in the specified format (JSON or Markdown)
  • Follow-up research recommendations </success_criteria>