telemetry-anomdet 0.1.0__py3-none-any.whl

telemetry_anomdet/models/ensemble.py

@@ -0,0 +1,273 @@
+# src/telemetry_anomdet/models/ensemble.py
+
+"""
+Ensemble combinator for anomaly detectors.
+
+This module defines an `AnomalyEnsemble` that can wrap multiple
+BaseDetector compatible detectors and combine their scores into a
+single ensemble score and anomaly decision.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+
+from .base import BaseDetector
+
+
+class AnomalyEnsemble(BaseDetector):
+    """
+    Stacking ensemble of anomaly detectors.
+
+    Parameters
+    ----------
+    models : Mapping[str, BaseDetector]
+        Named detectors to include in the ensemble. Example:
+
+            {
+                "pca":    PCAAnomaly(n_components = 10),
+                "iso":    IsolationForestAnomaly(),
+                "gdn":    GDN(epochs = 50),
+                "tranad": TranAD(window_size = 50),
+            }
+
+    combine : str, default = "mean"
+        Strategy for combining normalized per-model scores.
+        One of ``"mean"``, ``"median"``, ``"max"``.
+    normalize : str, default = "robust"
+        Per-model score normalization before combining.
+        One of ``"none"``, ``"minmax"``, ``"robust"``.
+        Statistics are estimated from training data.
+    percentile : float, default = 95.0
+        Percentile of ensemble training scores used as the default
+        anomaly threshold. Passed to ``BaseDetector._set_post_fit()``.
+
+    Attributes (set after fit)
+    --------------------------
+    decision_scores_ : np.ndarray, shape (n_windows,)
+        Ensemble anomaly scores on training data.
+    threshold_ : float
+        Default anomaly cutoff derived from training scores at ``percentile``.
+    labels_ : np.ndarray, shape (n_windows,)
+        Binary anomaly labels on training data. 0 = normal, 1 = anomaly.
+    """
+
+    def __init__(
+        self,
+        models: Mapping[str, BaseDetector],
+        combine: str = "mean",
+        normalize: str = "robust",
+        percentile: float = 95.0,
+    ):
+        super().__init__(percentile=percentile)
+        self.models = models
+        self.combine = combine
+        self.normalize = normalize
+
+        self._norm_stats: dict[str, dict] = {}
+
+    # ---- Helpers ----
+    def _compute_norm_stats(self, scores: np.ndarray, method: str) -> dict:
+        """
+        Compute normalization statistics from training scores.
+
+        Called once during ``fit()``. The returned dict is stored in
+        ``_norm_stats`` and reused at inference time by ``_apply_norm()``,
+        ensuring test scores are scaled on the same training distribution.
+
+        ``"robust"`` is preferred over ``"minmax"`` for anomaly detection
+        because anomalies are extreme values by definition: they would skew
+        a minmax scale and compress the normal operating range.
+
+        Parameters
+        ----------
+        scores : np.ndarray, shape (n_windows,)
+            Raw training scores from a single detector.
+        method : str
+            One of ``"none"``, ``"minmax"``, ``"robust"``.
+
+        Returns
+        -------
+        dict
+            Statistics needed to apply the same normalization to new data.
+        """
+
+        if method == "none":
+            return {}
+        if method == "minmax":
+            s_min = float(np.min(scores))
+            s_max = float(np.max(scores))
+            if s_max == s_min:
+                s_max = s_min + 1e-12
+            return {"min": s_min, "max": s_max}
+        if method == "robust":
+            med = float(np.median(scores))
+            q1 = float(np.percentile(scores, 25.0))
+            q3 = float(np.percentile(scores, 75.0))
+            iqr = q3 - q1
+            if iqr <= 0.0:
+                iqr = 1e-12
+            return {"median": med, "iqr": iqr}
+        raise ValueError(f"Unknown normalization method: {method!r}")
+
+    def _apply_norm(self, scores: np.ndarray, stats: dict, method: str) -> np.ndarray:
+        """
+        Apply normalization to a score array using training statistics.
+
+        For ``"robust"``, the formula ``0.5 + (x - median) / (2 * IQR)``
+        maps the middle 50% of training scores to approximately ``[0, 1]``.
+        Scores outside that range are clipped: genuine anomalies saturate
+        at 1.0, which is the desired behavior.
+
+        Parameters
+        ----------
+        scores : np.ndarray
+            Raw scores from a single detector (training or inference).
+        stats : dict
+            Statistics returned by ``_compute_norm_stats()``.
+        method : str
+            Must match the method used to compute ``stats``.
+
+        Returns
+        -------
+        np.ndarray
+            Normalized scores clipped to ``[0, 1]``.
+        """
+
+        scores = np.asarray(scores, dtype=float)
+        if method == "none":
+            return scores
+        if method == "minmax":
+            out = (scores - stats["min"]) / (stats["max"] - stats["min"])
+            return np.clip(out, 0.0, 1.0)
+        if method == "robust":
+            out = 0.5 + (scores - stats["median"]) / (2.0 * stats["iqr"])
+            return np.clip(out, 0.0, 1.0)
+        raise ValueError(f"Unknown normalization method: {method!r}")
+
+    def _combine_matrix(self, S: np.ndarray) -> np.ndarray:
+        """
+        Combine per-model score matrix into ensemble scores.
+
+        Parameters
+        ----------
+        S : np.ndarray, shape (n_models, n_windows)
+
+        Returns
+        -------
+        np.ndarray, shape (n_windows,)
+        """
+        if self.combine == "mean":
+            return np.mean(S, axis=0)
+        if self.combine == "median":
+            return np.median(S, axis=0)
+        if self.combine == "max":
+            return np.max(S, axis=0)
+        raise ValueError(f"Unknown combine strategy: {self.combine!r}")
+
+    # ---- BaseDetector interface ----
+    def fit(self, X: np.ndarray, y: np.ndarray | None = None) -> AnomalyEnsemble:
+        """
+        Fit all detectors and estimate normalization statistics.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+            Windowed telemetry tensor from windowify().
+        y : ignored
+
+        Returns
+        -------
+        self : AnomalyEnsemble
+        """
+        X = self._validate_X(X)
+
+        for _, model in self.models.items():
+            model.fit(X) if y is None else model.fit(X, y)
+
+        # Per-model training scores
+        per_model = {name: model.decision_function(X) for name, model in self.models.items()}
+
+        # Learn normalization stats from training scores
+        self._norm_stats = {
+            name: self._compute_norm_stats(scores, self.normalize)
+            for name, scores in per_model.items()
+        }
+
+        # Build normalized score matrix to ensemble scores
+        S = np.vstack(
+            [
+                self._apply_norm(scores, self._norm_stats[name], self.normalize)
+                for name, scores in per_model.items()
+            ]
+        )
+        ensemble_scores = self._combine_matrix(S)
+
+        self._set_post_fit(ensemble_scores)
+        return self
+
+    def decision_function(self, X: np.ndarray, *, normalize: bool = True) -> np.ndarray:
+        """
+        Compute ensemble anomaly scores.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+        normalize : bool, default=True
+            Apply configured normalization before combining.
+
+        Returns
+        -------
+        scores : np.ndarray, shape (n_windows,)
+            Higher = more anomalous.
+        """
+        self._require_fit()
+        X = self._validate_X(X)
+
+        per_model = self.score_components(X)
+
+        S = []
+        for name, scores in per_model.items():
+            if normalize and self.normalize != "none":
+                stats = self._norm_stats.get(name)
+                if stats is None:
+                    raise RuntimeError(
+                        f"No normalization stats for model '{name}'. "
+                        "Call fit() on the ensemble first."
+                    )
+                S.append(self._apply_norm(scores, stats, self.normalize))
+            else:
+                S.append(np.asarray(scores, dtype=float))
+
+        return self._combine_matrix(np.vstack(S))
+
+    # ---- SHAP hook ----
+    def score_components(self, X: np.ndarray) -> dict[str, np.ndarray]:
+        """
+        Per-model raw anomaly scores before combination.
+
+        This is the input to SHAPExplainer; SHAP perturbs X and measures
+        how each channel affects each model's score independently.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+
+        Returns
+        -------
+        dict
+            ``{model_name: np.ndarray of shape (n_windows,)}``
+        """
+        X = self._validate_X(X)
+        return {name: model.decision_function(X) for name, model in self.models.items()}
+
+    # ---- repr ----
+    def _get_params(self) -> dict:
+        return {
+            "models": list(self.models.keys()),
+            "combine": self.combine,
+            "normalize": self.normalize,
+            "percentile": self.percentile,
+        }

telemetry_anomdet/models/supervised/__init__.py

@@ -0,0 +1,7 @@
+# src/telemetry_anomdet/models/supervised/__init__.py
+
+"""
+Supervised models (labelled data).
+"""
+
+__all__ = []

telemetry_anomdet/models/unsupervised/__init__.py

@@ -0,0 +1,12 @@
+# src/telemetry_anomdet/models/unsupervised/__init__.py
+
+"""
+Unsupervised anomaly detection models.
+"""
+
+from .gaussian_nb import GaussianNaiveBayes
+from .isolation_forest import IsolationForestModel
+from .kmeans import KMeansAnomaly
+from .pca import PCAAnomaly
+
+__all__ = ["IsolationForestModel", "GaussianNaiveBayes", "KMeansAnomaly", "PCAAnomaly"]

telemetry_anomdet/models/unsupervised/gaussian_nb.py

@@ -0,0 +1,61 @@
+# src/telemetry_anomdet/models/supervised/bayes.py
+
+"""
+Gaussian Naive Bayes
+
+Each feature is assumed to follow a Gaussian (normal) distribution conditioned on the class label y.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..base import BaseDetector
+
+
+@dataclass
+class GaussianNaiveBayes(BaseDetector):
+    """
+    Gaussian Naive Bayes classifier.
+
+    Attributes
+    ----------
+    classes : np.ndarray
+        Unique class labels observed during training.
+    mean : dict
+        Per-class feature means.
+    var : dict
+        Per-class feature variances.
+    priors : dict
+        Class prior probabilities.
+    """
+
+    def fit(self, X: np.ndarray, y: np.ndarray):
+        """
+        Estimate mean, variance, and prior for each class.
+        """
+
+        pass
+
+    def _pdf(self, class_idx, x: np.ndarray):
+        """
+        Compute the Gaussian probability density for a given class.
+        """
+
+        pass
+
+    def _posterior(self, x: np.ndarray):
+        """
+        Compute the posterior probability for each class.
+        """
+
+        pass
+
+    def predict(self, X: np.ndarray):
+        """
+        Predict class label for each sample.
+        """
+
+        pass

