""" utils/features.py Causal, leakage-safe feature engineering (project brief, Task 2). Design summary -------------- 1. Near-constant sensors are dropped (their variance on TRAIN rows is ~0, so they carry no signal and would just add noise / instability). 2. For FD002 (multiple operating conditions) we optionally cluster the three operating settings into "regimes" with KMeans and z-normalize every sensor *within its regime*, using regime statistics computed on TRAIN rows only. For FD001 (a single condition) this step is skipped. 3. For every kept sensor we build a small, trailing (right-aligned, therefore causal) window of engineered features: current value, rolling mean/std/min/max, a rolling slope (local trend), the first difference, and an EWM mean. 4. A handful of sensor ratios and the raw operating settings / cycle number are appended. 5. Everything is finally scaled with a StandardScaler fit on TRAIN rows. The `FeaturePipeline` class mirrors the minimal interface sketched in the brief (`fit`, `transform_engine`) plus a batch `transform` used for training. """ from __future__ import annotations import numpy as np import pandas as pd from sklearn.cluster import KMeans from sklearn.preprocessing import StandardScaler from .data_loading import OP_SETTING_COLS, SENSOR_COLS # A few sensor ratios that are commonly cited as informative for this # benchmark. They are cheap, causal (row-level, no future data), and are # included purely as extra candidate features -- illustrative, not sacred. RATIO_PAIRS = [ ("sensor_11", "sensor_4"), ("sensor_9", "sensor_14"), ("sensor_7", "sensor_12"), ] def _rolling_slope(values: np.ndarray) -> float: """Slope of a simple least-squares line fit through the trailing window.""" n = len(values) if n < 2: return 0.0 x = np.arange(n, dtype=float) x_mean, y_mean = x.mean(), values.mean() denom = ((x - x_mean) ** 2).sum() if denom == 0: return 0.0 return float(((x - x_mean) * (values - y_mean)).sum() / denom) def drop_near_constant_sensors( train_df: pd.DataFrame, threshold: float = 1e-5 ) -> list[str]: """Returns the sensor columns whose variance on TRAIN rows exceeds `threshold`.""" variances = train_df[SENSOR_COLS].var() kept = variances[variances > threshold].index.tolist() return kept class FeaturePipeline: """ Causal feature pipeline. Call `fit` once on the TRAIN split only, then `transform` on train/validation/test splits (and `transform_engine` for single-engine inference, e.g. in the deployed app). """ def __init__( self, window: int = 15, ewm_span: int = 5, condition_aware: bool = False, n_regimes: int = 6, seed: int = 42, ): self.window = window self.ewm_span = ewm_span self.condition_aware = condition_aware self.n_regimes = n_regimes self.seed = seed self.kept_sensors_: list[str] = [] self.regime_model_: KMeans | None = None self.regime_mean_table_: np.ndarray | None = ( None # shape (n_regimes, n_sensors) ) self.regime_std_table_: np.ndarray | None = None self.scaler_: StandardScaler | None = None self.feature_names_: list[str] = [] # ------------------------------------------------------------------ # # Fitting (TRAIN engines only) # ------------------------------------------------------------------ # def fit(self, train_df: pd.DataFrame): self.kept_sensors_ = drop_near_constant_sensors(train_df) if self.condition_aware: self.regime_model_ = KMeans( n_clusters=self.n_regimes, random_state=self.seed, n_init=10 ) self.regime_model_.fit(train_df[OP_SETTING_COLS]) regimes = self.regime_model_.predict(train_df[OP_SETTING_COLS]) tmp = train_df[self.kept_sensors_].copy() tmp["regime"] = regimes n_sensors = len(self.kept_sensors_) mean_table = np.zeros((self.n_regimes, n_sensors)) std_table = np.ones((self.n_regimes, n_sensors)) for regime, g in tmp.groupby("regime"): for j, s in enumerate(self.kept_sensors_): mean, std = g[s].mean(), g[s].std() mean_table[regime, j] = mean std_table[regime, j] = std if std > 1e-8 else 1.0 self.regime_mean_table_ = mean_table self.regime_std_table_ = std_table # Build the raw engineered feature table on TRAIN rows, then fit the scaler. engineered = self._engineer(train_df) self.feature_names_ = [ c for c in engineered.columns if c not in ("engine_id", "cycle") ] self.scaler_ = StandardScaler() self.scaler_.fit(engineered[self.feature_names_]) return self # ------------------------------------------------------------------ # # Internal: causal feature engineering (no scaling yet) # ------------------------------------------------------------------ # def _normalize_sensors(self, df: pd.DataFrame) -> pd.DataFrame: """Row-level regime normalization. Uses only fixed, already-fitted regime stats (a small [n_regimes x n_sensors] lookup table built during `fit`), so this is a fast vectorized array lookup rather than a per-row Python computation.""" out = df[self.kept_sensors_].copy() if self.condition_aware: regimes = self.regime_model_.predict(df[OP_SETTING_COLS]) means = self.regime_mean_table_[regimes] # shape (n_rows, n_sensors) stds = self.regime_std_table_[regimes] out[self.kept_sensors_] = ( out[self.kept_sensors_].to_numpy() - means ) / stds return out def _engineer(self, df: pd.DataFrame) -> pd.DataFrame: df = df.sort_values(["engine_id", "cycle"]).reset_index(drop=True) normed = self._normalize_sensors(df) pieces = {"engine_id": df["engine_id"], "cycle": df["cycle"]} grouped = normed.groupby(df["engine_id"]) for s in self.kept_sensors_: series = normed[s] g = series.groupby(df["engine_id"]) pieces[f"{s}_current"] = series.to_numpy() pieces[f"{s}_roll_mean"] = g.transform( lambda x: x.rolling(self.window, min_periods=1).mean() ) pieces[f"{s}_roll_std"] = g.transform( lambda x: x.rolling(self.window, min_periods=1).std() ).fillna(0.0) pieces[f"{s}_roll_min"] = g.transform( lambda x: x.rolling(self.window, min_periods=1).min() ) pieces[f"{s}_roll_max"] = g.transform( lambda x: x.rolling(self.window, min_periods=1).max() ) pieces[f"{s}_slope"] = g.transform( lambda x: x.rolling(self.window, min_periods=2).apply( _rolling_slope, raw=True ) ).fillna(0.0) pieces[f"{s}_diff"] = g.transform(lambda x: x.diff()).fillna(0.0) pieces[f"{s}_ewm"] = g.transform( lambda x: x.ewm(span=self.ewm_span, adjust=False).mean() ) # Raw operating settings + absolute cycle number (both known at time t, so causal). for c in OP_SETTING_COLS: pieces[c] = df[c].to_numpy() pieces["cycle_number"] = df["cycle"].to_numpy() # Sensor ratios (row-level, only if both sensors survived the near-constant filter). for num, den in RATIO_PAIRS: if num in self.kept_sensors_ and den in self.kept_sensors_: denom = normed[den].replace(0, np.nan) pieces[f"ratio_{num}_{den}"] = ( (normed[num] / denom).fillna(0.0).to_numpy() ) return pd.DataFrame(pieces) # ------------------------------------------------------------------ # # Public transform (batch) # ------------------------------------------------------------------ # def transform(self, df: pd.DataFrame) -> pd.DataFrame: """Returns engine_id, cycle, plus every scaled feature column.""" engineered = self._engineer(df) scaled = self.scaler_.transform(engineered[self.feature_names_]) out = pd.DataFrame(scaled, columns=self.feature_names_, index=engineered.index) out.insert(0, "cycle", engineered["cycle"].to_numpy()) out.insert(0, "engine_id", engineered["engine_id"].to_numpy()) return out def transform_engine( self, engine_history: pd.DataFrame, at_cycle: int | None = None ) -> pd.Series: """ Single-engine interface (used by the deployed app). `engine_history` must contain only rows with cycle <= at_cycle (or all rows if at_cycle is None) -- this makes the causality constraint explicit at the call site instead of hidden inside the feature code. """ history = engine_history.sort_values("cycle") if at_cycle is not None: history = history[history["cycle"] <= at_cycle] feats = self.transform(history) return feats.iloc[-1] def current_cycle_feature_names(self) -> list[str]: """Feature names that only use the current row (no window stats) -- used for the 'current-cycle baseline' comparison required by the brief.""" current = [f"{s}_current" for s in self.kept_sensors_] current += OP_SETTING_COLS + ["cycle_number"] return [c for c in current if c in self.feature_names_]