# Regime Detection

Regime detection identifies the current market "behavior mode" (trending, ranging, volatile). Different strategies work in different regimes.

**Related:**
- [GLOSSARY.md](../GLOSSARY.md) — Definitions of HMM, BOCPD, etc.
- [FORECAST.md](../FORECAST.md) — Price forecasting
- [SAMPLE-TRADE-ADVANCED.md](../SAMPLE-TRADE-ADVANCED.md) — Using regimes as trade filters

---

## Why Regimes Matter

Markets cycle through distinct behavioral phases:

| Regime | Characteristics | Strategy Implication |
|--------|-----------------|---------------------|
| **Low Volatility / Ranging** | Price oscillates in a band | Mean reversion works; trend-following fails |
| **Trending** | Directional momentum | Trend-following works; mean reversion fails |
| **High Volatility / Crisis** | Large unpredictable swings | Reduce size or stay out |

A strategy that profits in one regime may lose in another. Regime detection helps you:
1. **Filter trades:** Only enter when conditions match your strategy
2. **Adjust sizing:** Reduce risk in unfavorable regimes
3. **Detect breakouts:** Identify when the market is transitioning

---

## Methods

### 1. Hidden Markov Model (HMM)

**What it does:** Classifies each bar into one of N hidden "states" based on return and volatility patterns.

**How it works:**
1. Assumes the market switches between N underlying states
2. Each state has characteristic mean return and volatility
3. Uses observed data to estimate which state is currently active

**Example:**
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method hmm --params "n_states=2"
```

**Output:**
```
summary:
  last_state: 0
  state_shares:
    0: 0.623
    1: 0.377
  state_sigma:
    0: 0.000303   # Low volatility state
    1: 0.000739   # High volatility state
```

**Interpretation:**
- **State 0:** Low volatility (σ = 0.0003) — ranging/quiet market
- **State 1:** High volatility (σ = 0.0007) — trending/active market
- Currently in State 0 (low volatility)

**Parameters:**
| Parameter | Default | Description |
|-----------|---------|-------------|
| `n_states` | 2 | Number of regimes to detect |

**When to use:**
- Ongoing regime classification
- Filtering strategies by market type
- Multi-day to multi-week analysis

---

### 2. Change-Point Detection (BOCPD)

**What it does:** Detects moments when the market's statistical properties changed.

**How it works:**
- Bayesian Online Change Point Detection
- Estimates probability that each bar marks a regime transition
- Doesn't classify regimes—just detects when changes occur

**Example:**
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method bocpd --threshold 0.5
```

**Output:**
```
summary:
  last_cp_prob: 0.471
  max_cp_prob: 0.471
  change_points_count: 0
```

**Interpretation:**
- `last_cp_prob: 0.471` — 47% probability that a regime change just occurred
- Below threshold (0.5), so not flagged as a change point
- Higher probabilities indicate likely structural breaks

**Parameters:**
| Parameter | Default | Description |
|-----------|---------|-------------|
| `threshold` | 0.5 | Probability cutoff to flag a change point |
| `lookback` | 300 | Historical bars to analyze |

**When to use:**
- Detecting breakouts
- Alerting on market structure changes
- Invalidating stale forecasts

---

### 3. Markov-Switching AR (MS-AR)

**What it does:** Combines HMM with autoregressive modeling. Each regime has its own AR parameters.

**Example:**
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method ms_ar --params "n_states=2 order=1"
```

Use `n_states` to choose the number of regimes.

**When to use:**
- When regime changes affect both mean and autocorrelation structure
- Academic research contexts

---

### 4. Clustering (`clustering`)

**What it does:** Groups bars into regimes using distance-based clustering (e.g. KMeans on return/volatility features). Does not assume a hidden Markov structure.

**Example:**
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method clustering --params "n_states=3"
```

Use `n_states` to choose the number of regimes; legacy aliases are ignored.

**When to use:**
- Exploratory regime discovery without a parametric model
- When HMM convergence is unstable

---

## Practical Strategies

### Strategy 1: Regime Filter

Only enter trend-following trades when HMM detects high-volatility state:

```bash
# Check current regime
mtdata-cli regime_detect EURUSD --timeframe H1 --method hmm --params "n_states=2"

# If state_sigma shows current state is high-volatility:
#   → Enable trend-following entries
# If current state is low-volatility:
#   → Disable trend-following or switch to mean reversion
```

### Strategy 2: Change-Point Alert

Monitor for regime transitions and reduce exposure when detected:

