churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/temporal/timestamp_manager.py

@@ -0,0 +1,255 @@
+"""Timestamp management for leakage-safe ML pipelines.
+
+This module provides the core timestamp handling infrastructure for ensuring
+point-in-time (PIT) correctness in ML training pipelines. It supports multiple
+strategies for managing timestamps depending on data availability.
+
+Key concepts:
+    - feature_timestamp: When features were observed
+    - label_timestamp: When the label became known
+    - label_available_flag: Whether the label can be used for training
+
+Example:
+    >>> from customer_retention.stages.temporal import TimestampManager, TimestampConfig, TimestampStrategy
+    >>> config = TimestampConfig(
+    ...     strategy=TimestampStrategy.PRODUCTION,
+    ...     feature_timestamp_column="last_activity_date",
+    ...     label_timestamp_column="churn_date"
+    ... )
+    >>> manager = TimestampManager(config)
+    >>> df_with_timestamps = manager.ensure_timestamps(df)
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Optional
+
+import numpy as np
+import pandas as pd
+
+
+class TimestampStrategy(Enum):
+    """Strategy for handling timestamps in the ML pipeline.
+
+    Attributes:
+        PRODUCTION: Use explicit timestamp columns from the data
+        SYNTHETIC_RANDOM: Generate random timestamps within a date range
+        SYNTHETIC_INDEX: Generate timestamps based on row index
+        SYNTHETIC_FIXED: Use a fixed timestamp for all rows
+        DERIVED: Derive timestamps from other columns (e.g., tenure)
+    """
+    PRODUCTION = "production"
+    SYNTHETIC_RANDOM = "synthetic_random"
+    SYNTHETIC_INDEX = "synthetic_index"
+    SYNTHETIC_FIXED = "synthetic_fixed"
+    DERIVED = "derived"
+
+
+@dataclass
+class TimestampConfig:
+    """Configuration for timestamp handling strategy.
+
+    Attributes:
+        strategy: The timestamp handling strategy to use
+        feature_timestamp_column: Column name for feature timestamps (production strategy)
+        label_timestamp_column: Column name for label timestamps (production strategy)
+        observation_window_days: Days between feature observation and label availability
+        synthetic_base_date: Base date for synthetic timestamp generation
+        synthetic_range_days: Range of days for synthetic random timestamps
+        derive_label_from_feature: If True, derive label_timestamp from feature_timestamp
+        derivation_config: Configuration for derived timestamps (formula, source columns)
+    """
+
+    strategy: TimestampStrategy
+    feature_timestamp_column: Optional[str] = None
+    label_timestamp_column: Optional[str] = None
+    observation_window_days: int = 90
+    synthetic_base_date: str = "2024-01-01"
+    synthetic_range_days: int = 365
+    derive_label_from_feature: bool = False
+    derivation_config: Optional[dict[str, Any]] = None
+
+
+class TimestampManager:
+    """Manages timestamp columns to ensure point-in-time correctness.
+
+    The TimestampManager ensures that all data has proper feature_timestamp,
+    label_timestamp, and label_available_flag columns, regardless of whether
+    the source data has explicit timestamps or needs synthetic ones.
+
+    Example:
+        >>> config = TimestampConfig(strategy=TimestampStrategy.SYNTHETIC_FIXED)
+        >>> manager = TimestampManager(config)
+        >>> df = manager.ensure_timestamps(df)
+        >>> assert "feature_timestamp" in df.columns
+        >>> assert "label_timestamp" in df.columns
+        >>> assert "label_available_flag" in df.columns
+    """
+
+    def __init__(self, config: TimestampConfig):
+        """Initialize the TimestampManager.
+
+        Args:
+            config: Configuration specifying the timestamp strategy
+        """
+        self.config = config
+
+    def ensure_timestamps(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Add or validate timestamp columns based on the configured strategy.
+
+        This is the main entry point for timestamp handling. It adds feature_timestamp,
+        label_timestamp, and label_available_flag columns to the DataFrame.
+
+        Args:
+            df: Input DataFrame
+
+        Returns:
+            DataFrame with timestamp columns added
+
+        Raises:
+            ValueError: If production strategy is used but required columns are missing
+        """
+        if self.config.strategy == TimestampStrategy.PRODUCTION:
+            return self._validate_production_timestamps(df)
+        elif self.config.strategy == TimestampStrategy.DERIVED:
+            return self._derive_timestamps(df)
+        return self._add_synthetic_timestamps(df)
+
+    def _validate_production_timestamps(self, df: pd.DataFrame) -> pd.DataFrame:
+        required = [self.config.feature_timestamp_column, self.config.label_timestamp_column]
+        missing = [col for col in required if col and col not in df.columns]
+        if missing:
+            raise ValueError(f"Missing required timestamp columns: {missing}")
+
+        df = df.copy()
+        if self.config.feature_timestamp_column:
+            df["feature_timestamp"] = self._parse_datetime_column(
+                df[self.config.feature_timestamp_column], self.config.feature_timestamp_column
+            )
+        if self.config.label_timestamp_column:
+            df["label_timestamp"] = self._parse_datetime_column(
+                df[self.config.label_timestamp_column], self.config.label_timestamp_column
+            )
+        elif self.config.derive_label_from_feature:
+            window = timedelta(days=self.config.observation_window_days)
+            df["label_timestamp"] = df["feature_timestamp"] + window
+        now = datetime.now()
+        has_event = df["label_timestamp"].notna() & (df["label_timestamp"] <= now)
+        observation_complete = (
+            df["feature_timestamp"].notna()
+            & (df["feature_timestamp"] + pd.Timedelta(days=self.config.observation_window_days) <= now)
+        )
+        df["label_available_flag"] = has_event | observation_complete
+        return df
+
+    def _parse_datetime_column(self, series: pd.Series, col_name: str) -> pd.Series:
+        if pd.api.types.is_datetime64_any_dtype(series):
+            return series
+        parsed = pd.to_datetime(series, format="mixed", errors="coerce")
+        invalid_count = parsed.isna().sum() - series.isna().sum()
+        if invalid_count > 0:
+            import warnings
+            warnings.warn(f"Column '{col_name}': {invalid_count} invalid dates coerced to NaT")
+        return parsed
+
+    def _derive_timestamps(self, df: pd.DataFrame) -> pd.DataFrame:
+        if not self.config.derivation_config:
+            raise ValueError("derivation_config required for DERIVED strategy")
+
+        df = df.copy()
+        config = self.config.derivation_config
+
+        if "feature_derivation" in config:
+            df = self._apply_derivation(df, config["feature_derivation"], "feature_timestamp")
+        if "label_derivation" in config:
+            df = self._apply_derivation(df, config["label_derivation"], "label_timestamp")
+        elif "feature_timestamp" in df.columns:
+            window = timedelta(days=self.config.observation_window_days)
+            df["label_timestamp"] = df["feature_timestamp"] + window
+
+        df["label_available_flag"] = True
+        return df
+
+    def _apply_derivation(self, df: pd.DataFrame, derivation: dict, target_col: str) -> pd.DataFrame:
+        sources = derivation.get("sources", [])
+        formula = derivation.get("formula", "")
+
+        if not sources or not formula:
+            return df
+
+        if "tenure" in formula.lower() and len(sources) >= 1:
+            tenure_col = sources[0]
+            if tenure_col in df.columns:
+                reference_date = datetime.now()
+                df[target_col] = reference_date - pd.to_timedelta(df[tenure_col] * 30, unit="D")
+        return df
+
+    def _add_synthetic_timestamps(self, df: pd.DataFrame) -> pd.DataFrame:
+        df = df.copy()
+        base = pd.to_datetime(self.config.synthetic_base_date)
+        window = timedelta(days=self.config.observation_window_days)
+
+        if self.config.strategy == TimestampStrategy.SYNTHETIC_FIXED:
+            df["feature_timestamp"] = base
+            df["label_timestamp"] = base + window
+        elif self.config.strategy == TimestampStrategy.SYNTHETIC_INDEX:
+            df["feature_timestamp"] = base + pd.to_timedelta(range(len(df)), unit="D")
+            df["label_timestamp"] = df["feature_timestamp"] + window
+        elif self.config.strategy == TimestampStrategy.SYNTHETIC_RANDOM:
+            np.random.seed(42)
+            days = np.random.randint(0, self.config.synthetic_range_days, len(df))
+            df["feature_timestamp"] = base + pd.to_timedelta(days, unit="D")
+            df["label_timestamp"] = df["feature_timestamp"] + window
+
+        df["label_available_flag"] = True
+        return df
+
+    def validate_point_in_time(self, df: pd.DataFrame) -> bool:
+        """Validate that timestamps maintain point-in-time correctness.
+
+        Ensures that feature_timestamp is always <= label_timestamp for all rows,
+        which is required to prevent data leakage during training.
+
+        Args:
+            df: DataFrame with timestamp columns
+
+        Returns:
+            True if validation passes
+
+        Raises:
+            ValueError: If timestamp columns are missing or violations are found
+        """
+        if "feature_timestamp" not in df.columns or "label_timestamp" not in df.columns:
+            raise ValueError("Missing timestamp columns for point-in-time validation")
+
+        violations = df[df["feature_timestamp"] > df["label_timestamp"]]
+        if len(violations) > 0:
+            raise ValueError(
+                f"Point-in-time violation: {len(violations)} rows have "
+                f"feature_timestamp > label_timestamp"
+            )
+        return True
+
+    def get_timestamp_summary(self, df: pd.DataFrame) -> dict[str, Any]:
+        """Generate a summary of timestamp column statistics.
+
+        Args:
+            df: DataFrame with timestamp columns
+
+        Returns:
+            Dictionary containing timestamp statistics including min/max dates,
+            null percentages, and label availability rates
+        """
+        summary = {"strategy": self.config.strategy.value}
+
+        for col in ["feature_timestamp", "label_timestamp"]:
+            if col in df.columns:
+                summary[f"{col}_min"] = df[col].min()
+                summary[f"{col}_max"] = df[col].max()
+                summary[f"{col}_null_pct"] = df[col].isna().mean()
+
+        if "label_available_flag" in df.columns:
+            summary["label_available_pct"] = df["label_available_flag"].mean()
+
+        return summary

