Analysis

---
name: analysis
description: "Guide Kalshi, Polymarket, and cross-venue analysis workflows for
  prediction-market-analysis."
metadata:
  disco-role: operating
disable-model-invocation: true
license: MIT
---

# analysis

Use this sub-skill for anything that runs, interprets, or extends the repo's analysis classes.
It covers both the menu-driven CLI and the Python `Analysis` framework.

## Use this route when

- The user wants to run a named analysis or all analyses.
- The user wants calibration, return, volume, category, or statistical-study guidance.
- The user wants a new analysis class or a fix to an existing one.
- The user wants help understanding `Analysis`, `AnalysisOutput`, or `ChartConfig`.

## Scope

### Included

- Kalshi calibration and pricing analyses.
- Kalshi maker/taker, category, hour-of-day, and volume analyses.
- Kalshi meta statistics and paper-style statistical tests.
- Polymarket calibration, volume, and trade-time analyses.
- The cross-venue animated calibration comparison.
- `Analysis.save()` output formats and `ChartConfig` JSON export.

### Excluded

- Market/trade/block backfills and cursor recovery, which belong to `sub-skills/indexing/`.
- Dataset download, archive creation, and host-tool installation, which belong to `sub-skills/data-ops/`.

## Read first

- `../../references/analysis-catalog.md` for the full analysis list.
- `../../references/api-reference.md` for the `Analysis` and `ChartConfig` APIs.
- `../../references/data-layout.md` for the required Parquet inputs.
- `../../references/troubleshooting.md` for cross-cutting failures.

## Core workflow

1. Identify the analysis name from the catalog or from `scripts/catalog.py`.
2. Confirm the required input directories exist.
3. Run the analysis with `uv run main.py analyze <name>` or the equivalent wrapper.
4. Read the saved outputs under `output/<analysis-name>.*`.
5. If the analysis is missing, thin, or failing, inspect the relevant source module and the family-specific troubleshooting notes.

## Analysis families

### Kalshi calibration and pricing

Use these when the task is about price calibration, mispricing, or expected value:

- `win_rate_by_price`
- `mispricing_by_price`
- `win_rate_by_trade_size`
- `ev_yes_vs_no`

Typical inputs:
`data/kalshi/trades/`, `data/kalshi/markets/`.

### Kalshi time and volume

Use these when the task is about temporal trends or notional volume:

- `returns_by_hour`
- `vwap_by_hour`
- `volume_over_time`
- `longshot_volume_share_over_time`
- `kalshi_calibration_deviation_over_time`
- `maker_taker_gap_over_time`

Typical inputs:
`data/kalshi/trades/`, sometimes `data/kalshi/markets/`.

### Kalshi maker/taker and category studies

Use these when the task compares makers and takers, direction, or category grouping:

- `trade_size_by_role`
- `maker_returns_by_direction`
- `maker_win_rate_by_direction`
- `maker_vs_taker_returns`
- `maker_taker_returns_by_category`
- `market_types`
- `yes_vs_no_by_price`
- `meta_stats`
- `statistical_tests`

Typical inputs:
`data/kalshi/trades/`, `data/kalshi/markets/`, and `src.analysis.kalshi.util.categories`.

### Polymarket analyses

Use these when the task is about Polymarket calibration, volume, or block-level trade history:

- `polymarket_win_rate_by_price`
- `polymarket_calibration_by_bucket`
- `polymarket_volume_over_time`
- `polymarket_trades_over_time`

Typical inputs:
`data/polymarket/trades/`, `data/polymarket/legacy_trades/`, `data/polymarket/markets/`, `data/polymarket/blocks/`, and `data/polymarket/fpmm_collateral_lookup.json`.

### Cross-venue comparison

Use `win_rate_by_price_animated` when the user wants a single workflow that compares Kalshi and Polymarket in one animated calibration plot.

Typical inputs:
Both platforms' data directories plus `data/polymarket/blocks/` and the collateral lookup file.

## Adding or fixing an analysis

- Subclass `Analysis`.
- Set a stable `name` and a human-readable `description` in `__init__`.
- Keep data selection, transformations, figure creation, and chart serialization inside `run()` or helper methods.
- Return `AnalysisOutput`.
- Use `self.progress()` for longer SQL or dataframe steps.
- Prefer `ChartConfig` helpers when the analysis should also emit JSON chart output.
- Use the category helpers from `src.analysis.kalshi.util.categories` when grouping Kalshi markets.

## Common failure patterns

- Missing or empty `data/` subtrees.
- No finalized or resolved markets, leading to empty dataframes.
- Missing Polymarket helper files, especially the collateral lookup or block timestamps.
- `Analysis.load()` returning no classes because the command was run from the wrong directory.
- Matplotlib backend issues on headless hosts.

## Helpful helper

- `../../scripts/catalog.py` lists the analysis names without opening the interactive menu when run through the repo environment.