```bash
# Check for recent change points
mtdata-cli regime_detect EURUSD --timeframe H1 --method bocpd --threshold 0.6

# If last_cp_prob > 0.6:
#   → Tighten stops
#   → Reduce position size
#   → Consider closing positions
```

### Strategy 3: Regime-Conditional Barrier Analysis

Run barrier optimization separately for each regime:

```bash
# In low-volatility regime: tighter barriers
mtdata-cli forecast_barrier_optimize EURUSD --timeframe H1 --horizon 12 \
  --tp-min 0.15 --tp-max 0.5 --sl-min 0.1 --sl-max 0.4

# In high-volatility regime: wider barriers
mtdata-cli forecast_barrier_optimize EURUSD --timeframe H1 --horizon 12 \
  --tp-min 0.5 --tp-max 2.0 --sl-min 0.3 --sl-max 1.5
```

---

## Output Contract

### Compact TOON Output (Default)
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method hmm
```
Shows regime segments: start time, end time, duration, state ID.

### JSON Output
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method hmm --json
```
Returns structured JSON for programmatic use.

Canonical fields for successful compact/full JSON responses:

| Field | Applies to | Notes |
|-------|------------|-------|
| `method` | all methods | Normalized implementation method. For example, requesting `gmm` runs the HMM-lite implementation and reports `method: "hmm"`. |
| `requested_method` | aliases | Present when the requested method differs from `method`, such as `gmm -> hmm`. |
| `current_regime` | all methods | Uses `regime_id`, `label`, `since`, `bars`, and `regime_confidence` when those concepts apply. BOCPD also includes transition-oriented fields such as `status` and `transition_risk`. |
| `regimes` | all compact/full methods | Uses `start`, `end`, `bars`, and `regime_confidence` consistently where regime confidence applies. |
| `regime_info` | state/rule methods | Describes regime labels and statistics. Clustering labels are derived from return/volatility when available instead of opaque `regime_N` names. |
| `reliability` | all methods | Always includes `confidence`, `reliability_label`, and `source`; method-specific diagnostics may add more fields. |
| `warnings` | as needed | Explains accepted parameters that do not apply to the selected method. |

`current_regime.regime_confidence` and `regimes[].regime_confidence` are the canonical regime-confidence keys. Reliability diagnostics keep their own `reliability.confidence` field.

### Parameter applicability

Use `n_states` as the canonical state-count parameter for HMM/GMM, MS-AR, clustering, GARCH, wavelet, and ensemble. Requests that include legacy aliases such as `k_regimes` or `n_clusters` fail validation; use `n_states` only.

`threshold` only applies to BOCPD change-point detection. If supplied for non-BOCPD methods, the tool reports a warning rather than silently changing confidence filtering.

For `rule_based`, use `params.window_bars` to choose the analysis window. `lookback`, `min_regime_bars`, and `max_regimes` do not change rule-based output because it emits one current-window regime; non-default uses are reported in `warnings`.

### Auto-detected state counts

Some methods infer `n_states` when it is not explicitly supplied:

| Method | Auto-detection basis |
|--------|----------------------|
| `garch` | Realized-volatility percentile spread plus return kurtosis |
| `ensemble` | Return-distribution kurtosis |

These methods can choose different state counts on the same data because they optimize for different regime concepts: volatility tiers for GARCH and consensus return/volatility granularity for ensemble.

### Richer Sections
```bash
mtdata-cli regime_detect EURUSD --timeframe H1 --method hmm --extras metadata,diagnostics --json
```
Adds supported richer sections such as metadata and diagnostics.

---

## Quick Reference

| Task | Command |
|------|---------|
| Classify regimes (2 states) | `mtdata-cli regime_detect EURUSD --method hmm --params "n_states=2"` |
| Classify regimes (3 states) | `mtdata-cli regime_detect EURUSD --method hmm --params "n_states=3"` |
| Detect change points | `mtdata-cli regime_detect EURUSD --method bocpd --threshold 0.5` |
| Markov-switching AR | `mtdata-cli regime_detect EURUSD --method ms_ar --params "n_states=2"` |
| Clustering | `mtdata-cli regime_detect EURUSD --method clustering --params "n_states=3"` |

---

## See Also

- [GLOSSARY.md](../GLOSSARY.md) — Term definitions
- [FORECAST.md](../FORECAST.md) — Price forecasting
- [VOLATILITY.md](VOLATILITY.md) — Volatility estimation
- [BARRIER_FUNCTIONS.md](../BARRIER_FUNCTIONS.md) — TP/SL analysis