customer_retention/stages/transformation/__init__.py

@@ -0,0 +1,13 @@
+from .binary_handler import BinaryHandler, BinaryTransformResult
+from .categorical_encoder import CategoricalEncoder, CategoricalEncodeResult, EncodingStrategy
+from .datetime_transformer import DatetimeTransformer, DatetimeTransformResult
+from .numeric_transformer import NumericTransformer, NumericTransformResult, PowerTransform, ScalingStrategy
+from .pipeline import PipelineResult, TransformationManifest, TransformationPipeline
+
+__all__ = [
+    "NumericTransformer", "ScalingStrategy", "PowerTransform", "NumericTransformResult",
+    "CategoricalEncoder", "EncodingStrategy", "CategoricalEncodeResult",
+    "DatetimeTransformer", "DatetimeTransformResult",
+    "BinaryHandler", "BinaryTransformResult",
+    "TransformationPipeline", "TransformationManifest", "PipelineResult"
+]

customer_retention/stages/transformation/binary_handler.py

@@ -0,0 +1,85 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import numpy as np
+
+from customer_retention.core.compat import Series
+
+
+@dataclass
+class BinaryTransformResult:
+    series: Series
+    mapping: dict = field(default_factory=dict)
+    original_values: list = field(default_factory=list)
+    positive_class: Any = None
+
+
+class BinaryHandler:
+    TRUE_VALUES = {1, 1.0, True, "1", "yes", "Yes", "YES", "true", "True", "TRUE", "y", "Y"}
+    FALSE_VALUES = {0, 0.0, False, "0", "no", "No", "NO", "false", "False", "FALSE", "n", "N"}
+
+    def __init__(self, positive_class: Optional[Any] = None):
+        self.positive_class = positive_class
+        self._mapping: Optional[dict] = None
+        self._original_values: Optional[list] = None
+        self._positive: Any = None
+        self._is_fitted = False
+
+    def fit(self, series: Series) -> "BinaryHandler":
+        clean = series.dropna()
+        unique_vals = clean.unique().tolist()
+        self._original_values = unique_vals
+
+        if self.positive_class is not None:
+            self._positive = self.positive_class
+            self._mapping = {v: 1 if v == self.positive_class else 0 for v in unique_vals}
+        else:
+            self._mapping, self._positive = self._infer_mapping(unique_vals)
+
+        self._is_fitted = True
+        return self
+
+    def transform(self, series: Series) -> BinaryTransformResult:
+        if not self._is_fitted:
+            raise ValueError("Handler not fitted. Call fit() or fit_transform() first.")
+        return self._apply_transform(series)
+
+    def fit_transform(self, series: Series) -> BinaryTransformResult:
+        self.fit(series)
+        return self._apply_transform(series)
+
+    def _infer_mapping(self, unique_vals: list) -> tuple[dict, Any]:
+        if len(unique_vals) == 1:
+            val = unique_vals[0]
+            if val in self.TRUE_VALUES or str(val).lower() in {"yes", "y", "true", "1"}:
+                return {val: 1}, val
+            return {val: 0}, None
+
+        mapping = {}
+        positive = None
+
+        for val in unique_vals:
+            val_lower = str(val).lower() if isinstance(val, str) else val
+            if val in self.TRUE_VALUES or val_lower in {"yes", "y", "true", "1", "active"}:
+                mapping[val] = 1
+                positive = val
+            elif val in self.FALSE_VALUES or val_lower in {"no", "n", "false", "0", "inactive"}:
+                mapping[val] = 0
+
+        if len(mapping) == len(unique_vals) and positive is not None:
+            return mapping, positive
+
+        if len(unique_vals) == 2:
+            sorted_vals = sorted(unique_vals, key=lambda x: (str(x).lower(), x))
+            return {sorted_vals[0]: 0, sorted_vals[1]: 1}, sorted_vals[1]
+
+        return {v: i for i, v in enumerate(unique_vals)}, unique_vals[-1] if unique_vals else None
+
+    def _apply_transform(self, series: Series) -> BinaryTransformResult:
+        result = series.map(self._mapping)
+        result = result.where(series.notna(), np.nan)
+
+        return BinaryTransformResult(
+            series=result, mapping=self._mapping or {},
+            original_values=self._original_values or [], positive_class=self._positive
+        )

