signalflow-trading 0.2.1__py3-none-any.whl

signalflow/target/triple_barrier.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+import numpy as np
+import polars as pl
+from numba import njit, prange
+
+from signalflow.core import sf_component, SignalType 
+from signalflow.target.base import Labeler
+
+
+@njit(parallel=True, cache=True)
+def _find_first_hit(
+    prices: np.ndarray,
+    pt: np.ndarray,
+    sl: np.ndarray,
+    lookforward: int,
+) -> tuple[np.ndarray, np.ndarray]:
+    n = len(prices)
+    up_off = np.zeros(n, dtype=np.int32)
+    dn_off = np.zeros(n, dtype=np.int32)
+
+    for i in prange(n):
+        pt_i = pt[i]
+        sl_i = sl[i]
+
+        if np.isnan(pt_i) or np.isnan(sl_i):
+            continue
+
+        max_j = min(i + lookforward, n - 1)
+
+        for k in range(1, max_j - i + 1):
+            j = i + k
+            p = prices[j]
+            if up_off[i] == 0 and p >= pt_i:
+                up_off[i] = k
+            if dn_off[i] == 0 and p <= sl_i:
+                dn_off[i] = k
+            if up_off[i] > 0 and dn_off[i] > 0:
+                break
+
+    return up_off, dn_off
+
+
+@dataclass
+@sf_component(name="triple_barrier")
+class TripleBarrierLabeler(Labeler):
+    """
+    Triple-Barrier Labeling (De Prado), Numba-accelerated.
+
+    Volatility-based barriers:
+      - pt = close * exp(vol * profit_multiplier)
+      - sl = close * exp(-vol * stop_loss_multiplier)
+    """
+
+    price_col: str = "close"
+
+    vol_window: int = 60
+    lookforward_window: int = 1440
+    profit_multiplier: float = 1.0
+    stop_loss_multiplier: float = 1.0
+
+    def __post_init__(self) -> None:
+        if self.vol_window <= 1:
+            raise ValueError("vol_window must be > 1")
+        if self.lookforward_window <= 0:
+            raise ValueError("lookforward_window must be > 0")
+        if self.profit_multiplier <= 0 or self.stop_loss_multiplier <= 0:
+            raise ValueError("profit_multiplier/stop_loss_multiplier must be > 0")
+
+        cols = [self.out_col]
+        if self.include_meta:
+            cols += list(self.meta_columns)
+        self.output_columns = cols
+
+    def compute_group(
+        self, group_df: pl.DataFrame, data_context: dict[str, Any] | None
+    ) -> pl.DataFrame:
+        if self.price_col not in group_df.columns:
+            raise ValueError(f"Missing required column '{self.price_col}'")
+
+        if group_df.height == 0:
+            return group_df
+
+        lf = int(self.lookforward_window)
+        vw = int(self.vol_window)
+
+        df = group_df.with_columns(
+            (pl.col(self.price_col) / pl.col(self.price_col).shift(1))
+            .log()
+            .rolling_std(window_size=vw, ddof=1)
+            .alias("_vol")
+        ).with_columns(
+            [
+                (
+                    pl.col(self.price_col)
+                    * (pl.col("_vol") * self.profit_multiplier).exp()
+                ).alias("_pt"),
+                (
+                    pl.col(self.price_col)
+                    * (-pl.col("_vol") * self.stop_loss_multiplier).exp()
+                ).alias("_sl"),
+            ]
+        )
+
+        prices = df.get_column(self.price_col).to_numpy().astype(np.float64)
+        pt = df.get_column("_pt").fill_null(np.nan).to_numpy().astype(np.float64)
+        sl = df.get_column("_sl").fill_null(np.nan).to_numpy().astype(np.float64)
+
+        up_off, dn_off = _find_first_hit(prices, pt, sl, lf)
+
+        up_off_series = pl.Series("_up_off", up_off).replace(0, None).cast(pl.Int32)
+        dn_off_series = pl.Series("_dn_off", dn_off).replace(0, None).cast(pl.Int32)
+
+        df = df.with_columns([up_off_series, dn_off_series])
+
+        df = self._apply_labels(df)
+
+        if self.include_meta:
+            df = self._compute_meta(df, prices, up_off_series, dn_off_series, lf)
+
+        if (
+            self.mask_to_signals
+            and data_context is not None
+            and "signal_keys" in data_context
+        ):
+            df = self._apply_signal_mask(df, data_context, group_df)
+
+        drop_cols = ["_vol", "_pt", "_sl", "_up_off", "_dn_off"]
+        df = df.drop([c for c in drop_cols if c in df.columns])
+
+        return df
+
+    def _apply_labels(self, df: pl.DataFrame) -> pl.DataFrame:
+        """Apply RISE/FALL/NONE labels based on barrier hits."""
+        choose_up = pl.col("_up_off").is_not_null() & (
+            pl.col("_dn_off").is_null() | (pl.col("_up_off") <= pl.col("_dn_off"))
+        )
+        choose_dn = pl.col("_dn_off").is_not_null() & (
+            pl.col("_up_off").is_null() | (pl.col("_dn_off") < pl.col("_up_off"))
+        )
+
+        return df.with_columns(
+            pl.when(choose_up)
+            .then(pl.lit(SignalType.RISE.value))
+            .when(choose_dn)
+            .then(pl.lit(SignalType.FALL.value))
+            .otherwise(pl.lit(SignalType.NONE.value))
+            .alias(self.out_col)
+        )
+
+    def _compute_meta(
+        self,
+        df: pl.DataFrame,
+        prices: np.ndarray,
+        up_off_series: pl.Series,
+        dn_off_series: pl.Series,
+        lf: int,
+    ) -> pl.DataFrame:
+        """Compute t_hit and ret meta columns."""
+        n = df.height
+        ts_arr = df.get_column(self.ts_col).to_numpy()
+
+        idx = np.arange(n)
+        up_np = up_off_series.fill_null(0).to_numpy()
+        dn_np = dn_off_series.fill_null(0).to_numpy()
+
+        hit_off = np.where(
+            (up_np > 0) & ((dn_np == 0) | (up_np <= dn_np)),
+            up_np,
+            np.where(dn_np > 0, dn_np, 0),
+        )
+
+        hit_idx = np.clip(idx + hit_off, 0, n - 1)
+        vert_idx = np.clip(idx + lf, 0, n - 1)
+        final_idx = np.where(hit_off > 0, hit_idx, vert_idx)
+
+        t_hit = ts_arr[final_idx]
+        ret = np.where(prices > 0, np.log(prices[final_idx] / prices), np.nan)
+
+        return df.with_columns(
+            [
+                pl.Series("t_hit", t_hit),
+                pl.Series("ret", ret),
+            ]
+        )

