Event Etf Study

---
name: event-etf-study
description: 基于关键事件进行ETF研究。从概念或事件出发，识别相关股票，构建市值加权ETF指数，分析事件窗口期间的市值变化，并生成交互式HTML仪表盘。当用户询问概念股、概念ETF、事件驱动分析或事件研究时使用。触发条件：提及影响A股概念板块的热门话题、政策或事件；请求构建主题ETF或概念指数；分析特定事件前后的股票表现。
---
## IMPORTANT: Output-Language Lock

- The final conversation reply and every deliverable (dashboard / charts / tables / custom_html) must follow the language of the user's latest query, not the market
- If the prompt is in English and the symbols are China / Hong Kong stocks, both the reply and the deliverables must stay in English; stock references should default to ticker code such as `600519.SH` / `0700.HK`
- If the prompt is in Chinese, both the reply and the deliverables must stay in Chinese; when a Chinese stock name is known, prefer the Chinese name
- Do not make this mistake: the HTML is in English but the actual conversation reply switches back to Chinese
- If the English stock name is uncertain, use the ticker code instead of a Chinese stock name

# Event Study ETF

## Workflow

1. **Read the pitfalls**: read `references/common_pitfalls.md` in full, then self-check against the checklist at the end before delivery.
2. **Freeze reproducibility metadata**: hard-code `query`, `language`, `event_date_source`, `generated_at`, `price_adjustment`, `market`, `data_source`, and `constituent_snapshot` in the code configuration block. Resolve `language` to a concrete `"zh"` or `"en"` string from the query text (CJK detection) before hard-coding it. Do not let reruns of the same study update these values automatically.
3. **Identify concept stocks**: search concept stocks across Tonghuashun (10jqka), Xueqiu, and East Money -> save a source snapshot CSV -> take the union as constituent candidates -> validate with mshtools/ifind -> assign T1/T2/T3 tiers by relevance. See `references/concept_research.md` for methodology.
4. **Fetch data**: use MCP ifind to fetch forward-adjusted daily prices plus total shares -> save raw returns/previews under `raw/` -> compute daily market cap.
   - Set the window length exactly to the user's request: if the user asks for "buy after the event and hold for one week", use 3-5 trading days before the event plus 1-2 weeks after the event (about 10-15 trading days).
   - General rule: `start_date = 3-5 trading days before the reference date`; `end_date = 2-3 trading days after the user's focus window`.
5. **Build the ETF**: use market cap on the pre-event reference date to calculate weights, then generate both market-cap-weighted NAV and equal-weighted NAV.
6. **Export standard files**: call `references/export_event_results.py` to produce 3 standard data files plus 1 reproducibility manifest. Always pass `market` (`"china_a"` or `"us"`) and `generated_at`.
7. **Generate the dashboard**: call `references/render_event_dashboard.py` to read the standard files and produce an HTML dashboard. Use `assets/dashboard_template.html` as the shell template. See "Dashboard Chart Selection" below for choosing modules.
8. **Static charts**: use Matplotlib to generate standalone PNG files in the cwd.
9. **Report**: write `report.md`; it must include `## Assumptions` and `## Known Limitations`.
10. **Self-check**: trial run -> 4 standard files written -> run `references/validate_event_outputs.py` -> reconcile numbers -> complete the pitfalls checklist.
11. **Deliver**: runnable code + 4 standard files + `report.md` + PNG files + HTML dashboard.

## Load On Demand

| File                                     | When to read it                                                    |
| ---------------------------------------- | ------------------------------------------------------------------ |
| `references/common_pitfalls.md`        | **Required reading**, first step for every task              |
| `references/concept_research.md`       | When identifying concept stocks or searching for related companies |
| `references/dashboard_schema.md`       | When generating or customizing the HTML dashboard                  |
| `references/export_event_results.py`   | Call when exporting standard files                                 |
| `references/render_event_dashboard.py` | Call when generating the dashboard                                 |
| `references/validate_event_outputs.py` | Validate before delivery                                           |
| `references/event_study_template.py`   | Skeleton for writing analysis code                                 |

## Standard Output Files

Write 4 files to the cwd, using the concept name as the prefix (e.g. `ai_chip`):

