Skip to content

Labeling

finml_core.processing.labeling

TripleBarrierLabeling(col_map, ticker_level, date_level, config=None)

Labels financial time-series using the Triple Barrier Method (TBM).

Unlike standard fixed-horizon labeling, TBM creates dynamic labels based on volatility-adjusted price targets. It effectively captures the path-dependent nature of financial assets by monitoring three concurrent barriers:

  1. Upper Barrier (Take Profit): Hit when price appreciation reaches \(P_t \cdot (1 + \text{tp}_{\text{mult}} \cdot \sigma_t)\).
  2. Lower Barrier (Stop Loss): Hit when price depreciation reaches \(P_t \cdot (1 - \text{sl}_{\text{mult}} \cdot \sigma_t)\).
  3. Vertical Barrier (Time Limit): Hit when neither price barrier is touched within a fixed window \(T\).
Mathematical Outcomes
  • 1 (Long): Upper barrier hit first.
  • -1 (Short): Lower barrier hit first.
  • 0 (Hold): Vertical barrier (Time Limit) reached.
Note

This implementation is optimized for MultiIndex DataFrames (Ticker, Date) and uses vectorized NumPy operations for the internal path-scanning loop.

Parameters:

Name Type Description Default
col_map Dict

Mapping for OHLCV columns.

Required to compute the labeling: {'close': ..., 'high': ..., 'low': ...}

Example: 

{
    'close': 'Close',
    'high': 'High',
    'low': 'Low',
}
which is yfinance standard.

 required
ticker_level str

MultiIndex level name for asset identifiers (e.g., 'Ticker').

 required
date_level str

MultiIndex level name for timestamps (e.g., 'Date').

 required
config Dict[str, Any]

Hyperparameters for the barriers.

Key Type Default Description
stop_loss_multiplier float 2.0 Volatility multiplier for SL.
take_profit_multiplier float 2.0 Volatility multiplier for TP.
time_limit int 10 Max periods to hold (Vertical Barrier).
vol_span int 100 Span for EWM Volatility calculation.
None

compute_outcomes(df)

Executes the Triple Barrier labeling process across all assets.

This method orchestrates the full pipeline
  1. Volatility Normalization: Computes dynamic \(\sigma_t\) per ticker.
  2. MultiIndex Grouping: Isolates price paths by asset to prevent cross-ticker data leakage during barrier scanning.
  3. Numpy-Vectorized Search: Triggers the internal search engine for first-touch events on future price paths.

Parameters:

Name Type Description Default
df DataFrame

MultiIndex DataFrame containing price series.

 required

Returns:

Type Description
DataFrame

A DataFrame indexed like df with labeling results:

  • target_side: The final label {1, 0, -1}.
  • transaction_return: Unrealized return at the touch moment.
  • t1: Timestamp when the first barrier was hit.
  • upper_barrier & lower_barrier: The volatility-adjusted price levels.
  • time_to_barrier: Integer steps taken to reach the outcome.
  • both_barriers_hit: Boolean flag for high-volatility gap cases.

Raises:

Type Description
KeyError

If required columns or MultiIndex levels are missing.