ml4t-meta-labels · diff
git:20260901.f84f825 to git:20260901.830d7a8
29 added, 30 removed. Audit A to A.
---
name: ml4t-meta-labels
description: "Secondary model predicts whether a primary signal will be profitable. Use when sizing positions or filtering low-conviction trades from a base alpha model."
when_to_use: "Use when a signal has decent recall but too many false positives"
dependencies: [triple-barrier]
metadata:
book_chapters: "7"
library: "ml4t-engineer"
paths: ["**/*feature*.py", "**/*label*.py", "**/*barrier*.py", "**/*store*.py", "**/*horizon*.py", "**/*meta_label*.py", "**/*microstructure*.py", "**/*regime*.py", "**/*selection*.py"]
---
# Meta-Labels
A momentum signal fires 1,000 times per year but only 40% are profitable. Instead of discarding the signal, train a second model to predict *which* of those 1,000 trades will work.
## The Problem
Raw trading signals typically have acceptable recall (they catch most real moves) but poor precision (many false positives). Tuning the primary model to improve precision degrades recall. Meta-labeling decouples the two: the primary model generates candidates, the meta-model filters them.
## The Pattern
### WRONG
```python
from sklearn.ensemble import GradientBoostingClassifier
# Use raw signal directly - many false positives passed through
signal = primary_model.predict(X) # 1=buy, -1=sell, 0=hold
positions = signal # Every signal becomes a trade
```
### CORRECT
```python
import numpy as np
from sklearn.ensemble import GradientBoostingClassifier
from sklearn.model_selection import TimeSeriesSplit
- # Stage 1: primary signal (direction). These have to BE out-of-fold predictions
- # already - a primary fitted on X leaks its training rows into the meta-model.
- signal = primary_model.predict(X) # 1=buy, -1=sell, 0=hold
+ def purged(split, horizon):
+ """Drop training rows whose label window reaches into the test fold."""
+ for train, test in split:
+ yield train[train < test[0] - horizon], test
- # Stage 2: Meta-model filters which signals to act on
- fired = np.flatnonzero(signal != 0)
- X_meta, y_meta = X[fired], outcomes[fired] # outcomes: 1=profitable, 0=not
+ def oof_signal(X, y, splits):
+ """Primary predictions, each from a model that never saw that row."""
+ out = np.zeros(len(X))
+ for train, test in splits:
+ out[test] = fit_primary(X[train], y[train]).predict(X[test])
+ return out
- # The meta-model has to score rows it did not fit. Fitting and predicting on
- # the same samples grades the filter on its own training set.
- prob_win = np.full(len(fired), np.nan)
- for train, test in TimeSeriesSplit(n_splits=5).split(X_meta): # purge: ml4t-purging-embargo
- meta_model = GradientBoostingClassifier(n_estimators=100, max_depth=3)
- meta_model.fit(X_meta[train], y_meta[train])
- prob_win[test] = meta_model.predict_proba(X_meta[test])[:, 1]
+ signal = np.zeros(len(X))
+ prob_win = np.full(len(X), np.nan)
+ for train, test in purged(TimeSeriesSplit(n_splits=5).split(X), horizon):
+ # Inner folds first. Fitting the meta-model on primary predictions the
+ # primary made in sample teaches it the primary's memorisation, not its edge.
+ inner = purged(TimeSeriesSplit(n_splits=3).split(X[train]), horizon)
+ fired = oof_signal(X[train], y[train], inner) != 0
+ meta = GradientBoostingClassifier(n_estimators=100, max_depth=3)
+ meta.fit(X[train][fired], outcomes[train][fired]) # 1=profitable, 0=not
- positions = np.zeros(len(X))
- positions[fired] = signal[fired] * (prob_win > 0.55) # NaN compares False
+ signal[test] = fit_primary(X[train], y[train]).predict(X[test])
+ acted = test[signal[test] != 0]
+ prob_win[acted] = meta.predict_proba(X[acted])[:, 1]
+
+ positions = np.where(prob_win > 0.55, signal, 0.0) # NaN compares False
```
## Two-Stage Architecture
```
Primary Model ──→ Signal (direction + timing)
│
▼ (only where signal fired)
Meta-Model ──→ P(profitable) ──→ Filter / Size position
```
- The meta-model receives the *same features* plus signal-specific features:
-
- ```python
- # Additional features for the meta-model
- meta_features = np.column_stack([
- X[fired], # Original features
- np.abs(signal_score[fired]), # Primary model confidence
- volatility[fired], # Current vol regime
- recent_win_rate[fired], # Rolling hit rate of primary
- ])
- ```
+ The meta-model receives the *same features* plus signal-specific ones: the
+ primary's own confidence, the current volatility regime, and its rolling hit
+ rate. Build them from the outer training fold only, like everything else here.
## Position Sizing
- Meta-label probabilities naturally map to position sizes:
-
```python
- # Kelly-inspired sizing: size proportional to edge. Size history from the
- # out-of-fold prob_win above; the last fold's model is for future rows only.
+ # Kelly-inspired sizing: size proportional to edge. Every prob_win above is an
+ # out-of-fold score; refit on all of it for rows after the last fold.
edge = 2 * np.nan_to_num(prob_win, nan=0.5) - 1 # unscored rows get zero size
position_size = base_size * np.clip(edge, 0, 1)
```
## Guardrails
- **Meta-model never overrides direction** - it only decides whether to act, and how much
- **Separate CV for primary and meta** - meta-model must not see primary's test data
- **Requires sufficient primary signals** - if primary fires <100 times, meta-model will overfit
## Production Implementation
`ml4t-engineer` provides integrated meta-labeling with triple-barrier outcomes:
```python
from ml4t.engineer.config import LabelingConfig
from ml4t.engineer.labeling import atr_triple_barrier_labels, meta_labels
config = LabelingConfig.atr_barrier(
atr_tp_multiple=2.0,
atr_sl_multiple=1.5,
atr_period=14,
max_holding_period=10,
)
labeled = atr_triple_barrier_labels(df, config=config, price_col="close")
labeled = labeled.with_columns(primary_signal.alias("signal"))
meta = meta_labels(labeled, signal_col="signal", return_col="label_return")
# Returns: original signal plus binary meta_label for trade filtering/sizing
```
## Checklist
- [ ] Primary model has persistent, fold-stable IC (check worst-fold, not just mean)
- [ ] Meta-model trained only on samples where primary signal fired
- [ ] CV is nested: primary and meta models use separate folds
- [ ] Meta-model probability used for position sizing or filtering
- [ ] Sufficient signal count (>200) to train meta-model reliably