telemetry_anomdet/models/unsupervised/isolation_forest.py

@@ -0,0 +1,28 @@
+# src/telemetry_anomdet/models/unsupervised/isolation_forest.py
+
+"""
+Isolation Forest unsupervised anomaly detector wrapper.
+
+This module exposes a simple class with a consistent API:
+- fit(X)
+- predict(X) -> anomaly scores (higher = more anomalous)
+- save / load via BaseModel
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..base import BaseDetector
+
+
+@dataclass
+class IsolationForestModel(BaseDetector):
+    """
+    Wrapper for sklearn IsolationForest.
+
+    Parameters
+    ----------
+    config:
+        Optional dict to pass to sklearn IsolationForest.
+    """

telemetry_anomdet/models/unsupervised/kmeans.py

@@ -0,0 +1,204 @@
+# src/telemetry_anomdet/models/unsupervised/kmeans.py
+
+"""
+K-Means clustering anomaly detection.
+
+Each telemetry window is assigned to its nearest cluster centroid.
+Anomaly scores are distances to the nearest centroid. Windows far from
+any learned nominal operating mode score higher and are flagged as anomalies.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.cluster import KMeans
+from sklearn.preprocessing import StandardScaler
+
+from ...feature_extraction import features
+from ..base import BaseDetector
+
+
+class KMeansAnomaly(BaseDetector):
+    """
+    K-Means clustering based anomaly detector.
+
+    Accepts 3D windowed input (n_windows, window_size, n_features) and
+    flattens internally via features_stat() before clustering. The caller
+    never needs to manage this conversion.
+
+    Parameters
+    ----------
+    n_clusters : int, default = 5
+        Number of clusters (nominal operating modes) to learn. Each cluster
+        represents a recurring pattern in the telemetry.
+    scale : bool, default = False
+        Apply StandardScaler before clustering. Enable when channels differ
+        significantly in scale so distance calculations are not dominated by
+        high-magnitude channels.
+    percentile : float, default = 95.0
+        Percentile of training centroid distances used to set the default
+        anomaly threshold. 95.0 means the top 5% most distant training
+        windows are labelled as anomalies.
+
+    Attributes (set after fit)
+    --------------------------
+    decision_scores_ : np.ndarray, shape (n_windows,)
+        Distance-to-nearest-centroid scores on training data.
+    threshold_ : float
+        Default anomaly cutoff derived from training scores at ``percentile``.
+    labels_ : np.ndarray, shape (n_windows,)
+        Binary anomaly labels on training data. 0 = normal, 1 = anomaly.
+    model : sklearn.cluster.KMeans
+        Fitted KMeans instance.
+    centroids : np.ndarray, shape (n_clusters, n_features)
+        Learned cluster centers in the (optionally scaled) feature space.
+    scaler : sklearn.preprocessing.StandardScaler or None
+        Fitted scaler when ``scale=True``, otherwise None.
+    """
+
+    def __init__(
+        self,
+        n_clusters: int = 5,
+        scale: bool = False,
+        percentile: float = 95.0,
+    ):
+        super().__init__(percentile=percentile)
+        self.n_clusters = n_clusters
+        self.scale = scale
+
+        # Fit artifacts: set in fit()
+        self.model: KMeans | None = None
+        self.centroids: np.ndarray | None = None
+        self.scaler: StandardScaler | None = None
+
+    # ---- helpers ----
+    def _flatten(self, X: np.ndarray) -> np.ndarray:
+        """
+        Flatten 3D windowed tensor to 2D feature matrix via features_stat().
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+
+        Returns
+        -------
+        X2d : np.ndarray, shape (n_windows, n_features * 6)
+            Statistical features per window: mean, std, min, max, median, slope.
+        """
+        return features.features_stat(X)
+
+    def _scale_fit(self, X2d: np.ndarray) -> np.ndarray:
+        if self.scale:
+            self.scaler = StandardScaler()
+            return self.scaler.fit_transform(X2d)
+        self.scaler = None
+        return X2d
+
+    def _scale_transform(self, X2d: np.ndarray) -> np.ndarray:
+        if self.scale:
+            if self.scaler is None:
+                raise RuntimeError("Scaler is not fitted. Was the model fitted with scale=True?")
+            return self.scaler.transform(X2d)
+        return X2d
+
+    def _centroid_distances(self, Xs: np.ndarray) -> np.ndarray:
+        """Distance from each sample to its nearest centroid."""
+        return self.model.transform(Xs).min(axis=1)
+
+    # ---- BaseDetector interface ----
+    def fit(self, X: np.ndarray, y: np.ndarray | None = None) -> KMeansAnomaly:
+        """
+        Fit K-Means on nominal telemetry windows.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+            Windowed telemetry tensor from windowify().
+        y : ignored
+            Present for API consistency.
+
+        Returns
+        -------
+        self : KMeansAnomaly
+
+        Raises
+        ------
+        ValueError
+            If n_clusters < 1 or n_clusters > n_windows.
+        """
+        X = self._validate_X(X)
+        X2d = self._flatten(X)
+        n_windows = X2d.shape[0]
+
+        if self.n_clusters < 1:
+            raise ValueError("n_clusters must be at least 1.")
+        if self.n_clusters > n_windows:
+            raise ValueError(
+                f"n_clusters ({self.n_clusters}) cannot exceed the number of "
+                f"windows ({n_windows}). Reduce n_clusters or increase your data."
+            )
+
+        Xs = self._scale_fit(X2d)
+
+        self.model = KMeans(
+            n_clusters=self.n_clusters,
+            n_init=10,
+            random_state=0,
+        )
+        self.model.fit(Xs)
+        self.centroids = self.model.cluster_centers_
+
+        scores = self._centroid_distances(Xs)
+        self._set_post_fit(scores)
+        return self
+
+    def decision_function(self, X: np.ndarray) -> np.ndarray:
+        """
+        Compute distance-to-nearest-centroid scores for each window.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+
+        Returns
+        -------
+        scores : np.ndarray, shape (n_windows,)
+            Centroid distances. Higher = more anomalous.
+        """
+        self._require_fit()
+        X = self._validate_X(X)
+        X2d = self._flatten(X)
+        Xs = self._scale_transform(X2d)
+        return self._centroid_distances(Xs)
+
+    # ---- KMeans specific method ----
+    def predict_clusters(self, X: np.ndarray) -> np.ndarray:
+        """
+        Assign each window to its nearest cluster.
+
+        Unique to KMeansAnomaly. Not part of the BaseDetector interface.
+        Useful for understanding which nominal operating mode each window
+        belongs to, independent of whether it is flagged as an anomaly.
+
+        Parameters
+        ----------
+        X : np.ndarray, shape (n_windows, window_size, n_features)
+
+        Returns
+        -------
+        cluster_labels : np.ndarray of int, shape (n_windows,)
+            Cluster index in [0, n_clusters - 1] for each window.
+        """
+        self._require_fit()
+        X = self._validate_X(X)
+        X2d = self._flatten(X)
+        Xs = self._scale_transform(X2d)
+        return self.model.predict(Xs)
+
+    # ---- Repr support ----
+    def _get_params(self) -> dict:
+        return {
+            "n_clusters": self.n_clusters,
+            "scale": self.scale,
+            "percentile": self.percentile,
+        }