| File                           | Content                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `<prefix>_prices.csv`        | Daily constituent prices and market caps:`date, ticker, name, close, market_cap, tier`             |
| `<prefix>_portfolio.csv`     | Daily ETF NAV and total market cap:`date, mcap_weighted_nav, equal_weighted_nav, total_market_cap` |
| `<prefix>_summary.json`      | Summary metadata + statistics + constituent list                                                     |
| `<prefix>_run_manifest.json` | Reproducibility manifest: input hashes, parameters, dependency versions, output hashes               |

### Key Reproducibility Rules

- `generated_at` must be passed explicitly and reused for reproducible reruns.
- `language` must be resolved to `"zh"` or `"en"` and hard-coded in the configuration block.
- Weights based on market cap from the trading day before the event.
- NAV base date is `pre_event_date`, anchored at 100.
- Missing-price handling: `ffill_before_pct_change`.
- Every ifind call must record actual parameters in the manifest.
- Save constituent source snapshots as `<prefix>_constituents_sources.csv`.

## HTML Dashboard

- Use `assets/dashboard_template.html` as the shell template.
- Output one standalone HTML file: `<prefix>_dashboard.html`.
- Module selection via `include_modules` parameter. Available modules:

| Module ID    | Chart Content                                       | Suggested Scenario                       |
| ------------ | --------------------------------------------------- | ---------------------------------------- |
| `overview` | KPI cards + main NAV curve + drawdown               | **Required**                       |
| `nav`      | Market-cap-weighted vs equal-weighted NAV dual-line | When comparing weighting methods         |
| `weight`   | Tier-colored weight donut                           | When many constituents or uneven weights |
| `impact`   | Per-stock event-day/peak/latest return bars         | When analyzing stock-level reactions     |
| `mcap`     | Sector total market-cap trend area                  | When focusing on sector value changes    |
| `table`    | Constituent detail table                            | **Required**                       |

Selection guidance:

- **Full**: `["overview", "nav", "weight", "impact", "mcap", "table"]`
- **Concise**: `["overview", "nav", "table"]`
- **Stock-focused**: `["overview", "weight", "impact", "table"]`
- **Trend-focused**: `["overview", "nav", "mcap", "table"]`

### Color Scheme

Market-aware colors: China A-shares (`china_a`) use red up/green down; US equities (`us`) use green up/red down.

| Market      | Up          | Down        |
| ----------- | ----------- | ----------- |
| `china_a` | `#ef5350` | `#26a69a` |
| `us`      | `#26a69a` | `#ef5350` |

- Main chart NAV line color follows the sign of total ETF return.
- KPI cards involving gains/losses pass `raw` for market-aware coloring.
- Regular comparison charts (nav, mcap, weight) use fixed data colors: blue `#3b82f6`, orange `#f97316`, purple `#8b5cf6`.
- Tier coloring: T1 `#3b82f6`, T2 `#60a5fa`, T3 `#93c5fd`.
- Event-date marker: red dashed line `#ef4444` with white label on red background.

### `custom_html` Constraints

- DOM ids and CSS classes must use the `es-custom-` prefix.
- echarts is already loaded globally in the template.
- Titles, labels, and tooltips must use the same language as dashboard `language`.

## Matplotlib Charts

- Dark theme: dark background plus light text.
- Use red/green on the main chart to match the dashboard color scheme; blue tones for other charts.
- macOS Unicode font: `FontProperties(fname="/System/Library/Fonts/Supplemental/Arial Unicode.ttf")`.
- File name: `<prefix>_<name>.png`, `dpi=150`.

## Required Report Sections

`report.md` must include:

- `## Assumptions`: event-date source, reference-date choice, constituent criteria, weighting method, share basis, window length, price-adjustment method.
- `## Known Limitations`: survivorship bias, data coverage, excessive single-stock weight, market-cap calculation basis, and event expectations priced in before the official event date.

## Core Rules

- Use mshtools/ifind for data; do not hard-code prices.
- Proactively warn when a single-stock weight exceeds 30%.
- Always compute both market-cap-weighted and equal-weighted versions.
- Keep all output artifacts in one consistent language matching the user's query.
- The event date must be evidence-backed.

## Out Of Scope

Options/derivatives pricing, live trading, deep single-stock fundamental analysis, and cross-market arbitrage.