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

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)

tsadmetrics/metrics/tem/ptdm/DetectionAccuracyInRange.py

@@ -0,0 +1,66 @@
+from ....base.Metric import Metric
+from ....utils.functions_counting_metrics import counting_method
+import numpy as np
+
+class DetectionAccuracyInRange(Metric):
+    """
+    Calculate detection accuracy in range for anomaly detection in time series.
+
+    This metric measures the proportion of predicted anomaly events that correspond to true anomalies.
+    It is defined as:
+
+    .. math::
+        \\text{DAIR} = \\frac{EM + DA}{EM + DA + FA}
+
+    Where:
+
+    - EM (Exact Match):
+        Number of predicted anomaly segments that exactly match a true anomaly segment.
+    - DA (Detected Anomaly):
+        Number of true anomaly points not exactly matched where at least one prediction falls
+        within a window [i-k, i+k] around the true point index i or within the true segment range.
+    - FA (False Anomaly):
+        Number of predicted anomaly segments that do not overlap any true anomaly segment
+        even within a k-step tolerance window around true points.
+
+    For more information, see the original paper:
+    https://acta.sapientia.ro/content/docs/evaluation-metrics-for-anomaly-detection.pdf
+
+    Parameters:
+        k (int):
+            Half-window size for tolerance around each true anomaly point. A prediction within k
+            time steps of a true point counts toward detection.
+    """
+    name = "dair"
+    binary_prediction = True
+    param_schema = {
+        "k": {
+            "default": 5,
+            "type": int
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="dair", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate detection accuracy in range for anomaly detection in time series.
+
+        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 detection accuracy in range score.
+        """
+
+        if np.sum(y_pred) == 0:
+            return 0
+
+        k = self.params["k"]
+        em, da, _, fa = counting_method(y_true, y_pred, k)
+
+        return (em + da) / (em + da + fa)

tsadmetrics/metrics/tem/ptdm/PointadjustedAtKFScore.py

@@ -0,0 +1,80 @@
+from ....base.Metric import Metric
+import numpy as np
+from ....utils.functions_conversion import full_series_to_segmentwise, full_series_to_pointwise, pointwise_to_full_series
+
+class PointadjustedAtKFScore(Metric):
+    """
+    Calculate point-adjusted at K% 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 K% of the points within that segment are predicted as anomalous, all points in 
+    the segment are marked as correctly detected. The adjusted predictions are then used 
+    to _compute the standard F-Score precision.
+
+    Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
+    
+    For more information, see the original paper:
+    https://ojs.aaai.org/index.php/AAAI/article/view/20680
+
+    Parameters:
+        k (float):
+            The minimum percentage of the anomaly that must be detected to consider the anomaly as 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 = "pakf"
+    binary_prediction = True
+    param_schema = {
+        "k": {
+            "default": 0.5,
+            "type": float
+        },
+        "beta": {
+            "default": 1.0,
+            "type": float
+        }
+    }
+
+    def __init__(self, **kwargs):
+        super().__init__(name="pakf", **kwargs)
+
+    def _compute(self, y_true, y_pred):
+        """
+        Calculate the point-adjusted at K% 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 point-adjusted at k F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+        """
+
+        adjusted_prediction = full_series_to_pointwise(y_pred).tolist()
+        for start, end in full_series_to_segmentwise(y_true):
+            correct_points = 0
+            for i in range(start, end + 1):
+                if i in adjusted_prediction:
+                    correct_points += 1
+                    if correct_points / (end + 1 - start) >= self.params['k']:
+                        for j in range(start, end + 1):
+                            adjusted_prediction.append(j)
+                        break
+
+        adjusted_prediction = pointwise_to_full_series(np.sort(np.unique(adjusted_prediction)), len(y_true))
+        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)