signalflow/utils/__init__.py

@@ -0,0 +1,7 @@
+from signalflow.utils.import_utils import import_model_class
+from signalflow.utils.tune_utils import build_optuna_params
+
+__all__ = [
+    "import_model_class",
+    "build_optuna_params",
+]

signalflow/utils/import_utils.py

@@ -0,0 +1,11 @@
+def import_model_class(class_path: str) -> type:
+    """Dynamically import model class from string path."""
+    parts = class_path.rsplit(".", 1)
+    if len(parts) == 2:
+        module_name, class_name = parts
+    else:
+        raise ValueError(f"Invalid class path: {class_path}")
+
+    import importlib
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)

signalflow/utils/tune_utils.py

@@ -0,0 +1,19 @@
+import optuna
+from typing import Any
+
+
+def build_optuna_params(trial: optuna.Trial, tune_space: dict[str, tuple]) -> dict[str, Any]:
+    """Build hyperparameters from optuna trial."""
+    params = {}
+    for name, spec in tune_space.items():
+        param_type = spec[0]
+        if param_type == "int":
+            params[name] = trial.suggest_int(name, spec[1], spec[2])
+        elif param_type == "float":
+            params[name] = trial.suggest_float(name, spec[1], spec[2])
+        elif param_type == "log_float":
+            params[name] = trial.suggest_float(name, spec[1], spec[2], log=True)
+        elif param_type == "categorical":
+            params[name] = trial.suggest_categorical(name, spec[1])
+    return params
+

signalflow/validator/__init__.py

@@ -0,0 +1,6 @@
+from signalflow.validator.base import SignalValidator
+from signalflow.validator.sklearn_validator import SklearnSignalValidator
+__all__ = [
+    "SignalValidator",
+    "SklearnSignalValidator",
+]

signalflow/validator/base.py

