baxter-ts 0.1.1__py3-none-any.whl

baxter_ts/__init__.py

@@ -0,0 +1,19 @@
+"""
+baxter-ts: AutoML time series library with BAX behavioural explanation.
+
+Usage:
+    from baxter_ts import BAXModel
+
+    model = BAXModel()
+    model.fit(df, target_col="sales", date_col="date")
+    model.predict(steps=30)
+    model.explain()
+    model.anomalies()
+    model.visualize()
+    model.report("my_report")
+"""
+
+from baxter_ts.core import BAXModel
+
+__version__ = "0.1.1"
+__all__ = ["BAXModel"]

baxter_ts/anomaly/__init__.py

@@ -0,0 +1,3 @@
+from baxter_ts.anomaly.detector import AnomalyDetector
+
+__all__ = ["AnomalyDetector"]

baxter_ts/anomaly/detector.py

@@ -0,0 +1,118 @@
+"""
+Anomaly detection on model residuals.
+Running on residuals (actual - predicted) catches anomalies the model
+didn't predict — far more useful than flagging obvious raw-value spikes.
+Three methods: IsolationForest, Z-score on residuals, IQR on residuals.
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.ensemble import IsolationForest
+from typing import Optional
+
+
+class AnomalyDetector:
+    SEVERITY_LABELS = {0: "normal", 1: "suspicious", 2: "anomaly"}
+
+    def __init__(
+        self,
+        method: str = "ensemble",
+        contamination: float = 0.05,
+        z_threshold: float = 3.0,
+        window: int = 30,
+    ):
+        self.method = method
+        self.contamination = contamination
+        self.z_threshold = z_threshold
+        self.window = window
+        self._iso: Optional[IsolationForest] = None
+        self.audit: dict = {}
+
+    def fit_predict(
+        self,
+        y_true: pd.Series,
+        y_pred: np.ndarray,
+        X: Optional[pd.DataFrame] = None,
+    ) -> pd.DataFrame:
+        """
+        Returns a DataFrame with columns:
+            actual, predicted, residual, anomaly_score,
+            anomaly_flag (0/1), severity, anomaly_label
+        """
+        residuals = y_true.values - y_pred
+        index = y_true.index
+
+        result = pd.DataFrame(
+            {
+                "actual": y_true.values,
+                "predicted": y_pred,
+                "residual": residuals,
+            },
+            index=index,
+        )
+
+        # Method 1: Isolation Forest on residuals
+        iso_scores = self._iso_scores(residuals)
+
+        # Method 2: Rolling Z-score on residuals
+        zscore_flags = self._rolling_zscore_flags(residuals)
+
+        # Method 3: IQR flags
+        iqr_flags = self._iqr_flags(residuals)
+
+        if self.method == "ensemble":
+            # Vote: flag if 2+ methods agree
+            votes = iso_scores + zscore_flags.astype(int) + iqr_flags.astype(int)
+            result["anomaly_score"] = iso_scores.astype(float) + np.abs(residuals) / (np.std(residuals) + 1e-9)
+            result["anomaly_flag"] = (votes >= 2).astype(int)
+        elif self.method == "isolation_forest":
+            result["anomaly_score"] = iso_scores.astype(float)
+            result["anomaly_flag"] = iso_scores
+        elif self.method == "zscore":
+            result["anomaly_score"] = np.abs(residuals) / (np.std(residuals) + 1e-9)
+            result["anomaly_flag"] = zscore_flags.astype(int)
+        else:
+            result["anomaly_score"] = np.abs(residuals) / (np.std(residuals) + 1e-9)
+            result["anomaly_flag"] = iqr_flags.astype(int)
+
+        # Severity: 0=normal, 1=suspicious (score > 1.5σ), 2=anomaly (flagged)
+        sigma = np.std(residuals) + 1e-9
+        result["severity"] = 0
+        result.loc[np.abs(residuals) > 1.5 * sigma, "severity"] = 1
+        result.loc[result["anomaly_flag"] == 1, "severity"] = 2
+        result["severity_label"] = result["severity"].map(self.SEVERITY_LABELS)
+
+        n_anomalies = int(result["anomaly_flag"].sum())
+        self.audit = {
+            "method": self.method,
+            "total_points": len(result),
+            "anomalies_found": n_anomalies,
+            "anomaly_pct": round(n_anomalies / len(result) * 100, 2),
+            "suspicious_count": int((result["severity"] == 1).sum()),
+            "residual_mean": round(float(np.mean(residuals)), 4),
+            "residual_std": round(float(np.std(residuals)), 4),
+        }
+        return result
+
+    def _iso_scores(self, residuals: np.ndarray) -> np.ndarray:
+        try:
+            iso = IsolationForest(
+                contamination=self.contamination, random_state=42, n_jobs=-1
+            )
+            preds = iso.fit_predict(residuals.reshape(-1, 1))
+            return (preds == -1).astype(int)
+        except Exception:
+            return np.zeros(len(residuals), dtype=int)
+
+    def _rolling_zscore_flags(self, residuals: np.ndarray) -> np.ndarray:
+        s = pd.Series(residuals)
+        roll_mean = s.rolling(self.window, min_periods=3).mean().fillna(s.mean())
+        roll_std  = s.rolling(self.window, min_periods=3).std().fillna(s.std())
+        z = (s - roll_mean) / (roll_std + 1e-9)
+        return (z.abs() > self.z_threshold).values
+
+    def _iqr_flags(self, residuals: np.ndarray) -> np.ndarray:
+        q1, q3 = np.percentile(residuals, 25), np.percentile(residuals, 75)
+        iqr = q3 - q1
+        lower, upper = q1 - 2.5 * iqr, q3 + 2.5 * iqr
+        return (residuals < lower) | (residuals > upper)

baxter_ts/bax/__init__.py

@@ -0,0 +1,4 @@
+from baxter_ts.bax.explainer import BAXExplainer
+from baxter_ts.bax.narrator import BAXNarrator
+
+__all__ = ["BAXExplainer", "BAXNarrator"]

baxter_ts/bax/explainer.py

@@ -0,0 +1,58 @@
+"""
+BAX Explainer: computes SHAP values on the winning model.
+Works with tree-based models (RF, XGB, CatBoost) via TreeExplainer.
+"""
+
+import warnings
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Optional
+
+
+class BAXExplainer:
+    def __init__(self):
+        self._explainer = None
+        self.shap_values_: Optional[np.ndarray] = None
+        self.feature_importance_: Optional[pd.Series] = None
+        self.top_features_: List[str] = []
+        self.audit: dict = {}
+
+    def fit(self, model, X_sample: pd.DataFrame) -> "BAXExplainer":
+        """Fit SHAP TreeExplainer on a sample of training data."""
+        try:
+            import shap
+            sample = X_sample.dropna()
+            if len(sample) > 500:
+                sample = sample.sample(500, random_state=42)
+
+            raw_model = model._model
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                self._explainer = shap.TreeExplainer(raw_model)
+                self.shap_values_ = self._explainer.shap_values(sample)
+
+            mean_abs = np.abs(self.shap_values_).mean(axis=0)
+            self.feature_importance_ = pd.Series(
+                mean_abs, index=sample.columns
+            ).sort_values(ascending=False)
+            self.top_features_ = self.feature_importance_.head(10).index.tolist()
+            self.audit["shap_computed"] = True
+            self.audit["top_features"] = self.top_features_
+        except Exception as e:
+            self.audit["shap_computed"] = False
+            self.audit["shap_error"] = str(e)
+        return self
+
+    def explain_prediction(
+        self, model, X_row: pd.DataFrame
+    ) -> Dict[str, float]:
+        """Returns per-feature SHAP contribution for a single row."""
+        if self._explainer is None:
+            return {}
+        try:
+            import shap
+            row = X_row.dropna(axis=1).fillna(0)
+            vals = self._explainer.shap_values(row)
+            return dict(zip(row.columns, vals[0]))
+        except Exception:
+            return {}

baxter_ts/bax/narrator.py

@@ -0,0 +1,128 @@
+"""
+BAX Narrator: translates SHAP feature importances into plain-English
+behavioural explanations. This is the core differentiator of baxter-ts.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Optional
+
+
+class BAXNarrator:
+    FEATURE_PHRASES = {
+        "lag_":         "recent past values (lag-{n})",
+        "roll_mean_":   "rolling average over {n} periods",
+        "roll_std_":    "recent volatility ({n}-period std dev)",
+        "seasonal_":    "seasonal pattern",
+        "trend_":       "underlying trend",
+        "ewm_":         "exponentially weighted recent momentum",
+        "dayofweek":    "day-of-week effect",
+        "month":        "month-of-year effect",
+        "hour":         "hour-of-day effect",
+        "is_weekend":   "weekend vs weekday pattern",
+        "fourier":      "cyclical seasonality (Fourier term)",
+        "sin_":         "cyclical seasonality (sine component)",
+        "cos_":         "cyclical seasonality (cosine component)",
+        "time_idx":     "long-run time trend",
+        "pct_change":   "recent rate of change",
+        "residual_":    "irregular/noise component",
+        "holiday":      "holiday calendar effect",
+        "quarter":      "quarterly pattern",
+    }
+
+    def generate(
+        self,
+        feature_importance: Optional[pd.Series],
+        model_name: str,
+        target_col: str,
+        test_scores: dict,
+        preprocessing_audit: dict,
+    ) -> str:
+        if feature_importance is None or len(feature_importance) == 0:
+            return self._fallback_narrative(model_name, target_col, test_scores)
+
+        top = feature_importance.head(10)
+        total_importance = top.sum()
+
+        lines = []
+        lines.append(
+            f"The {model_name} model was selected as the best performer for "
+            f"predicting '{target_col}', achieving a test MAE of "
+            f"{test_scores.get('mae', 'N/A')} and RMSE of "
+            f"{test_scores.get('rmse', 'N/A')}."
+        )
+        lines.append("")
+        lines.append("Key behavioural drivers (BAX analysis):")
+        lines.append("")
+
+        cumulative = 0.0
+        for rank, (feat, importance) in enumerate(top.items(), start=1):
+            pct = round(importance / (total_importance + 1e-9) * 100, 1)
+            cumulative += pct
+            phrase = self._describe_feature(feat)
+            direction = ""
+            lines.append(
+                f"  {rank}. {phrase} accounts for {pct}% of prediction influence{direction}."
+            )
+            if cumulative >= 80:
+                break
+
+        lines.append("")
+        lines.append(self._preprocessing_summary(preprocessing_audit))
+        lines.append("")
+        lines.append(
+            "Note: Contributions are computed using SHAP (SHapley Additive exPlanations), "
+            "which fairly attributes prediction influence across all features while "
+            "respecting feature interactions."
+        )
+        return "\n".join(lines)
+
+    def _describe_feature(self, feature_name: str) -> str:
+        for prefix, template in self.FEATURE_PHRASES.items():
+            if prefix in feature_name:
+                n = ""
+                parts = feature_name.split("_")
+                for part in parts:
+                    if part.isdigit():
+                        n = part
+                        break
+                return template.replace("{n}", n) if n else template.replace(" ({n})", "").replace("{n}", "")
+        return f"feature '{feature_name}'"
+
+    def _preprocessing_summary(self, audit: dict) -> str:
+        parts = []
+        v = audit.get("validator", {})
+        i = audit.get("imputer", {})
+        o = audit.get("outlier", {})
+        t = audit.get("transformer", {})
+        sc = audit.get("scaler", {})
+
+        if v.get("inferred_frequency"):
+            parts.append(f"Data frequency detected as '{v['inferred_frequency']}'")
+        if i.get("missing_pct", 0) > 0:
+            parts.append(
+                f"{i['missing_pct']}% missing values filled using '{i.get('strategy_used', 'auto')}'"
+            )
+        if o.get("outliers_found", 0) > 0:
+            parts.append(
+                f"{o['outliers_found']} outliers ({o.get('outlier_pct', '')}%) "
+                f"treated via {o.get('outlier_treatment', 'cap')}"
+            )
+        if t.get("diffs_applied", 0) > 0:
+            parts.append(f"{t['diffs_applied']}-order differencing applied for stationarity")
+        if t.get("log_transform_applied"):
+            parts.append("log(1+x) transform applied to reduce skewness")
+        if sc.get("scaler_used"):
+            parts.append(f"{sc['scaler_used']} scaling applied")
+
+        if parts:
+            return "Preprocessing applied: " + "; ".join(parts) + "."
+        return ""
+
+    def _fallback_narrative(self, model_name: str, target_col: str, test_scores: dict) -> str:
+        return (
+            f"{model_name} was selected to forecast '{target_col}'. "
+            f"Test MAE: {test_scores.get('mae', 'N/A')}, "
+            f"RMSE: {test_scores.get('rmse', 'N/A')}. "
+            "SHAP explanation unavailable for this model configuration."
+        )