Labeling¶
Triple-barrier method, meta-labeling, volatility estimators, and trend scanning (AFML Ch. 3).
labeling ¶
MetaLabeler ¶
Meta-labeling model for bet sizing (AFML Ch. 3).
Wraps a primary model's predictions: generates meta-labels that indicate whether to act on the primary signal, and sizes bets based on prediction probability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_probability
|
float
|
Minimum probability threshold for a positive meta-label. |
required |
bet_size ¶
Compute bet size from a predicted probability.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
probability
|
float
|
Predicted probability of the positive class. |
required |
Returns:
| Type | Description |
|---|---|
float
|
Bet size in [0, 1]. Returns 0 if below |
generate_labels ¶
Generate binary meta-labels from events and primary predictions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
list[Event]
|
Labeled events. |
required |
primary_predictions
|
list[int]
|
Primary model's directional predictions (+1 or -1). |
required |
Returns:
| Type | Description |
|---|---|
ndarray[int32]
|
Meta-labels (0 = do not trade, 1 = trade). |
add_vertical_barrier ¶
Add vertical barriers (maximum holding period) to entry indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entry_indices
|
list[int]
|
Entry bar indices. |
required |
max_holding
|
int
|
Maximum holding period in bars. |
required |
series_len
|
int
|
Total length of the price series (for clamping). |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
Exit indices corresponding to each entry (clamped to series_len - 1). |
daily_volatility ¶
Compute daily volatility as the EWMA standard deviation of returns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prices
|
ndarray
|
Price series. |
required |
timestamps
|
list[float]
|
Unix timestamps corresponding to prices. |
required |
span
|
int
|
EWMA span for volatility estimation. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Daily volatility estimates. |
drop_rare_labels ¶
Generate a boolean mask to drop labels below a minimum frequency.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
labels
|
list[int]
|
Label vector. |
required |
min_pct
|
float
|
Minimum fraction (0 to 1) a label must represent to be kept. |
required |
Returns:
| Type | Description |
|---|---|
list[bool]
|
Mask where True means the sample's label is frequent enough. |
garman_klass_volatility ¶
Garman-Klass volatility estimator using OHLC prices.
Uses open, high, low, and close prices for a more efficient estimate than Parkinson (accounts for opening jumps).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bars
|
list[OhlcvBar]
|
OHLCV bars. |
required |
window
|
int
|
Rolling window size. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Rolling Garman-Klass volatility estimates. |
get_bins ¶
Convert events to directional labels (-1, 0, +1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
list[Event]
|
Labeled events from |
required |
Returns:
| Type | Description |
|---|---|
ndarray[int32]
|
Labels: +1 (upper touch), -1 (lower touch), 0 (vertical). |
get_events ¶
Generate triple-barrier labeled events from a price series (AFML Ch. 3).
For each entry index, finds the first barrier touch (upper profit-take, lower stop-loss, or vertical max-holding) and records the event.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prices
|
ndarray
|
Price series. |
required |
entry_indices
|
list[int]
|
Indices at which to enter positions. |
required |
config
|
TripleBarrierConfig
|
Barrier configuration (upper, lower, max holding period). |
required |
daily_vols
|
ndarray
|
Daily volatility estimates (same length as prices), used to scale barriers. |
required |
Returns:
| Type | Description |
|---|---|
list[Event]
|
Labeled events with entry/exit indices, touch type, and return. |
get_meta_bins ¶
Generate meta-labels that correct a primary model's predictions (AFML Ch. 3).
A meta-label is 1 if the primary prediction's direction matches the actual outcome, 0 otherwise.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
events
|
list[Event]
|
Labeled events from |
required |
primary_predictions
|
list[int]
|
Primary model's directional predictions (+1 or -1). |
required |
Returns:
| Type | Description |
|---|---|
ndarray[int32]
|
Meta-labels (0 or 1). |
parkinson_volatility ¶
Parkinson volatility estimator using high-low range.
More efficient than close-to-close volatility since it uses intra-bar price range information.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bars
|
list[OhlcvBar]
|
OHLCV bars. |
required |
window
|
int
|
Rolling window size. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Rolling Parkinson volatility estimates. |
trend_scanning_label_series ¶
Trend scanning label series (+1, -1, 0) for an entire price series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prices
|
ndarray
|
Price series. |
required |
max_window
|
int
|
Maximum look-ahead window. |
required |
Returns:
| Type | Description |
|---|---|
ndarray[int32]
|
Labels for each index where a label could be computed. |
trend_scanning_labels ¶
Trend scanning labels using t-statistic regression (AFML Ch. 3.5).
For each event index, fits linear regressions over multiple forward-looking windows and selects the window with the highest |t-statistic|.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prices
|
ndarray
|
Price series. |
required |
t_events
|
list[int]
|
Indices at which to compute labels. If None, uses all indices. |
None
|
max_window
|
int
|
Maximum look-ahead window. |
20
|
min_window
|
int
|
Minimum look-ahead window (default: 3). |
None
|
Returns:
| Type | Description |
|---|---|
list[TrendScanResult]
|
Per-event results with t-stat, label, best window, and R-squared. |
yang_zhang_volatility ¶
Yang-Zhang volatility estimator.
Combines overnight (close-to-open), open-to-close, and Rogers-Satchell components for a minimum-variance, drift-independent estimator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bars
|
list[OhlcvBar]
|
OHLCV bars. |
required |
window
|
int
|
Rolling window size. |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Rolling Yang-Zhang volatility estimates. |