Stock Correlation

# stock-correlation

Analyze stock correlations to find related companies, sector peers, and pair-trading candidates using historical price data.

## What it does

Routes to four specialized sub-skills based on user intent:

- **Co-movement Discovery** — given a single ticker, find the most correlated stocks from curated sector and thematic peer universes (e.g., "what correlates with NVDA?")
- **Return Correlation** — deep-dive pairwise analysis between two tickers: Pearson correlation, beta, R-squared, spread Z-score, and rolling stability (e.g., "correlation between AMD and NVDA")
- **Sector Clustering** — full NxN correlation matrix with hierarchical clustering to identify groups and outliers (e.g., "correlation matrix for FAANG")
- **Realized Correlation** — time-varying and regime-conditional correlation: rolling windows (20/60/120-day), up vs down days, high-vol vs low-vol, drawdown regimes (e.g., "when NVDA drops what else drops?")

## Triggers

- "what correlates with NVDA", "find stocks related to AMD"
- "correlation between AAPL and MSFT", "how do LITE and COHR move together"
- "what moves with", "stocks that move together", "sympathy plays"
- "sector peers", "pair trading", "hedging pair"
- "when NVDA drops what else drops", "rolling correlation"
- "correlation matrix for FAANG", "cluster these stocks"
- Well-known pairs: AMD/NVDA, GOOGL/AVGO, LITE/COHR

## Prerequisites

- Python 3.8+
- The skill auto-installs `yfinance`, `pandas`, and `numpy` via pip if not already present
- `scipy` is optional (used for hierarchical clustering in Sector Clustering sub-skill; falls back to sorting if unavailable)

## Platform

Works on **all platforms** (Claude Code, Claude.ai with code execution, etc.).

## Setup

```bash
# As a plugin (recommended — installs all skills)
npx plugins add himself65/finance-skills --plugin finance-market-analysis

# Or install just this skill
npx skills add himself65/finance-skills --skill stock-correlation
```

See the [main README](../../../../README.md) for more installation options.

## Reference files

- `references/sector_universes.md` — Dynamic peer universe construction using yfinance Screener API, with fallback strategies


# Dynamic Peer Universe Construction

How to build a peer universe at runtime for correlation analysis. **Do not hardcode ticker lists** — fetch them dynamically so results stay current.

---

## Method 1: Same-Sector Screen (Primary)

Use yfinance's `yf.screen()` + `EquityQuery` to find stocks in the same sector as the target. Note: the screener supports filtering by `sector` but not directly by `industry` — use sector-level screening and let the correlation math surface the closest peers.

```python
import yfinance as yf
from yfinance import EquityQuery

def get_sector_peers(ticker_symbol, min_market_cap=1_000_000_000, max_results=30):
    """Find peers in the same sector above a market cap threshold."""
    target = yf.Ticker(ticker_symbol)
    info = target.info
    sector = info.get("sector", "")

    if not sector:
        return []

    # Screen for same-sector stocks on major US exchanges
    query = EquityQuery("and", [
        EquityQuery("eq", ["sector", sector]),
        EquityQuery("gt", ["intradaymarketcap", min_market_cap]),
        EquityQuery("is-in", ["exchange", "NMS", "NYQ"]),
    ])

    result = yf.screen(query, size=max_results, sortField="intradaymarketcap", sortAsc=False)

    peers = []
    for quote in result.get("quotes", []):
        symbol = quote.get("symbol", "")
        if symbol and symbol != ticker_symbol:
            peers.append(symbol)

    return peers
```

## Method 2: Thematic Expansion

For cross-sector correlations (e.g., AI supply chain spans semis + cloud + software), read the target's business description and screen adjacent sectors:

```python
def get_thematic_context(ticker_symbol):
    """Get company context to inform adjacent-sector screening."""
    target = yf.Ticker(ticker_symbol)
    info = target.info
    return {