tsadmetrics 0.1.17__py3-none-any.whl → 1.0.0__py3-none-any.whl

tsadmetrics/metrics/tem/tpdm/PointadjustedFScore.py

@@ -0,0 +1,96 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise
+
+class PointadjustedFScore(Metric):
+    """
+    Point-adjusted F-score for anomaly detection in time series.
+
+    This metric modifies the standard F-score by applying a temporal adjustment
+    to the predictions:
+    
+    - For each ground-truth anomalous segment, if at least one point is predicted
+      as anomalous, all points in that segment are considered correctly detected.
+    - The adjusted predictions are then compared to the ground-truth labels using
+      the standard point-wise F-score formula.
+
+    Reference:
+        Implementation based on:
+        https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+        Original paper for point-adjusted evaluation:
+        https://doi.org/10.1145/3178876.3185996
+
+    Attributes:
+        name (str):
+            Fixed name identifier for this metric: `"paf"`.
+        binary_prediction (bool):
+            Indicates that this metric expects binary predictions.
+        param_schema (dict):
+            Defines supported parameters. Includes:
+                - beta (float): Weighting factor for recall in the F-score
+                  calculation. Default = 1.0.
+
+    Raises:
+        ValueError:
+            If `y_true` and `y_pred` have mismatched lengths.
+        TypeError:
+            If inputs are not array-like.
+    """
+
+    name = "paf"
+    binary_prediction = True
+    param_schema = {
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the PointadjustedFScore metric.
+
+        Parameters:
+            **kwargs:
+                Optional keyword arguments passed to the base `Metric` class.
+                Supported parameter:
+                    - beta (float): Weight factor for recall in the F-score.
+        """
+        super().__init__(name="paf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Compute the point-adjusted F-score.
+
+        Parameters:
+            y_true (np.ndarray):
+                Ground-truth binary labels for the time series (0 = normal, 1 = anomaly).
+            y_pred (np.ndarray):
+                Predicted binary labels for the time series (0 = normal, 1 = anomaly).
+
+        Returns:
+            float:
+                The computed point-adjusted F-score. Returns 0 if either precision or
+                recall is 0.
+        """
+        adjusted_prediction = y_pred.copy()
+
+        for start, end in full_series_to_segmentwise(y_true):
+            if np.any(adjusted_prediction[start:end + 1]):
+                adjusted_prediction[start:end + 1] = 1
+            else:
+                adjusted_prediction[start:end + 1] = 0
+
+        tp = np.sum(adjusted_prediction * y_true)
+        fp = np.sum(adjusted_prediction * (1 - y_true))
+        fn = np.sum((1 - adjusted_prediction) * y_true)
+
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0
+        recall = tp / (tp + fn) if (tp + fn) > 0 else 0
+
+        if precision == 0 or recall == 0:
+            return 0
+
+        beta = self.params['beta']
+        return ((1 + beta**2) * precision * recall) / (beta**2 * precision + recall)

tsadmetrics/metrics/tem/tpdm/RangebasedFScore.py

@@ -0,0 +1,236 @@
+from ....base.Metric import Metric
+import numpy as np
+
+class RangebasedFScore(Metric):
+    """
+    Range-based F-score for anomaly detection in time series.
+
+    This metric evaluates anomaly detection performance over temporal ranges,
+    combining range-based precision and recall into a harmonic mean. It accounts
+    for positional bias, existence and overlap rewards, and cardinality penalties,
+    allowing fine-grained control over missed detections and false alarms.
+
+    References:
+        - Implementation: https://link.springer.com/article/10.1007/s10618-023-00988-8
+        - Original range-based anomaly detection paper: 
+          https://proceedings.neurips.cc/paper_files/paper/2018/file/8f468c873a32bb0619eaeb2050ba45d1-Paper.pdf
+
+    Parameters:
+        p_alpha (float): 
+            Relative importance of existence reward for precision (0 <= alpha_p <= 1).
+        r_alpha (float): 
+            Relative importance of existence reward for recall (0 <= alpha_r <= 1).
+        p_bias (str): 
+            Positional bias for precision ("flat", "front", "middle", "back").
+        r_bias (str): 
+            Positional bias for recall ("flat", "front", "middle", "back").
+        cardinality_mode (str, optional): 
+            Cardinality factor type ("one", "reciprocal", "udf_gamma").
+        beta (float): 
+            Weight of precision in the F-score. Default = 1.
+
+    Attributes:
+        name (str): 
+            Fixed metric name `"rbf"`.
+        binary_prediction (bool): 
+            True, this metric expects binary predictions.
+        param_schema (dict): 
+            Parameter schema and defaults.
+    """
+
+    name = "rbf"
+    binary_prediction = True
+    param_schema = {
+        "beta": {"default": 1.0, "type": float},
+        "p_alpha": {"default": 0.5, "type": float},
+        "r_alpha": {"default": 0.5, "type": float},
+        "p_bias": {"default": "flat", "type": str},
+        "r_bias": {"default": "flat", "type": str},
+        "cardinality_mode": {"default": "one", "type": str},
+    }
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the RangebasedFScore metric.
+
+        Parameters:
+            **kwargs: Additional parameters matching the param_schema.
+        """
+        super().__init__(name="rbf", **kwargs)
+
+    # -----------------------
+    # Utility functions
+    # -----------------------
+
+    def _udf_gamma(self):
+        """User-defined gamma function (default implementation)."""
+        return 1.0
+
+    def _gamma_select(self, gamma: str, overlap: int) -> float:
+        """
+        Select gamma value based on cardinality mode and overlap.
+
+        Args:
+            gamma (str): 'one', 'reciprocal', or 'udf_gamma'.
+            overlap (int): Number of overlapping ranges.
+
+        Returns:
+            float: Selected gamma factor.
+        """
+        assert isinstance(overlap, int), TypeError("overlap must be int")
+
+        if gamma == "one":
+            return 1.0
+        elif gamma == "reciprocal":
+            return 1.0 / overlap if overlap > 1 else 1.0
+        elif gamma == "udf_gamma":
+            return 1.0 / self._udf_gamma() if overlap > 1 else 1.0
+        else:
+            raise ValueError(f"Invalid gamma type: {gamma}")
+
+    def _gamma_function(self, overlap_count):
+        """Compute gamma factor from overlap count based on cardinality mode."""
+        return self._gamma_select(self.params['cardinality_mode'], overlap_count[0])
+
+    def _compute_omega_reward(self, bias, r1, r2, overlap_count):
+        """
+        Compute omega reward based on overlap of two ranges with positional bias.
+
+        Args:
+            bias (str): Positional bias type.
+            r1 (np.array): First range [start, end].
+            r2 (np.array): Second range [start, end].
+            overlap_count (list): List to track number of overlaps.
+
+        Returns:
+            float: Omega reward.
+        """
+        if r1[1] < r2[0] or r1[0] > r2[1]:
+            return 0
+        overlap_count[0] += 1
+        overlap = np.zeros(r1.shape)
+        overlap[0] = max(r1[0], r2[0])
+        overlap[1] = min(r1[1], r2[1])
+        return self._omega_function(bias, r1, overlap)
+
+    def _omega_function(self, bias, rrange, overlap):
+        """Compute normalized positional omega function for range overlap."""
+        anomaly_length = rrange[1] - rrange[0] + 1
+        my_positional_bias, max_positional_bias = 0, 0
+
+        for i in range(1, anomaly_length + 1):
+            temp_bias = self._delta_function(bias, i, anomaly_length)
+            max_positional_bias += temp_bias
+            j = rrange[0] + i - 1
+            if overlap[0] <= j <= overlap[1]:
+                my_positional_bias += temp_bias
+
+        return my_positional_bias / max_positional_bias if max_positional_bias > 0 else 0
+
+    def _delta_function(self, bias, t, anomaly_length):
+        """Compute positional delta function for omega."""
+        return self._delta_select(bias, t, anomaly_length)
+
+    def _delta_select(self, delta, t, anomaly_length):
+        """Select positional bias value based on delta type."""
+        if delta == "flat":
+            return 1.0
+        elif delta == "front":
+            return float(anomaly_length - t + 1)
+        elif delta == "middle":
+            return float(t if t <= anomaly_length / 2 else anomaly_length - t + 1)
+        elif delta == "back":
+            return float(t)
+        elif delta == "udf_delta":
+            return self._udf_delta(t, anomaly_length)
+        else:
+            raise ValueError("Invalid positional bias value")
+
+    def _udf_delta(self, t=None, anomaly_length=None):
+        """User-defined delta function (default returns 1.0)."""
+        return 1.0
+
+    def _shift(self, arr, num, fill_value=np.nan):
+        """Shift array by `num` positions, filling empty slots."""
+        arr = np.roll(arr, num)
+        if num < 0:
+            arr[num:] = fill_value
+        elif num > 0:
+            arr[:num] = fill_value
+        return arr
+
+    def _prepare_data(self, values_real, values_pred):
+        """
+        Prepare ranges for real and predicted anomalies.
+
+        Returns:
+            Tuple of numpy arrays: (real_anomalies, predicted_anomalies)
+        """
+        assert len(values_real) == len(values_pred)
+        predicted_anomalies_ = np.argwhere(values_pred == 1).ravel()
+        predicted_anomalies = self._extract_ranges(predicted_anomalies_)
+        real_anomalies_ = np.argwhere(values_real == 1).ravel()
+        real_anomalies = self._extract_ranges(real_anomalies_)
+        return real_anomalies, predicted_anomalies
+
+    def _extract_ranges(self, anomaly_indices):
+        shifted_fwd = self._shift(anomaly_indices, 1, fill_value=anomaly_indices[0])
+        shifted_bwd = self._shift(anomaly_indices, -1, fill_value=anomaly_indices[-1])
+        start = np.argwhere((shifted_fwd - anomaly_indices) != -1).ravel()
+        end = np.argwhere((anomaly_indices - shifted_bwd) != -1).ravel()
+        return np.hstack([anomaly_indices[start].reshape(-1, 1), anomaly_indices[end].reshape(-1, 1)])
+
+    # -----------------------
+    # Range-based precision & recall
+    # -----------------------
+
+    def _compute_precision(self, y_true, y_pred):
+        """Compute range-based precision."""
+        alpha = self.params["p_alpha"]
+        if len(y_pred) == 0:
+            return 0
+        precision = 0
+        for range_p in y_pred:
+            omega_reward, overlap_count = 0, [0]
+            for range_r in y_true:
+                omega_reward += self._compute_omega_reward(self.params["p_bias"], range_p, range_r, overlap_count)
+            overlap_reward = self._gamma_function(overlap_count) * omega_reward
+            existence_reward = 1 if overlap_count[0] > 0 else 0
+            precision += alpha * existence_reward + (1 - alpha) * overlap_reward
+        return precision / len(y_pred)
+
+    def _compute_recall(self, y_true, y_pred):
+        """Compute range-based recall."""
+        alpha = self.params["r_alpha"]
+        if len(y_true) == 0:
+            return 0
+        recall = 0
+        for range_r in y_true:
+            omega_reward, overlap_count = 0, [0]
+            for range_p in y_pred:
+                omega_reward += self._compute_omega_reward(self.params["r_bias"], range_r, range_p, overlap_count)
+            overlap_reward = self._gamma_function(overlap_count) * omega_reward
+            existence_reward = 1 if overlap_count[0] > 0 else 0
+            recall += alpha * existence_reward + (1 - alpha) * overlap_reward
+        return recall / len(y_true)
+
+    # -----------------------
+    # Metric computation
+    # -----------------------
+
+    def _compute(self, y_true, y_pred):
+        """
+        Compute the range-based F-score.
+
+        Returns:
+            float: F-beta score using range-based precision and recall.
+        """
+        if np.sum(y_pred) == 0:
+            return 0
+
+        beta = self.params['beta']
+        y_true_mod, y_pred_mod = self._prepare_data(y_true, y_pred)
+        precision = self._compute_precision(y_true_mod, y_pred_mod)
+        recall = self._compute_recall(y_true_mod, y_pred_mod)
+
+        return (1 + beta ** 2) * precision * recall / (beta ** 2 * precision + recall) if precision + recall > 0 else 0

tsadmetrics/metrics/tem/tpdm/SegmentwiseFScore.py

@@ -0,0 +1,73 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise
+
+class SegmentwiseFScore(Metric):
+    """
+    Segment-wise F-score for anomaly detection in time series.
+
+    This metric computes the F-score at the segment level rather than point-wise.
+    Each contiguous segment of anomalies in the ground truth is treated as a unit.
+    - True positive (TP): at least one predicted anomaly within a ground-truth segment.
+    - False negative (FN): no predicted anomaly in a ground-truth segment.
+    - False positive (FP): predicted segment with no overlap with any ground-truth segment.
+
+    References:
+        - Implementation: https://link.springer.com/article/10.1007/s10618-023-00988-8
+        - Original paper: https://doi.org/10.1145/3219819.3219845
+
+    Parameters:
+        beta (float): Weight of precision in the harmonic mean.
+                      Default is 1.0 (balanced F1-score).
+    """
+
+    name = "swf"
+    binary_prediction = True
+    param_schema = {
+        "beta": {"default": 1.0, "type": float}
+    }
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the SegmentwiseFScore metric.
+
+        Parameters:
+            **kwargs: Additional parameters matching param_schema.
+        """
+        super().__init__(name="swf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Compute the segment-wise F-score.
+
+        Parameters:
+            y_true (np.array): Ground truth binary labels.
+            y_pred (np.array): Predicted binary labels.
+
+        Returns:
+            float: Segment-wise F-score.
+        """
+        beta = self.params["beta"]
+
+        # Count true positives and false negatives per ground-truth segment
+        tp, fn = 0, 0
+        for gt_segment in full_series_to_segmentwise(y_true):
+            if np.any(y_pred[gt_segment[0]:gt_segment[1]+1]):
+                tp += 1
+            else:
+                fn += 1
+
+        # Count false positives per predicted segment
+        fp = 0
+        for pred_segment in full_series_to_segmentwise(y_pred):
+            if not np.any(y_true[pred_segment[0]:pred_segment[1]+1]):
+                fp += 1
+
+        # Compute precision and recall
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0
+        recall = tp / (tp + fn) if (tp + fn) > 0 else 0
+
+        # Return F-beta score
+        if precision == 0 or recall == 0:
+            return 0.0
+        return (1 + beta**2) * precision * recall / (beta**2 * precision + recall)

tsadmetrics/metrics/tem/tpdm/__init__.py

@@ -0,0 +1,12 @@
+from .CompositeFScore import CompositeFScore
+from .PointadjustedAucPr import PointadjustedAucPr
+from .PointadjustedAucRoc import PointadjustedAucRoc
+from .SegmentwiseFScore import SegmentwiseFScore
+from .RangebasedFScore  import RangebasedFScore
+from .PointadjustedFScore import PointadjustedFScore
+__all__ = ['CompositeFScore',
+           'PointadjustedAucPr',
+           'PointadjustedAucRoc',
+           'SegmentwiseFScore',
+            'RangebasedFScore',
+           'PointadjustedFScore']

tsadmetrics/metrics/tem/tstm/AffiliationbasedFScore.py

@@ -0,0 +1,68 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise
+from ....utils.functions_affiliation import pr_from_events, reformat_segments
+
+class AffiliationbasedFScore(Metric):
+    """
+    Calculate affiliation based F-score for anomaly detection in time series.
+
+    This metric combines the affiliation-based precision and recall into a single score 
+    using the harmonic mean, adjusted by a weight :math:`{\\beta}` to control the relative importance 
+    of recall versus precision. Since both precision and recall are distance-based, 
+    the F-score reflects a balance between how well predicted anomalies align with true 
+    anomalies and vice versa.
+
+    Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    For more information, see the original paper:
+    https://dl.acm.org/doi/10.1145/3534678.3539339
+
+    Parameters:
+        beta (float):
+            The beta value, which determines the weight of precision in the combined score.
+            Default is 1, which gives equal weight to precision and recall.
+    """
+    name = "aff_f"
+    binary_prediction = True
+    param_schema = {
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="aff_f", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the affiliation based F-score.
+
+        Parameters:
+            y_true (np.array):
+                The ground truth binary labels for the time series data.
+            y_pred (np.array):
+                The predicted binary labels for the time series data.
+
+        Returns:
+            float: The affiliation based F-score.
+        """
+
+        if np.sum(y_pred) == 0:
+            return 0
+
+        pr_output = pr_from_events(
+            reformat_segments(full_series_to_segmentwise(y_pred)),
+            reformat_segments(full_series_to_segmentwise(y_true)),
+            (0, len(y_true)),
+        )
+
+        precision = pr_output['precision']
+        recall = pr_output['recall']
+
+        if precision == 0 or recall == 0:
+            return 0
+
+        beta = self.params["beta"]
+        return ((1 + beta**2) * precision * recall) / (beta**2 * precision + recall)

tsadmetrics/metrics/tem/tstm/Pate.py

@@ -0,0 +1,62 @@
+from ....base.Metric import Metric
+from pate.PATE_metric import PATE
+import numpy as np
+
+
+class Pate(Metric):
+    """
+    Calculate PATE score for anomaly detection in time series using real-valued anomaly scores.
+
+    This version of PATE evaluates real-valued anomaly scores by assigning weights to predictions 
+    based on their temporal proximity to the true anomaly intervals. It defines an early buffer of 
+    length `early` before each anomaly and a delay buffer of length `delay` after it. Detections with 
+    high scores within the anomaly interval receive full weight, while those in the buffer zones are 
+    assigned linearly decaying weights depending on their distance from the interval. Scores outside 
+    these zones contribute to false positives, and intervals with insufficient detection are penalized 
+    as false negatives.
+
+    The final PATE score aggregates these weighted contributions across all time steps, yielding 
+    a smooth performance measure that is sensitive to both the timing and confidence of the predictions.
+
+    Implementation of https://arxiv.org/abs/2405.12096
+
+    For more information, see the original paper:
+    https://arxiv.org/abs/2405.12096
+
+    Parameters:
+        early (int):
+            Length of the early buffer zone before each anomaly interval.
+        delay (int):
+            Length of the delay buffer zone after each anomaly interval.
+    """
+    name = "pate"
+    binary_prediction = False
+    param_schema = {
+        "early": {
+            "default": 5,
+            "type": int
+        },
+        "delay": {
+            "default": 5,
+            "type": int
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="pate", **kwargs)
+
+    def _compute(self, y_true, y_anomaly_scores):
+        """
+        Calculate the real-valued PATE score.
+
+        Parameters:
+            y_true (np.array):
+                Ground truth binary labels (0 = normal, 1 = anomaly).
+            y_anomaly_scores (np.array):
+                Real-valued anomaly scores for each time point.
+
+        Returns:
+            float: The real-valued PATE score.
+        """
+
+        return PATE(y_true, y_anomaly_scores, self.params["early"], self.params["delay"], binary_scores=False)

tsadmetrics/metrics/tem/tstm/PateFScore.py

@@ -0,0 +1,61 @@
+from ....base.Metric import Metric
+from pate.PATE_metric import PATE
+
+
+class PateFScore(Metric):
+    """
+    Calculate PATE score for anomaly detection in time series.
+    
+    PATE evaluates predictions by assigning weighted scores based on temporal proximity 
+    to true anomaly intervals. It uses buffer zones around each true anomaly: an early buffer of length
+    `early` preceding the interval and a delay buffer of length `delay` following it. Detections within
+    the true interval receive full weight, while those in the early or delay buffers receive linearly
+    decaying weights based on distance from the interval edges. Predictions outside these zones are
+    treated as false positives, and missed intervals as false negatives. The final score balances these
+    weighted detections into a single measure of performance.
+
+    Implementation of https://arxiv.org/abs/2405.12096
+    
+    For more information, see the original paper:
+    https://arxiv.org/abs/2405.12096
+
+    Parameters:
+        early (int):
+            The maximum number of time steps before an anomaly must be predicted to be considered early.
+        delay (int):
+            The maximum number of time steps after an anomaly must be predicted to be considered delayed.
+    """
+    name = "pate_f1"
+    binary_prediction = True
+    param_schema = {
+        "early": {
+            "default": 5,
+            "type": int
+        },
+        "delay": {
+            "default": 5,
+            "type": int
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="pate_f1", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the PATE score.
+
+        Parameters:
+            y_true (np.array):
+                The ground truth binary labels for the time series data.
+            y_pred (np.array):
+                The predicted binary labels for the time series data.
+
+        Returns:
+            float: The PATE score.
+        """
+
+        early = self.params["early"]
+        delay = self.params["delay"]
+
+        return PATE(y_true, y_pred, early, delay, binary_scores=True)