customer_retention/stages/transformation/categorical_encoder.py

@@ -0,0 +1,245 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+import numpy as np
+
+from customer_retention.core.compat import DataFrame, Series, pd
+
+
+class EncodingStrategy(str, Enum):
+    ONE_HOT = "one_hot"
+    LABEL = "label"
+    ORDINAL = "ordinal"
+    CYCLICAL = "cyclical"
+    TARGET = "target"
+    FREQUENCY = "frequency"
+    BINARY = "binary"
+    HASH = "hash"
+
+
+@dataclass
+class CategoricalEncodeResult:
+    series: Optional[Series] = None
+    df: Optional[DataFrame] = None
+    strategy: EncodingStrategy = EncodingStrategy.LABEL
+    columns_created: list = field(default_factory=list)
+    mapping: dict = field(default_factory=dict)
+    dropped_categories: list = field(default_factory=list)
+
+
+class CategoricalEncoder:
+    def __init__(
+        self,
+        strategy: EncodingStrategy = EncodingStrategy.LABEL,
+        drop_first: bool = True,
+        handle_unknown: str = "error",
+        categories: Optional[list] = None,
+        period: Optional[int] = None,
+        smoothing: float = 1.0,
+        min_frequency: Optional[int] = None
+    ):
+        self.strategy = strategy
+        self.drop_first = drop_first
+        self.handle_unknown = handle_unknown
+        self.categories = categories
+        self.period = period
+        self.smoothing = smoothing
+        self.min_frequency = min_frequency
+        self._mapping: Optional[dict] = None
+        self._categories: Optional[list] = None
+        self._target_means: Optional[dict] = None
+        self._global_mean: Optional[float] = None
+        self._frequencies: Optional[dict] = None
+        self._cyclical_mapping: Optional[dict] = None
+        self._is_fitted = False
+
+    def fit(self, series: Series, target: Optional[Series] = None) -> "CategoricalEncoder":
+        clean = series.dropna()
+
+        if self.strategy == EncodingStrategy.ONE_HOT:
+            self._fit_one_hot(clean)
+        elif self.strategy == EncodingStrategy.LABEL:
+            self._fit_label(clean)
+        elif self.strategy == EncodingStrategy.ORDINAL:
+            self._fit_ordinal(clean)
+        elif self.strategy == EncodingStrategy.CYCLICAL:
+            self._fit_cyclical(clean)
+        elif self.strategy == EncodingStrategy.FREQUENCY:
+            self._fit_frequency(clean)
+        elif self.strategy == EncodingStrategy.TARGET:
+            self._fit_target(clean, target)
+
+        self._is_fitted = True
+        return self
+
+    def transform(self, series: Series, target: Optional[Series] = None) -> CategoricalEncodeResult:
+        if not self._is_fitted:
+            raise ValueError("Encoder not fitted. Call fit() or fit_transform() first.")
+        return self._apply_encoding(series, target)
+
+    def fit_transform(self, series: Series, target: Optional[Series] = None) -> CategoricalEncodeResult:
+        self.fit(series, target)
+        return self._apply_encoding(series, target)
+
+    def _fit_one_hot(self, clean: Series):
+        categories = clean.unique().tolist()
+        if self.min_frequency is not None:
+            value_counts = clean.value_counts()
+            categories = [c for c in categories if value_counts.get(c, 0) >= self.min_frequency]
+        self._categories = sorted(categories)
+        self._mapping = {cat: i for i, cat in enumerate(self._categories)}
+
+    def _fit_label(self, clean: Series):
+        categories = sorted(clean.unique().tolist())
+        self._mapping = {cat: i for i, cat in enumerate(categories)}
+
+    def _fit_ordinal(self, clean: Series):
+        if self.categories is None:
+            raise ValueError("Ordinal encoding requires categories parameter")
+        self._mapping = {cat: i for i, cat in enumerate(self.categories)}
+
+    def _fit_cyclical(self, clean: Series):
+        if self.period is None:
+            raise ValueError("Cyclical encoding requires period parameter")
+        # Check if values are strings and need mapping to indices
+        if clean.dtype == object:
+            unique_values = sorted(clean.unique().tolist())
+            # Auto-detect day of week names
+            day_names = {
+                'monday': 0, 'tuesday': 1, 'wednesday': 2, 'thursday': 3,
+                'friday': 4, 'saturday': 5, 'sunday': 6,
+                'mon': 0, 'tue': 1, 'wed': 2, 'thu': 3, 'fri': 4, 'sat': 5, 'sun': 6
+            }
+            month_names = {
+                'january': 0, 'february': 1, 'march': 2, 'april': 3, 'may': 4, 'june': 5,
+                'july': 6, 'august': 7, 'september': 8, 'october': 9, 'november': 10, 'december': 11,
+                'jan': 0, 'feb': 1, 'mar': 2, 'apr': 3, 'jun': 5, 'jul': 6, 'aug': 7,
+                'sep': 8, 'oct': 9, 'nov': 10, 'dec': 11
+            }
+            # Try to auto-detect mapping from common patterns
+            sample_lower = [str(v).lower() for v in unique_values]
+            if all(s in day_names for s in sample_lower):
+                self._cyclical_mapping = {v: day_names[str(v).lower()] for v in unique_values}
+            elif all(s in month_names for s in sample_lower):
+                self._cyclical_mapping = {v: month_names[str(v).lower()] for v in unique_values}
+            else:
+                # Generic mapping: assign indices based on order
+                self._cyclical_mapping = {v: i for i, v in enumerate(unique_values)}
+        else:
+            self._cyclical_mapping = None
+
+    def _fit_frequency(self, clean: Series):
+        total = len(clean)
+        value_counts = clean.value_counts()
+        self._frequencies = {cat: count / total for cat, count in value_counts.items()}
+
+    def _fit_target(self, clean: Series, target: Optional[Series]):
+        if target is None:
+            raise ValueError("Target encoding requires target parameter")
+
+        self._global_mean = target.mean()
+        self._target_means = {}
+
+        for cat in clean.unique():
+            mask = clean == cat
+            cat_target = target[mask]
+            n = len(cat_target)
+            cat_target.mean()
+
+            smoothed = (cat_target.sum() + self.smoothing * self._global_mean) / (n + self.smoothing)
+            self._target_means[cat] = smoothed
+
+    def _apply_encoding(self, series: Series, target: Optional[Series] = None) -> CategoricalEncodeResult:
+        if self.strategy == EncodingStrategy.ONE_HOT:
+            return self._encode_one_hot(series)
+        elif self.strategy == EncodingStrategy.LABEL:
+            return self._encode_label(series)
+        elif self.strategy == EncodingStrategy.ORDINAL:
+            return self._encode_ordinal(series)
+        elif self.strategy == EncodingStrategy.CYCLICAL:
+            return self._encode_cyclical(series)
+        elif self.strategy == EncodingStrategy.FREQUENCY:
+            return self._encode_frequency(series)
+        elif self.strategy == EncodingStrategy.TARGET:
+            return self._encode_target(series)
+
+        return CategoricalEncodeResult(series=series, strategy=self.strategy)
+
+    def _encode_one_hot(self, series: Series) -> CategoricalEncodeResult:
+        categories = self._categories if self._categories else sorted(series.dropna().unique().tolist())
+        if self.drop_first and len(categories) > 0:
+            categories = categories[1:]
+
+        cols = {}
+        col_names = []
+        for cat in categories:
+            col_name = f"{series.name or 'col'}_{cat}"
+            cols[col_name] = (series == cat).astype(int)
+            col_names.append(col_name)
+
+        if self.handle_unknown == "ignore":
+            for col in cols:
+                known_cats = set(self._categories) if self._categories else set()
+                unknown_mask = ~series.isin(known_cats) & series.notna()
+                cols[col] = cols[col].where(~unknown_mask, 0)
+
+        df = DataFrame(cols)
+
+        return CategoricalEncodeResult(
+            df=df, strategy=self.strategy,
+            columns_created=col_names, mapping=self._mapping or {}
+        )
+
+    def _encode_label(self, series: Series) -> CategoricalEncodeResult:
+        result = series.map(self._mapping)
+        return CategoricalEncodeResult(
+            series=result, strategy=self.strategy, mapping=self._mapping or {}
+        )
+
+    def _encode_ordinal(self, series: Series) -> CategoricalEncodeResult:
+        unknown = series[series.notna() & ~series.isin(self._mapping.keys())]
+        if len(unknown) > 0 and self.handle_unknown == "error":
+            raise ValueError(f"Found unknown categories: {unknown.unique().tolist()}")
+
+        result = series.map(self._mapping)
+        return CategoricalEncodeResult(
+            series=result, strategy=self.strategy, mapping=self._mapping or {}
+        )
+
+    def _encode_cyclical(self, series: Series) -> CategoricalEncodeResult:
+        # Map strings to numeric indices if mapping exists
+        if hasattr(self, '_cyclical_mapping') and self._cyclical_mapping is not None:
+            numeric = series.map(self._cyclical_mapping)
+        else:
+            numeric = pd.to_numeric(series, errors='coerce')
+
+        sin_vals = np.sin(2 * np.pi * numeric / self.period)
+        cos_vals = np.cos(2 * np.pi * numeric / self.period)
+
+        col_name = series.name or "col"
+        sin_col = f"{col_name}_sin"
+        cos_col = f"{col_name}_cos"
+
+        df = DataFrame({sin_col: sin_vals, cos_col: cos_vals})
+
+        return CategoricalEncodeResult(
+            df=df, strategy=self.strategy, columns_created=[sin_col, cos_col],
+            mapping=self._cyclical_mapping if hasattr(self, '_cyclical_mapping') else {}
+        )
+
+    def _encode_frequency(self, series: Series) -> CategoricalEncodeResult:
+        result = series.map(self._frequencies)
+        return CategoricalEncodeResult(
+            series=result, strategy=self.strategy, mapping=self._frequencies or {}
+        )
+
+    def _encode_target(self, series: Series) -> CategoricalEncodeResult:
+        result = series.map(self._target_means)
+        result.isna() & series.notna()
+        result = result.fillna(self._global_mean)
+        result = result.where(series.notna(), np.nan)
+
+        return CategoricalEncodeResult(
+            series=result, strategy=self.strategy, mapping=self._target_means or {}
+        )