@@ -0,0 +1,139 @@
+"""
+Base Signal Validator for SignalFlow.
+
+Signal validators (meta-labelers) predict the quality/risk of trading signals.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from pathlib import Path
+
+import polars as pl
+import numpy as np
+
+from signalflow.core import SfComponentType, Signals
+
+
+@dataclass
+class SignalValidator:
+    """Base class for signal validators (meta-labelers).
+    
+    Validates trading signals by predicting their risk/quality.
+    In De Prado's terminology - this is a meta-labeler.
+    
+    Note: Filtering to active signals (RISE/FALL only) should be done
+    BEFORE passing data to fit. This keeps the validator simple
+    and gives users full control over data preparation.
+    
+    Attributes:
+        model: The trained model instance
+        model_type: String identifier for model type (e.g., "lightgbm", "xgboost")
+        model_params: Parameters for model initialization
+        train_params: Parameters for training (e.g., early stopping)
+        tune_enabled: Whether hyperparameter tuning is enabled
+        tune_params: Parameters for tuning (e.g., n_trials, cv_folds)
+        feature_columns: List of feature column names (set after fit)
+    """
+    
+    component_type: ClassVar[SfComponentType] = SfComponentType.VALIDATOR
+    
+    model: Any | None = None
+    model_type: str | None = None
+    model_params: dict | None = None
+    
+    train_params: dict | None = None
+    tune_enabled: bool = False
+    tune_params: dict | None = None
+    
+    feature_columns: list[str] | None = field(default=None, repr=False)
+    pair_col: str = "pair"
+    ts_col: str = "timestamp"
+
+    def fit(
+        self, 
+        X_train: pl.DataFrame, 
+        y_train: pl.DataFrame | pl.Series,
+        X_val: pl.DataFrame | None = None, 
+        y_val: pl.DataFrame | pl.Series | None = None,
+    ) -> "SignalValidator":
+        """Train the validator model.
+        
+        Args:
+            X_train: Training features (Polars DataFrame)
+            y_train: Training labels
+            X_val: Validation features (optional)
+            y_val: Validation labels (optional)
+            
+        Returns:
+            Self for method chaining
+        """
+        raise NotImplementedError("Subclasses must implement fit()")
+
+    def tune(
+        self, 
+        X_train: pl.DataFrame, 
+        y_train: pl.DataFrame | pl.Series,
+        X_val: pl.DataFrame | None = None, 
+        y_val: pl.DataFrame | pl.Series | None = None,
+    ) -> dict[str, Any]:
+        """Tune hyperparameters.
+        
+        Returns:
+            Best parameters found
+        """
+        if not self.tune_enabled:
+            raise ValueError("Tuning is not enabled for this validator")
+        raise NotImplementedError("Subclasses must implement tune()")
+
+    def predict(self, signals: Signals, X: pl.DataFrame) -> Signals:
+        """Predict class labels and return updated Signals.
+        
+        Args:
+            signals: Input signals container
+            X: Features (Polars DataFrame) with (pair, timestamp) + feature columns
+            
+        Returns:
+            New Signals with prediction column added
+        """
+        raise NotImplementedError("Subclasses must implement predict()")
+    
+    def predict_proba(self, signals: Signals, X: pl.DataFrame) -> Signals:
+        """Predict class probabilities and return updated Signals.
+        
+        Args:
+            signals: Input signals container  
+            X: Features (Polars DataFrame)
+            
+        Returns:
+            New Signals with probability columns added
+        """
+        raise NotImplementedError("Subclasses must implement predict_proba()")
+    
+    def validate_signals(
+        self, 
+        signals: Signals, 
+        features: pl.DataFrame,
+        prefix: str = "probability_",
+    ) -> Signals:
+        """Add validation predictions to signals.
+        
+        Convenience method - calls predict_proba internally.
+        
+        Args:
+            signals: Input signals container
+            features: Features DataFrame with (pair, timestamp) + feature columns
+            prefix: Prefix for probability columns
+            
+        Returns:
+            Signals with added validation columns
+        """
+        raise NotImplementedError("Subclasses must implement validate_signals()")
+    
+    def save(self, path: str | Path) -> None:
+        """Save model to file."""
+        raise NotImplementedError("Subclasses must implement save()")
+    
+    @classmethod
+    def load(cls, path: str | Path) -> "SignalValidator":
+        """Load model from file."""
+        raise NotImplementedError("Subclasses must implement load()")