rhoa.targets

Target Generation for Financial Time Series Analysis

This module provides tools for generating optimized binary classification targets based on future price movements in financial time series data. It supports two optimization strategies: Pareto multi-objective optimization and elbow method threshold selection.

Core Functionality

Generate 8 target combinations using different entry/exit price definitions
Automatic parameter optimization for lookback periods and thresholds
Support for both end-of-period and maximum-during-period gain calculations
Flexible class balance targeting or elbow-based threshold selection

Target Methods

The module generates eight distinct target definitions, each representing a different combination of entry price (Close[t] or High[t]) and exit price (end-of-period or maximum-during-period):

Close[t+N] / Close[t] - Conservative entry, end-point exit
Close[t+N] / High[t] - Aggressive entry, end-point exit
High[t+N] / Close[t] - Conservative entry, high exit
High[t+N] / High[t] - Aggressive entry, high exit
max(Close[t+1:t+N]) / Close[t] - Conservative entry, optimal close exit
max(Close[t+1:t+N]) / High[t] - Aggressive entry, optimal close exit
max(High[t+1:t+N]) / Close[t] - Conservative entry, optimal high exit
max(High[t+1:t+N]) / High[t] - Aggressive entry, optimal high exit

Optimization Modes

Auto Mode (Pareto Optimization): Searches the space of (period, threshold) combinations to find Pareto-optimal solutions that balance three objectives: - Maximize threshold (higher precision requirements) - Minimize period (shorter holding time) - Minimize deviation from target class balance
Manual Mode (Elbow Method): Uses a fixed lookback period and finds the optimal threshold using the elbow/knee point detection on the curve of instance counts vs. thresholds.

Mathematical Background

Pareto Optimization: A solution is Pareto-optimal if no other solution exists that improves at least one objective without worsening any other. For point A to dominate B: - A must be better than B in at least one objective - A must be no worse than B in all other objectives
Elbow Method: Identifies the point of maximum curvature on a convex decreasing curve by finding the point with maximum perpendicular distance from the line connecting curve endpoints.

Dependencies

pandas : DataFrame operations and time series handling
numpy : Numerical computations
kneed : Elbow/knee point detection (KneeLocator)
paretoset : Pareto frontier computation

Notes

Look-ahead Bias Warning:: These targets use future price information and should only be used for target creation in supervised learning. Never use future data for feature engineering or training, only for defining what the model should predict.
NaN Handling:: The last N rows (where N is the lookback period) will contain NaN values due to insufficient future data. These should be excluded from analysis.
Class Imbalance:: Very low target_class_balance (< 0.1) may result in insufficient positive examples. Very high values (> 0.9) may result in overly easy targets with poor discrimination.

Examples

Basic usage with auto mode:

>>> import pandas as pd
>>> import numpy as np
>>> from rhoa.targets import generate_target_combinations
>>>
>>> # Load your OHLC data
>>> df = pd.read_csv('prices.csv', index_col='Date', parse_dates=True)
>>>
>>> # Generate targets with 50% class balance
>>> targets, metadata = generate_target_combinations(
...     df, mode='auto', target_class_balance=0.5
... )
>>>
>>> print(f"Generated {len(targets.columns)} targets")
>>> print(f"Target_1 has {targets['Target_1'].sum()} positive instances")

Manual mode with fixed period:

>>> targets, metadata = generate_target_combinations(
...     df, mode='manual', lookback_periods=10
... )
>>> print(f"Method 1 threshold: {metadata['method_1']['threshold']}%")

See also

_find_optimal_params_pareto: Pareto optimization for auto mode.
_find_optimal_params_elbow: Elbow method for manual mode.
_generate_targets: Generates target columns from optimal parameters.

Notes

Target Interpretation:

Targets 1-4 measure end-of-period gains (single point in time at t+N).
Targets 5-8 measure maximum gains during the period (any time in [t+1, t+N]).
Using High[t] as denominator (Targets 2, 4, 6, 8) is more conservative than Close[t], as it requires overcoming intraday peaks.
Maximum-based targets (5-8) capture exit opportunities that might occur before the end of the lookback period.

