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

tsadmetrics/metrics/spm/PointwiseAucPr.py

@@ -0,0 +1,62 @@
+from ...base.Metric import Metric
+import numpy as np
+from ...utils.functions_auc import precision_recall_curve
+
+class PointwiseAucPr(Metric):
+    """
+    Point-wise Area Under the Precision-Recall Curve (AUC-PR) for anomaly detection.
+
+    This metric computes the standard Area Under the Precision-Recall Curve (AUC-PR)
+    in a **point-wise manner**. Each time-series data point is treated independently
+    when calculating precision and recall, making this suitable for anomaly detection tasks
+    where anomalies are labeled at the individual point level.
+
+    Reference:
+        Implementation based on:
+        https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    Attributes:
+        name (str):
+            Fixed name identifier for this metric: `"pw_auc_pr"`.
+        binary_prediction (bool):
+            Indicates whether this metric expects binary predictions. Always `False`
+            since it requires continuous anomaly scores.
+
+    Raises:
+        ValueError:
+            If input arrays are invalid or improperly shaped (handled by the base class).
+        TypeError:
+            If inputs are not array-like.
+    """
+    
+    name = "pw_auc_pr"
+    binary_prediction = False
+    def __init__(self, **kwargs):
+        """
+        Initialize the PointwiseAucPr metric.
+
+        Parameters:
+            **kwargs:
+                Additional keyword arguments passed to the base `Metric` class.
+                These may include configuration parameters or overrides.
+        """
+        super().__init__(name="pw_auc_pr", **kwargs)
+
+    def _compute(self, y_true, y_anomaly_scores):
+        """
+        Compute the point-wise AUC-PR score.
+
+        Parameters:
+            y_true (np.ndarray):
+                Ground-truth binary labels for the time series.
+                Values must be 0 (normal) or 1 (anomaly).
+            y_anomaly_scores (np.ndarray):
+                Continuous anomaly scores assigned to each point in the series.
+
+        Returns:
+            float:
+                The computed point-wise AUC-PR score.
+        """
+
+        precision, recall, _ = precision_recall_curve(y_true, y_anomaly_scores)
+        return -np.sum(np.diff(recall) * np.array(precision)[:-1])

tsadmetrics/metrics/spm/PointwiseAucRoc.py

