analyze-retail-inverse-etf-allocation

<essential_principles> Retail Leveraged Inverse ETF Short Allocation Analysis Core Principles

Steps：

1. Download OHLCV data for inverse/positive leveraged ETFs and the benchmark index
2. Calculate the dollar volume ratio (or AUM proxy) as the short allocation indicator
3. Standardize using rolling quantiles to detect extremely low short allocation events
4. Identify historical analog events and calculate forward risk statistics
5. Generate conclusions and charts

Not Applicable Scenarios：

• Non-US equity markets (different ETF tickers)
• Very short-term intraday trading timing
• Institutional-grade hedging strategy monitoring (this indicator leans toward retail behavior)

<quick_start> Quick Start

# 安裝依賴
pip install yfinance pandas numpy matplotlib

# 完整分析（預設參數）
python scripts/inverse_etf_analyzer.py --start 2012-01-01 --end 2026-02-01

# 快速檢查當前狀態
python scripts/inverse_etf_analyzer.py --start 2012-01-01 --end 2026-02-01 --quick

# 自訂 ETF 清單
python scripts/inverse_etf_analyzer.py --start 2012-01-01 --end 2026-02-01 \
  --inverse SPXU SDS SH --long UPRO SSO SPY

</quick_start>

1. Full Analysis - Calculate the short allocation ratio, detect extreme values, event study, forward risk statistics
2. Visualization - Generate a chart of SPX + short allocation + event markers
3. Historical Event Comparison - List historical events of extremely low short allocation and subsequent market performance
4. Quick Check - View only the current short allocation status and quantile

Wait for a response before continuing.

After reading the workflow, please follow its steps exactly.

<reference_index> Reference Documents (references/)

Document	Content
methodology.md	Short allocation ratio calculation method, quantile standardization, event study framework
data-sources.md	Data source description (Yahoo Finance ETF OHLCV), fallback, licensing
input-schema.md	Definitions, types, default values, and validation rules for all input parameters
</reference_index>

<workflows_index>

Workflow	Purpose
analyze.md	Full analysis workflow (data acquisition → indicator calculation → event detection → risk statistics → conclusion generation)
visualize.md	Chart generation workflow (SPX + short allocation dual-axis chart + event vertical lines)
historical-episodes.md	Historical event comparison workflow (list past trigger events and subsequent performance)
</workflows_index>

<templates_index>

Template	Purpose
output-json.md	JSON output template (for program/dashboard consumption)
output-markdown.md	Markdown output template (for human reading/community sharing)
</templates_index>

<scripts_index>

Script	Purpose
inverse_etf_analyzer.py	Main analysis script: data acquisition, indicator calculation, event detection, risk statistics
visualize_allocation.py	Visualization script: dual-axis chart generation
</scripts_index>

<success_criteria> When the Skill executes successfully:

• Successfully download OHLCV data for all specified ETFs
• Calculate the short allocation ratio (short_alloc) and quantile
• Detect historical trigger events (if any exist)
• Calculate forward risk statistics for each event
• Generate JSON + Markdown conclusion output
• Conclusions include caveats (a risk distribution signal, not a timing tool) </success_criteria>

<examples_index> Example Output (examples/)

Document	Content
sample_output.json	Example JSON output for full analysis
</examples_index>