Pareto Optimization (Auto Mode):

The Pareto optimization finds solutions that are not dominated by any other solution in the objective space. A solution A dominates solution B if:

A is better than B in at least one objective
A is no worse than B in all other objectives

For this problem, we optimize three objectives:

Maximize threshold (prefer higher gain requirements)
Minimize period (prefer shorter holding periods)
Minimize deviation from target class balance

From the Pareto-optimal set, we select the solution closest to the target class balance.

Elbow Method (Manual Mode):

The elbow method finds the “knee” or “elbow” point on the curve of instance counts vs. thresholds. This point represents the optimal trade-off where:

Increasing threshold further causes steep drops in instances (high cost)
Decreasing threshold provides diminishing returns in instances

Mathematically, the elbow is found by maximizing the distance from the curve to the line connecting the endpoints.

Common Pitfalls:

Insufficient data: Ensure df has enough rows for the lookback period.
Look-ahead bias: Do not use future data for training; only for target creation.
Class imbalance: Very low or very high target_class_balance may yield poor results.
NaN handling: Last N rows will have NaN targets due to insufficient future data.

Examples

Example 1: Auto mode with default parameters

>>> import pandas as pd
>>> import numpy as np
>>> from rhoa.targets import generate_target_combinations
>>>
>>> # Create sample OHLC data
>>> np.random.seed(42)
>>> dates = pd.date_range('2020-01-01', periods=100, freq='D')
>>> df = pd.DataFrame({
...     'Close': 100 + np.cumsum(np.random.randn(100)),
...     'High': 100 + np.cumsum(np.random.randn(100)) + 1
... }, index=dates)
>>>
>>> # Generate targets with auto mode
>>> targets, meta = generate_target_combinations(df, mode='auto')
>>>
>>> # Check results
>>> print(f"Mode: {meta['mode']}")
Mode: auto
>>> print(f"Target_7 period: {meta['method_7']['period']}")
Target_7 period: 6
>>> print(f"Target_7 threshold: {meta['method_7']['threshold']}%")
Target_7 threshold: 4.0%
>>> print(f"Positive instances: {targets['Target_7'].sum()}")
Positive instances: 249

Example 2: Manual mode with custom lookback period

>>> # Generate targets with manual mode
>>> targets, meta = generate_target_combinations(
...     df,
...     mode='manual',
...     lookback_periods=10,
...     min_pct=0,
...     max_pct=20,
...     step=1
... )
>>>
>>> # Check results for method 1
>>> method_1 = meta['method_1']
>>> print(f"Period: {method_1['period']}, Threshold: {method_1['threshold']}%")
Period: 10, Threshold: 6.0%
>>> print(f"Instances: {method_1['instances']} ({method_1['pct_of_max']:.1f}% of max)")
Instances: 22 (1.4% of max)

Example 3: Target specific class balance

>>> # Aim for 30% positive instances
>>> targets, meta = generate_target_combinations(
...     df,
...     mode='auto',
...     target_class_balance=0.3,
...     min_period=1,
...     max_period=15
... )
>>>
>>> # Verify class balance for each target
>>> for i in range(1, 9):
...     positive_pct = targets[f'Target_{i}'].sum() / len(targets) * 100
...     print(f"Target_{i}: {positive_pct:.1f}% positive")
Target_1: 29.5% positive
Target_2: 30.2% positive
...

Example 4: Custom column names

>>> # DataFrame with different column names
>>> df_custom = df.rename(columns={'Close': 'close_price', 'High': 'high_price'})
>>> targets, meta = generate_target_combinations(
...     df_custom,
...     mode='auto',
...     close_col='close_price',
...     high_col='high_price'
... )
>>> print(targets.columns.tolist())
['Target_1', 'Target_2', 'Target_3', 'Target_4', 'Target_5', 'Target_6', 'Target_7', 'Target_8']

References