@@ -0,0 +1,63 @@
+from ...base.Metric import Metric
+import numpy as np
+from ...utils.functions_auc import roc_curve, auc
+
+class PointwiseAucRoc(Metric):
+    """
+    Point-wise Area Under the Receiver Operating Characteristic Curve (AUC-ROC) for anomaly detection.
+
+    This metric computes the standard Area Under the ROC Curve (AUC-ROC)
+    in a **point-wise manner**. Each time-series data point is treated independently
+    when calculating true positives, false positives, and false negatives.
+    It is widely used to evaluate the ability of anomaly scoring functions
+    to distinguish between normal and anomalous points.
+
+    Reference:
+        Implementation based on:
+        https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    Attributes:
+        name (str):
+            Fixed name identifier for this metric: `"pw_auc_roc"`.
+        binary_prediction (bool):
+            Indicates whether this metric expects binary predictions. Always `False`
+            since it requires continuous anomaly scores.
+
+    Raises:
+        ValueError:
+            If input arrays are invalid or improperly shaped (validated in the base class).
+        TypeError:
+            If inputs are not array-like.
+    """
+
+    name = "pw_auc_roc"
+    binary_prediction = False
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the PointwiseAucRoc metric.
+
+        Parameters:
+            **kwargs:
+                Additional keyword arguments passed to the base `Metric` class.
+                These may include configuration parameters or overrides.
+        """
+        super().__init__(name="pw_auc_roc", **kwargs)
+
+    def _compute(self, y_true, y_anomaly_scores):
+        """
+        Compute the point-wise AUC-ROC score.
+
+        Parameters:
+            y_true (np.ndarray):
+                Ground-truth binary labels for the time series.
+                Values must be 0 (normal) or 1 (anomaly).
+            y_anomaly_scores (np.ndarray):
+                Continuous anomaly scores assigned to each point in the series.
+
+        Returns:
+            float:
+                The computed point-wise AUC-ROC score.
+        """
+        fpr, tpr, _ = roc_curve(y_true, y_anomaly_scores)
+        return auc(fpr, tpr)

tsadmetrics/metrics/spm/PointwiseFScore.py

@@ -0,0 +1,86 @@
+from ...base.Metric import Metric
+import numpy as np
+
+class PointwiseFScore(Metric):
+    """
+    Point-wise F-score for anomaly detection in time series.
+
+    This metric computes the classical F-score without considering temporal context,
+    treating each time-series point independently. It balances precision and recall
+    according to the configurable parameter `beta`.
+
+    Reference:
+        Implementation based on:
+        https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    Parameters:
+        beta (float, optional):
+            The beta value determines the relative weight of recall compared to precision.
+            A value of 1.0 gives equal weight (F1-score).
+            Default is 1.0.
+
+    Attributes:
+        name (str):
+            Fixed name identifier for this metric: `"pwf"`.
+        binary_prediction (bool):
+            Indicates whether this metric expects binary predictions. Always `True`.
+        param_schema (dict):
+            Schema for supported parameters:
+            - `beta` (float, default=1.0).
+
+    Raises:
+        ValueError:
+            If required parameters are missing (validated by the base class).
+        TypeError:
+            If parameter types do not match the schema (validated by the base class).
+    """
+
+    name = "pwf"
+    binary_prediction = True
+    param_schema = {
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the PointwiseFScore metric.
+
+        Parameters:
+            **kwargs:
+                Additional keyword arguments passed to the base `Metric` class.
+                These may include configuration parameters such as `beta`.
+        """
+        super().__init__(name="pwf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Compute the point-wise F-score.
+
+        Parameters:
+            y_true (np.ndarray):
+                Ground-truth binary labels for the time series.
+                Values must be 0 (normal) or 1 (anomaly).
+            y_pred (np.ndarray):
+                Predicted binary labels for the time series.
+                Values must be 0 (normal) or 1 (anomaly).
+
+        Returns:
+            float:
+                The computed point-wise F-score.
+                Returns 0 if either precision or recall is 0.
+        """
+        tp = np.sum(y_pred * y_true)
+        fp = np.sum(y_pred * (1 - y_true))
+        fn = np.sum((1 - y_pred) * 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/spm/PrecisionAtK.py

@@ -0,0 +1,81 @@
+from ...base.Metric import Metric
+import numpy as np
+
+class PrecisionAtK(Metric):
+    """
+    Precision at K (P@K) for anomaly detection in time series.
+
+    This metric evaluates how many of the top-`k` points with the highest anomaly
+    scores correspond to true anomalies. It is particularly useful when focusing
+    on identifying the most anomalous points rather than setting a global threshold.
+
+    By definition, `k` is automatically set to the number of true anomalies present
+    in `y_true`.
+
+    .. math::
+        k = \sum(y\_true)
+
+    Reference:
+        Implementation based on:
+        https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    Attributes:
+        name (str):
+            Fixed name identifier for this metric: `"pak"`.
+        binary_prediction (bool):
+            Indicates whether this metric expects binary predictions. Always `False`
+            since it requires continuous anomaly scores.
+
+    Raises:
+        AssertionError:
+            - If the number of true anomalies (`k`) is zero.
+            - If the number of predicted positives is less than `k`.
+        ValueError:
+            If input arrays are invalid or improperly shaped (validated in the base class).
+        TypeError:
+            If inputs are not array-like.
+    """
+
+    name = "pak"
+    binary_prediction = False
+
+    def __init__(self, **kwargs):
+        """
+        Initialize the PrecisionAtK metric.
+
+        Parameters:
+            **kwargs:
+                Additional keyword arguments passed to the base `Metric` class.
+                These may include configuration parameters or overrides.
+        """
+        super().__init__(name="pak", **kwargs)
+
+    def _compute(self, y_true, y_anomaly_scores):
+        """
+        Compute the Precision at K (P@K) score.
+
+        Parameters:
+            y_true (np.ndarray):
+                Ground-truth binary labels for the time series.
+                Values must be 0 (normal) or 1 (anomaly).
+            y_anomaly_scores (np.ndarray):
+                Continuous anomaly scores assigned to each point in the series.
+
+        Returns:
+            float:
+                The precision at K score, where K = number of anomalies in `y_true`.
+
+        Raises:
+            AssertionError:
+                If `k = sum(y_true)` is 0.
+                If fewer than `k` points are predicted as anomalies.
+        """
+        k = int(sum(y_true))
+        assert k > 0, "The number of true anomalies (k) must be greater than zero."
+        threshold = np.sort(y_anomaly_scores)[-k]
+
+        pred = y_anomaly_scores >= threshold
+        assert sum(pred) >= k, (
+            f"Number of predicted positives ({sum(pred)}) should be >= k ({k})."
+        )
+        return np.dot(pred, y_true) / sum(pred)

tsadmetrics/metrics/spm/__init__.py

@@ -0,0 +1,9 @@
+from .PointwiseFScore import PointwiseFScore
+from .PrecisionAtK import PrecisionAtK
+from .PointwiseAucRoc import PointwiseAucRoc
+from .PointwiseAucPr  import PointwiseAucPr
+
+__all__ = ['PointwiseFScore', 
+           'PrecisionAtK', 
+           'PointwiseAucRoc', 
+           'PointwiseAucPr']

tsadmetrics/metrics/tem/dpm/DelayThresholdedPointadjustedFScore.py

@@ -0,0 +1,83 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise
+
+
+class DelayThresholdedPointadjustedFScore(Metric):
+    """
+    Calculate delay thresholded point-adjusted F-score for anomaly detection in time series.
+
+    This metric is based on the standard F-score, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, for each ground-truth anomalous segment, 
+    if at least one point within the first k time steps of the segment is predicted as anomalous, 
+    all points in the segment are marked as correctly detected. The adjusted predictions are then 
+    compared to the ground-truth labels using the standard point-wise F-score formulation.
+
+    Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
+
+    For more information, see the original paper:
+    https://doi.org/10.1145/3292500.3330680
+
+    Parameters:
+        k (int):
+            Maximum number of time steps from the start of an anomaly segment within which a prediction must occur 
+            for the segment to be considered detected.
+        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 = "dtpaf"
+    binary_prediction = True
+    param_schema = {
+        "k": {
+            "default": 1,
+            "type": int
+        },
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="dtpaf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the delay thresholded point-adjusted 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 computed delay thresholded point-adjusted F-score.
+        """
+
+        adjusted_prediction = y_pred.copy()
+        k = self.params["k"]
+
+        for start, end in full_series_to_segmentwise(y_true):
+            anomaly_adjusted = False
+            for i in range(start, min(start + k, end + 1)):
+                if adjusted_prediction[i] == 1:
+                    adjusted_prediction[start:end + 1] = 1
+                    anomaly_adjusted = True
+                    break
+            if not anomaly_adjusted:
+                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/dpm/LatencySparsityawareFScore.py

@@ -0,0 +1,76 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_latency_sparsity_aware import calc_twseq
+
+class LatencySparsityawareFScore(Metric):
+    """
+    Calculate latency and sparsity aware F-score for anomaly detection in time series.
+    
+    This metric is based on the standard F-score, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, for each ground-truth anomalous segment, 
+    all points in the segment are marked as correctly detected only after the first true positive 
+    is predicted within that segment. This encourages early detection by delaying credit for correct 
+    predictions until the anomaly is initially detected. Additionally, to reduce the impact of 
+    scattered false positives, predictions are subsampled using a sparsity factor n, so that 
+    only one prediction is considered every n time steps. The adjusted predictions are then used 
+    to _compute the standard point-wise F-score.
+
+    Implementation of https://dl.acm.org/doi/10.1145/3447548.3467174
+
+    For more information, see the original paper:
+    https://doi.org/10.1145/3447548.3467174
+
+    Parameters:
+        ni (int):
+            The batch size used in the implementation to handle latency and sparsity.
+        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 = "lsaf"
+    binary_prediction = True
+    param_schema = {
+        "ni": {
+            "default": 1,
+            "type": int
+        },
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="lsaf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the latency and sparsity aware 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 latency and sparsity aware F-score, which is the harmonic mean 
+            of precision and recall, adjusted by the beta value.
+        """
+
+        if np.sum(y_pred) == 0:
+            return 0
+
+        _, precision, recall, _, _, _, _, _ = calc_twseq(
+            y_pred,
+            y_true,
+            normal=0,
+            threshold=0.5,
+            tw=self.params["ni"],
+        )
+
+        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/dpm/MeanTimeToDetect.py

@@ -0,0 +1,47 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise
+
+class MeanTimeToDetect(Metric):
+    """
+    Calculate mean time to detect for anomaly detection in time series.
+    
+    This metric quantifies the average detection delay across all true anomaly events.  
+    For each ground-truth anomaly segment, let i be the index where the segment starts, 
+    and let :math:`{j \geq i}` be the first index within that segment where the model predicts an anomaly.  
+    The detection delay for that event is defined as:
+
+    .. math::
+        \Delta t = j - i
+
+    The MTTD is the mean of all such :math:`{\Delta t}` values, one per true anomaly segment, and expresses 
+    the average number of time steps between the true onset of an anomaly and its first detection.
+    """
+    name = "mttd"
+    binary_prediction = True
+    def __init__(self, **kwargs):
+        super().__init__(name="mttd", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the mean time to detect.
+
+        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 mean time to detect.
+        """
+
+        a_events = full_series_to_segmentwise(y_true)
+        t_sum = 0
+        for a, _ in a_events:
+            for i in range(a, len(y_pred)):
+                if y_pred[i] == 1:
+                    t_sum += i - a
+                    break
+
+        return t_sum / len(a_events)

tsadmetrics/metrics/tem/dpm/NabScore.py

@@ -0,0 +1,60 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_pointwise
+from ....utils.functions_nabscore import Sweeper, calculate_scores
+
+class NabScore(Metric):
+    """
+    Calculate NAB score for anomaly detection in time series.
+
+    This metric rewards early and accurate detections of anomalies while penalizing false positives. 
+    For each ground truth anomaly segment, only the first correctly predicted anomaly point contributes 
+    positively to the score, with earlier detections receiving higher rewards. In contrast, every false 
+    positive prediction contributes negatively.
+
+    Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
+    
+    For more information, see the original paper:
+    https://doi.org/10.1109/ICMLA.2015.141
+    """
+    name = "nab_score"
+    binary_prediction = True
+    def __init__(self, **kwargs):
+        super().__init__(name="nab_score", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the NAB 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 computed NAB score.
+        """
+        sweeper = Sweeper(probationPercent=0, costMatrix={"tpWeight": 1, "fpWeight": 0.11, "fnWeight": 1})
+
+        if len(full_series_to_pointwise(y_pred)) == 0:
+            return 0
+        if len(full_series_to_pointwise(y_true)) == 0:
+            return np.nan
+
+        try:
+            sweeper, null_score, raw_score = calculate_scores(
+                sweeper,
+                full_series_to_pointwise(y_true),
+                full_series_to_pointwise(y_pred),
+                len(y_true)
+            )
+            sweeper, null_score, perfect_score = calculate_scores(
+                sweeper,
+                full_series_to_pointwise(y_true),
+                full_series_to_pointwise(y_true),
+                len(y_true)
+            )
+            return (raw_score - null_score) / (perfect_score - null_score) * 100
+        except Exception:
+            return 0

tsadmetrics/metrics/tem/dpm/__init__.py

@@ -0,0 +1,11 @@
+from .DelayThresholdedPointadjustedFScore import DelayThresholdedPointadjustedFScore
+from .LatencySparsityawareFScore import LatencySparsityawareFScore
+from .MeanTimeToDetect import MeanTimeToDetect
+from .NabScore import NabScore
+
+__all__ = [
+    "DelayThresholdedPointadjustedFScore",
+    "LatencySparsityawareFScore",
+    "MeanTimeToDetect",
+    "NabScore"
+]

tsadmetrics/metrics/tem/ptdm/AverageDetectionCount.py

@@ -0,0 +1,53 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise, full_series_to_pointwise
+
+class AverageDetectionCount(Metric):
+    """
+    Calculate average detection count for anomaly detection in time series.
+
+    This metric computes, for each ground-truth anomalous segment, the percentage of points within that segment 
+    that are predicted as anomalous. It then averages these percentages across all true anomaly events, 
+    providing an estimate of detection coverage per event.
+
+    For more information, see the original paper:
+    https://ceur-ws.org/Vol-1226/paper31.pdf
+
+    Parameters:
+        None
+    """
+
+    name = "adc"
+    binary_prediction = True
+    param_schema = {}  
+
+    def __init__(self, **kwargs):
+        super().__init__(name="adc", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the average detection count.
+
+        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 average detection count score.
+        """
+
+        
+        azs = full_series_to_segmentwise(y_true)
+        a_points = full_series_to_pointwise(y_pred)
+
+        counts = []
+        for az in azs:
+            count = 0
+            for ap in a_points:
+                if ap >= az[0] and ap <= az[1]:
+                    count+=1
+            counts.append(count/(az[1] - az[0] + 1))  # Normalize by segment length
+        
+        return np.mean(counts)