tsadmetrics 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

tsadmetrics/binary_metrics.py

@@ -9,6 +9,8 @@ from pate.PATE_metric import PATE
 def point_wise_recall(y_true: np.array, y_pred: np.array):
     """
     Calculate point-wise recall for anomaly detection in time series.
+    Esta métrica consiste en el recall clásico, sin tener en cuenta el contexto
+    temporal.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -21,7 +23,6 @@ def point_wise_recall(y_true: np.array, y_pred: np.array):
     m = Pointwise_metrics(len(y_true),y_true,y_pred)
     m.set_confusion()
     TP,FN = m.tp,m.fn
-    #TP, _, FP, FN = get_tp_tn_fp_fn_point_wise(y_true, y_pred)
     if TP == 0:
         return 0
     return TP / (TP + FN)
@@ -29,6 +30,8 @@ def point_wise_recall(y_true: np.array, y_pred: np.array):
 def point_wise_precision(y_true: np.array, y_pred: np.array):
     """
     Calculate point-wise precision for anomaly detection in time series.
+    Esta métrica consiste en la precisión clásica, sin tener en cuenta el contexto
+    temporal.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -38,7 +41,6 @@ def point_wise_precision(y_true: np.array, y_pred: np.array):
     Returns:
     float: The point-wise precision score, which is the ratio of true positives to the sum of true positives and false positives.
     """
-    #TP, _, FP, FN = get_tp_tn_fp_fn_point_wise(y_true, y_pred)
     m = Pointwise_metrics(len(y_true),y_true,y_pred)
     m.set_confusion()
     TP,FP = m.tp,m.fp
@@ -49,6 +51,8 @@ def point_wise_precision(y_true: np.array, y_pred: np.array):
 def point_wise_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     Calculate point-wise F-score for anomaly detection in time series.
+    Esta métrica consiste en la F-score clásica, sin tener en cuenta el contexto
+    temporal.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -71,7 +75,12 @@ def point_wise_f_score(y_true: np.array, y_pred: np.array, beta=1):
 
 def point_adjusted_recall(y_true: np.array, y_pred: np.array):
     """
-    Calculate point-adjusted recall for anomaly detection in time series.
+    This metric is based on the standard recall 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 that 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 recall formulation.
+ 
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -84,7 +93,6 @@ def point_adjusted_recall(y_true: np.array, y_pred: np.array):
     if np.sum(y_pred) == 0:
         return 0
     m = PointAdjust(len(y_true),y_true,y_pred)
-    #m.adjust()
     TP,FN = m.tp,m.fn
     if TP == 0:
         return 0
@@ -93,6 +101,11 @@ def point_adjusted_recall(y_true: np.array, y_pred: np.array):
 def point_adjusted_precision(y_true: np.array, y_pred: np.array):
     """
     Calculate point-adjusted precision for anomaly detection in time series.
+    This metric is based on the standard precision 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 that 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 precision formulation.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -105,7 +118,6 @@ def point_adjusted_precision(y_true: np.array, y_pred: np.array):
     if np.sum(y_pred) == 0:
         return 0
     m = PointAdjust(len(y_true),y_true,y_pred)
-    #m.adjust()
     TP,FP = m.tp,m.fp
     if TP == 0:
         return 0
@@ -114,6 +126,11 @@ def point_adjusted_precision(y_true: np.array, y_pred: np.array):
 def point_adjusted_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     Calculate 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 that 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
 
     Parameters:
@@ -138,12 +155,17 @@ def point_adjusted_f_score(y_true: np.array, y_pred: np.array, beta=1):
 def delay_th_point_adjusted_recall(y_true: np.array, y_pred: np.array, k: int):
     """
     Calculate delay thresholded point-adjusted recall for anomaly detection in time series.
+    This metric is based on the standard recall 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 
+    used to compute the standard point-wise recall formulation.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     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.
-    k (int): The maximum number of time steps within which an anomaly must be predicted to be considered detected.
+    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.
 
     Returns:
     float: The delay thresholded point-adjusted recall score, which is the ratio of true positives to the sum of true positives and false negatives.
@@ -159,12 +181,17 @@ def delay_th_point_adjusted_recall(y_true: np.array, y_pred: np.array, k: int):
 def delay_th_point_adjusted_precision(y_true: np.array, y_pred: np.array, k: int):
     """
     Calculate delay thresholded point-adjusted precision for anomaly detection in time series.
+    This metric is based on the standard precision 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 
+    used to compute the standard point-wise precision fromulation.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     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.
-    k (int): The maximum number of time steps within which an anomaly must be predicted to be considered detected.
+    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.
 
     Returns:
     float: The delay thresholded point-adjusted precision score, which is the ratio of true positives to the sum of true positives and false positives.
@@ -180,12 +207,18 @@ def delay_th_point_adjusted_precision(y_true: np.array, y_pred: np.array, k: int
 def delay_th_point_adjusted_f_score(y_true: np.array, y_pred: np.array, k: int, beta=1):
     """
     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 
+    used to compute the standard point-wise F-Score formulation.
+    
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     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.
-    k (int): The maximum number of time steps within which an anomaly must be predicted to be considered detected.
+    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.
 
@@ -204,6 +237,12 @@ def delay_th_point_adjusted_f_score(y_true: np.array, y_pred: np.array, k: int,
 def point_adjusted_at_k_recall(y_true: np.array, y_pred: np.array, k: float):
     """
     Calculate k percent point-adjusted at K% recall for anomaly detection in time series.
+    This metric is based on the standard recall 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. Otherwise, the entire segment is treated as 
+    missed, even if some points were correctly predicted. The adjusted predictions are then used 
+    to compute the standard point-wise recall.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -224,6 +263,12 @@ def point_adjusted_at_k_recall(y_true: np.array, y_pred: np.array, k: float):
 def point_adjusted_at_k_precision(y_true: np.array, y_pred: np.array, k: float):
     """
     Calculate point-adjusted at K% precision for anomaly detection in time series.
+    This metric is based on the standard precision 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. Otherwise, the entire segment is treated as 
+    missed, even if some points were correctly predicted. The adjusted predictions are then used 
+    to compute the standard point-wise precision.
     Implementation of https://link.springer.com/article/10.1007/s10618-023-00988-8
 
     Parameters:
@@ -234,7 +279,6 @@ def point_adjusted_at_k_precision(y_true: np.array, y_pred: np.array, k: float):
     Returns:
     float: The point-adjusted precision score, which is the ratio of true positives to the sum of true positives and false positives.
     """
-    #TP, _, FP, _ = get_tp_tn_fp_fn_point_adjusted_at_k(y_true, y_pred, k)
     m = PointAdjustKPercent(len(y_true),y_true,y_pred,k=k)
     TP,FP = m.tp,m.fp
     if TP == 0:
@@ -244,6 +288,12 @@ def point_adjusted_at_k_precision(y_true: np.array, y_pred: np.array, k: float):
 def point_adjusted_at_k_f_score(y_true: np.array, y_pred: np.array, k: float, beta=1):
     """
     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. Otherwise, the entire segment is treated as 
+    missed, even if some points were correctly predicted. 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
 
     Parameters:
@@ -268,6 +318,14 @@ def point_adjusted_at_k_f_score(y_true: np.array, y_pred: np.array, k: float, be
 def latency_sparsity_aw_recall(y_true: np.array, y_pred: np.array, ni: int):
     """
     Calculate latency and sparsity aware recall for anomaly detection in time series.
+    This metric is based on the standard recall, 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 recall.
     Implementation of https://dl.acm.org/doi/10.1145/3447548.3467174
 
     Parameters:
@@ -289,6 +347,14 @@ def latency_sparsity_aw_recall(y_true: np.array, y_pred: np.array, ni: int):
 def latency_sparsity_aw_precision(y_true: np.array, y_pred: np.array, ni: int):
     """
     Calculate latency and sparsity aware precision for anomaly detection in time series.
+    This metric is based on the standard precision, 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 precision.
     Implementation of https://dl.acm.org/doi/10.1145/3447548.3467174
 
     Parameters:
@@ -310,6 +376,15 @@ def latency_sparsity_aw_precision(y_true: np.array, y_pred: np.array, ni: int):
 def latency_sparsity_aw_f_score(y_true: np.array, y_pred: np.array, ni: int, beta=1):
     """
     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
 
     Parameters:
@@ -335,6 +410,14 @@ def latency_sparsity_aw_f_score(y_true: np.array, y_pred: np.array, ni: int, bet
 def segment_wise_recall(y_true: np.array, y_pred: np.array):
     """
     Calculate segment-wise recall for anomaly detection in time series.
+    This metric is based on the standard recall, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, each contiguous segment of anomalous points 
+    is treated as a single unit. A true positive is counted if at least one point in a ground-truth 
+    anomalous segment is predicted as anomalous. A false negative is counted if no point in the segment 
+    is detected, and a false positive is recorded for each predicted anomalous segment that does not 
+    overlap with any ground-truth anomaly. The final recall is computed using these adjusted 
+    segment-level counts.
+
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -344,7 +427,6 @@ def segment_wise_recall(y_true: np.array, y_pred: np.array):
     Returns:
     float: The segment-wise recall score, which is the ratio of true positives to the sum of true positives and false negatives.
     """
-    #TP, _, FN = get_tp_fp_fn_segment_wise(y_true, y_pred)
     m = Segmentwise_metrics(len(y_true),y_true,y_pred)
     TP,FN = m.tp,m.fn
     if TP == 0:
@@ -354,6 +436,13 @@ def segment_wise_recall(y_true: np.array, y_pred: np.array):
 def segment_wise_precision(y_true: np.array, y_pred: np.array):
     """
     Calculate segment-wise precision for anomaly detection in time series.
+    This metric is based on the standard precision, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, each contiguous segment of anomalous points 
+    is treated as a single unit. A true positive is counted if at least one point in a ground-truth 
+    anomalous segment is predicted as anomalous. A false negative is counted if no point in the segment 
+    is detected, and a false positive is recorded for each predicted anomalous segment that does not 
+    overlap with any ground-truth anomaly. The final precision is computed using these adjusted 
+    segment-level counts.
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -363,7 +452,6 @@ def segment_wise_precision(y_true: np.array, y_pred: np.array):
     Returns:
     float: The segment-wise precision score, which is the ratio of true positives to the sum of true positives and false positives.
     """
-    #TP, FP, _ = get_tp_fp_fn_segment_wise(y_true, y_pred)
     m = Segmentwise_metrics(len(y_true),y_true,y_pred)
     TP,FP = m.tp,m.fp
     if TP == 0:
@@ -373,6 +461,13 @@ def segment_wise_precision(y_true: np.array, y_pred: np.array):
 def segment_wise_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     Calculate segment-wise 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, each contiguous segment of anomalous points 
+    is treated as a single unit. A true positive is counted if at least one point in a ground-truth 
+    anomalous segment is predicted as anomalous. A false negative is counted if no point in the segment 
+    is detected, and a false positive is recorded for each predicted anomalous segment that does not 
+    overlap with any ground-truth anomaly. The final F-score is computed using these adjusted 
+    segment-level counts.
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -400,24 +495,32 @@ def segment_wise_f_score(y_true: np.array, y_pred: np.array, beta=1):
 def composite_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     Calculate composite F-score for anomaly detection in time series.
+    This metric combines aspects of the point_wise_f_score and the segment_wise_f_score. 
+    It is defined as the harmonic mean of point_wise_precision and segment_wise_recall. 
+    The use of point-wise precision ensures that false positives are properly penalized, 
+    a feature that segment-wise metrics typically lack.
+
     Implementation of https://ieeexplore.ieee.org/document/9525836
 
     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.
-    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.
+        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.
+        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.
 
     Returns:
-    float: The composite F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+        float: The composite F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
   
     """
     m = Composite_f(len(y_true),y_true,y_pred)
     #Point wise precision
-    precision =  m.precision()#point_wise_precision(y_true,y_pred)
+    precision =  m.precision()
 
     #Segment wise recall
-    recall = m.recall()#segment_wise_recall(y_true,y_pred)
+    recall = m.recall()
 
     if precision==0 or recall==0:
         return 0
@@ -427,6 +530,12 @@ def composite_f_score(y_true: np.array, y_pred: np.array, beta=1):
 def time_tolerant_recall(y_true: np.array, y_pred: np.array, t: int) -> float:
     """
     Calculate time tolerant recall for anomaly detection in time series.
+    This metric is based on the standard recall, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, a predicted anomalous point is considered 
+    a true positive if it lies within a temporal window of size τ around any ground-truth anomalous point. 
+    This allows for small temporal deviations in the predictions to be tolerated. The adjusted predictions are then used 
+    to compute the standard point-wise recall.
+
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -446,6 +555,12 @@ def time_tolerant_recall(y_true: np.array, y_pred: np.array, t: int) -> float:
 def time_tolerant_precision(y_true: np.array, y_pred: np.array, t: int) -> float:
     """
     Calculate time tolerant precision for anomaly detection in time series.
+    This metric is based on the standard precision, but applies a temporal adjustment 
+    to the predictions before computing it. Specifically, a predicted anomalous point is considered 
+    a true positive if it lies within a temporal window of size τ around any ground-truth anomalous point. 
+    This allows for small temporal deviations in the predictions to be tolerated. The adjusted predictions are then used 
+    to compute the standard point-wise precision.
+
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -462,9 +577,15 @@ def time_tolerant_precision(y_true: np.array, y_pred: np.array, t: int) -> float
     return m.precision()
 
 
-def time_tolerant_f_score(y_true: np.array, y_pred: np.array,t: int, beta=1):
+def time_tolerant_f_score(y_true: np.array, y_pred: np.array, t: int, beta=1):
     """
     Calculate time tolerant 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, a predicted anomalous point is considered 
+    a true positive if it lies within a temporal window of size τ around any ground-truth anomalous point. 
+    This allows for small temporal deviations in the predictions to be tolerated.The adjusted predictions are then used 
+    to compute the standard point-wise F-Score.
+
     Implementation of https://arxiv.org/pdf/1802.04431
 
     Parameters:
@@ -488,13 +609,23 @@ def time_tolerant_f_score(y_true: np.array, y_pred: np.array,t: int, beta=1):
 def range_based_recall(y_true: np.array, y_pred: np.array, alpha: float, bias='flat', cardinality_mode='one'):
     """
     Calculate range-based recall for anomaly detection in time series.
-    
+
+    This metric extends standard recall by evaluating detection at the level of anomalous ranges 
+    rather than individual points.  For each true anomaly range, it computes a score that rewards 
+    (1) detecting the existence of the range, (2) the proportion of overlap, and (3) penalties or 
+    bonuses based on the position and fragmentation of predicted segments.  These components are 
+    weighted by α (existence vs. overlap) and further shaped by customizable bias functions 
+    for positional and cardinality factors.
+
+    For more information, see the original paper:
+    https://proceedings.neurips.cc/paper_files/paper/2018/file/8f468c873a32bb0619eaeb2050ba45d1-Paper.pdf
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    bias (str): The type of bias to apply for weighting (flat, front-end, back-end, middle).
-    cardinality (str, optional): ["one", "reciprocal", "udf_gamma"]. Defaults to "one".
+    alpha (float): Relative importance of existence reward. 0 ≤ alpha ≤ 1.
+    bias (str): Positional bias. This should be "flat", "front", "middle", or "back".
+    cardinality_mode (str, optional): Cardinality type. This should be "one", "reciprocal" or "udf_gamma".
     
     Returns:
     float: The range-based recall score.
@@ -509,13 +640,21 @@ def range_based_recall(y_true: np.array, y_pred: np.array, alpha: float, bias='f
 def range_based_precision(y_true: np.array, y_pred: np.array, alpha: float, bias='flat', cardinality_mode='one'):
     """
     Calculate range-based precision for anomaly detection in time series.
+
+    This metric extends standard precision by scoring predictions at the range level.  Each 
+    predicted anomaly range is evaluated for (1) overlap with any true ranges, (2) the size of 
+    that overlap, and (3) positional and fragmentation effects via bias functions.  Cardinality 
+    penalties can be applied when a single true range is covered by multiple predicted ranges.
+
+    For more information, see the original paper:
+    https://proceedings.neurips.cc/paper_files/paper/2018/file/8f468c873a32bb0619eaeb2050ba45d1-Paper.pdf
     
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    bias (str): The type of bias to apply for weighting (flat, front-end, back-end, middle).
-    cardinality (str, optional): ["one", "reciprocal", "udf_gamma"]. Defaults to "one".
+    alpha (float): Relative importance of existence reward. 0 ≤ alpha ≤ 1.
+    bias (str): Positional bias. This should be "flat", "front", "middle", or "back".
+    cardinality_mode (str, optional): Cardinality type. This should be "one", "reciprocal" or "udf_gamma".
     
     Returns:
     float: The range-based precision score.
@@ -534,15 +673,22 @@ def range_based_f_score(y_true: np.array, y_pred: np.array, p_alpha: float, r_al
     """
     Calculate range-based F-score for anomaly detection in time series.
 
+    This metric combines range-based precision and range-based recall into a single harmonic mean.  
+    It inherits all customizability of the underlying precision and recall—existence vs. overlap 
+    weighting, positional bias, and cardinality factors—allowing fine-grained control over how 
+    both missed detections and false alarms are penalized in a temporal context.
+
+    For more information, see the original paper:
+    https://proceedings.neurips.cc/paper_files/paper/2018/file/8f468c873a32bb0619eaeb2050ba45d1-Paper.pdf
+    
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    p_bias: string, default="flat"
-            Positional bias for precision. This should be "flat", "front", "middle", or "back"
-    r_bias: string, default="flat"
-        Positional bias for recall. This should be "flat", "front", "middle", or "back"
-    cardinality_mode (str, optional): ["one", "reciprocal", "udf_gamma"]. Defaults to "one".
+    alpha (float): Relative importance of existence reward. 0 ≤ alpha ≤ 1.
+    p_bias (str): Positional bias for precision. This should be "flat", "front", "middle", or "back".
+    r_bias (str): Positional bias for recall. This should be "flat", "front", "middle", or "back".
+    cardinality_mode (str, optional): Cardinality type. This should be "one", "reciprocal" or "udf_gamma".
     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.
 
@@ -561,11 +707,27 @@ def ts_aware_recall(y_true: np.array, y_pred: np.array, alpha: float, delta: flo
     """
     Calculate time series aware recall for anomaly detection in time series.
     
+    This metric is based on the range_based_recall, but introduces two key modifications.  
+    First, a predicted anomalous segment is only counted as a true positive if it covers at least a fraction 
+    θ of the ground‑truth anomaly range. Second, each labeled anomaly is extended by a tolerance window of 
+    length δ at its end, within which any overlap contribution decays linearly from full weight down to zero.  
+    Unlike the original range-based formulation, this variant omits cardinality and positional bias terms, 
+    focusing solely on overlap fraction and end‑tolerance decay.
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    past_range: Determines if the range is considered in the past or future as specified in https://www.mdpi.com/2079-9292/11/8/1213
+    alpha (float): Relative importance of the existence reward versus overlap reward (0 ≤ α ≤ 1).
+    delta (float): Tolerance window length at the end of each true anomaly segment.
+        - If past_range is True, δ must be a float in (0, 1], representing the fraction of the segment’s 
+            length to extend. E.g., δ = 0.5 extends a segment of length 10 by 5 time steps.
+        - If past_range is False, δ must be a non-negative integer, representing an absolute number of 
+            time steps to extend each segment.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of the true anomaly range that must be overlapped by 
+        predictions for the segment to count as detected.
+    past_range (bool): Determines how δ is interpreted.
+        - True: δ is treated as a fractional extension of each segment’s length.
+        - False: δ is treated as an absolute number of time steps.
     
     Returns:
     float: The time series aware recall score.
@@ -579,12 +741,28 @@ def ts_aware_recall(y_true: np.array, y_pred: np.array, alpha: float, delta: flo
 def ts_aware_precision(y_true: np.array, y_pred: np.array,alpha: float, delta: float, theta: float, past_range: bool = False):
     """
     Calculate time series aware precision for anomaly detection in time series.
+
+    This metric is based on the range_based_precision, but introduces two key modifications.  
+    First, a predicted anomalous segment is only counted as a true positive if it covers at least a fraction 
+    θ of the ground‑truth anomaly range. Second, each labeled anomaly is extended by a tolerance window of 
+    length δ at its end, within which any overlap contribution decays linearly from full weight down to zero.  
+    Unlike the original range-based formulation, this variant omits cardinality and positional bias terms, 
+    focusing solely on overlap fraction and end‑tolerance decay.
     
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    past_range: Determines if the range is considered in the past or future as specified in https://www.mdpi.com/2079-9292/11/8/1213
+    alpha (float): Relative importance of the existence reward versus overlap reward (0 ≤ α ≤ 1).
+    delta (float): Tolerance window length at the end of each true anomaly segment.
+        - If past_range is True, δ must be a float in (0, 1], representing the fraction of the segment’s 
+            length to extend. E.g., δ = 0.5 extends a segment of length 10 by 5 time steps.
+        - If past_range is False, δ must be a non-negative integer, representing an absolute number of 
+            time steps to extend each segment.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of the true anomaly range that must be overlapped by 
+        predictions for the segment to count as detected.
+    past_range (bool): Determines how δ is interpreted.
+        - True: δ is treated as a fractional extension of each segment’s length.
+        - False: δ is treated as an absolute number of time steps.
     
     Returns:
     float: The time series aware precision score.
@@ -600,13 +778,27 @@ def ts_aware_f_score(y_true: np.array, y_pred: np.array, beta: float, alpha: flo
     """
     Calculate time series aware F-score for anomaly detection in time series.
 
+    This metric is based on the range_based_f_score, but introduces two key modifications.  
+    First, a predicted anomalous segment is only counted as a true positive if it covers at least a fraction 
+    θ of the ground‑truth anomaly range. Second, each labeled anomaly is extended by a tolerance window of 
+    length δ at its end, within which any overlap contribution decays linearly from full weight down to zero.  
+    Unlike the original range-based formulation, this variant omits cardinality and positional bias terms, 
+    focusing solely on overlap fraction and end‑tolerance decay.
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
-    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.
-    past_range: Determines if the range is considered in the past or future as specified in https://www.mdpi.com/2079-9292/11/8/1213
+    alpha (float): Relative importance of the existence reward versus overlap reward (0 ≤ α ≤ 1).
+    delta (float): Tolerance window length at the end of each true anomaly segment.
+        - If past_range is True, δ must be a float in (0, 1], representing the fraction of the segment’s 
+            length to extend. E.g., δ = 0.5 extends a segment of length 10 by 5 time steps.
+        - If past_range is False, δ must be a non-negative integer, representing an absolute number of 
+            time steps to extend each segment.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of the true anomaly range that must be overlapped by 
+        predictions for the segment to count as detected.
+    past_range (bool): Determines how δ is interpreted.
+        - True: δ is treated as a fractional extension of each segment’s length.
+        - False: δ is treated as an absolute number of time steps.
 
     Returns:
     float: The time series aware F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
@@ -628,10 +820,17 @@ def enhanced_ts_aware_recall(y_true: np.array, y_pred: np.array, theta: float):
     """
     Calculate enhanced time series aware recall for anomaly detection in time series.
     
+    This metric is similar to the range-based recall in that it accounts for both detection existence 
+    and overlap proportion. Additionally, it requires that a significant fraction θ of each true anomaly 
+    segment be detected, and that a significant fraction γ of each predicted segment overlaps with the 
+    ground truth. Finally, recall contributions from each event are weighted by the square root of the 
+    true segment’s length, providing a compromise between point-wise and segment-wise approaches.
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of a true segment that must be overlapped 
+            by predictions to count as detected.
     
     Returns:
     float: The time series aware recall score.
@@ -648,10 +847,17 @@ def enhanced_ts_aware_precision(y_true: np.array, y_pred: np.array, theta: float
     """
     Calculate enhanced time series aware precision for anomaly detection in time series.
     
+    This metric is similar to the range-based precision in that it accounts for both detection existence 
+    and overlap proportion. Additionally, it requires that a significant fraction θ of each true anomaly 
+    segment be detected, and that a significant fraction γ of each predicted segment overlaps with the 
+    ground truth. Finally, precision contributions from each event are weighted by the square root of the 
+    true segment’s length, providing a compromise between point-wise and segment-wise approaches.
+
     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.
-    alpha (float): A parameter that controls the length of the range considered for true positives.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of a true segment that must be overlapped 
+            by predictions to count as detected.
     
     Returns:
     float: The time series aware precision score.
@@ -665,15 +871,21 @@ def enhanced_ts_aware_precision(y_true: np.array, y_pred: np.array, theta: float
 
 
 
-def enhanced_ts_aware_f_score(y_true: np.array, y_pred: np.array, beta: float, theta_p: float, theta_r: float):
+def enhanced_ts_aware_f_score(y_true: np.array, y_pred: np.array, theta_p: float, theta_r: float):
     """
     Calculate enhanced time series aware F-score for anomaly detection in time series.
+    
+    This metric is similar to the range-based F-score in that it accounts for both detection existence 
+    and overlap proportion. Additionally, it requires that a significant fraction θ of each true anomaly 
+    segment be detected, and that a significant fraction γ of each predicted segment overlaps with the 
+    ground truth. Finally, F-score contributions from each event are weighted by the square root of the 
+    true segment’s length, providing a compromise between point-wise and segment-wise approaches.
 
     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.
-    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.
+    theta (float): Minimum fraction (0 ≤ θ ≤ 1) of a true segment that must be overlapped 
+            by predictions to count as detected.
 
     Returns:
     float: The time series aware F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
@@ -689,14 +901,16 @@ def affiliation_based_recall(y_true: np.array, y_pred: np.array):
     """
     Calculate affiliation based recall for anomaly detection in time series.
 
+    This metric evaluates how well each labeled anomaly is affiliated with predicted points.
+    It computes the average distance from each ground truth anomaly point to the nearest 
+    predicted anomaly point.
+
     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.
-    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.
 
     Returns:
-    float: The time series aware F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+    float: The affiliation based recall score.
     """
     if np.sum(y_pred) == 0:
         return 0
@@ -709,14 +923,17 @@ def affiliation_based_precision(y_true: np.array, y_pred: np.array):
     """
     Calculate affiliation based F-score for anomaly detection in time series.
 
+    This metric evaluates how well each predicted anomaly is affiliated with labeled points.
+    It computes the average distance from each predicted anomaly point to the nearest 
+    ground truth anomaly point.
+
     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.
-    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.
+
 
     Returns:
-    float: The time series aware F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+    float: The affiliation based precision score.
     """
     if np.sum(y_pred) == 0:
         return 0
@@ -729,14 +946,20 @@ def affiliation_based_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     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 β 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.
+
     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.
     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.
+
 
     Returns:
-    float: The time series aware F-score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+    float: The affiliation based F-score.
     """
     if np.sum(y_pred) == 0:
         return 0
@@ -748,13 +971,18 @@ def nab_score(y_true: np.array, y_pred: np.array):
     """
     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.
+
     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 nab score, which is the harmonic mean of precision and recall, adjusted by the beta value.
+    float: The nab score.
     """
     
     m = NAB_score(len(y_true),y_true,y_pred)
@@ -764,6 +992,11 @@ def temporal_distance(y_true: np.array, y_pred: np.array, distance: int = 0):
     """
     Calculate temporal distane for anomaly detection in time series.
 
+    This metric computes the sum of the distances from each labelled anomaly point to
+    the closest predicted anomaly point, and from each predicted anomaly point to the
+    closest labelled anomaly point. 
+
+
     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.
@@ -773,7 +1006,7 @@ def temporal_distance(y_true: np.array, y_pred: np.array, distance: int = 0):
 
 
     Returns:
-    float: The temporal distance, which is the harmonic mean of precision and recall, adjusted by the beta value.
+    float: The temporal distance.
     """
     
     m = Temporal_Distance(len(y_true),y_true,y_pred,distance=distance)
@@ -783,13 +1016,20 @@ def average_detection_count(y_true: np.array, y_pred: np.array):
     """
     Calculate average detection count for anomaly detection in time series.
 
+    This metric computes, for each ground-truth anomalous segment, how many points within that segment 
+    are predicted as anomalous. It then averages these counts 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:
     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.
+    float: The average detection count score.
     """
     
     b = Binary_detection(len(y_true),y_true,y_pred)
@@ -810,10 +1050,17 @@ def absolute_detection_distance(y_true: np.array, y_pred: np.array):
     """
     Calculate absolute detection distance for anomaly detection in time series.
 
+    This metric computes, for each predicted anomaly point that overlaps a ground-truth anomaly segment, 
+    the distance from that point to the temporal center of the corresponding segment. It then sums all 
+    those distances and divides by the total number of such matching predicted points, yielding the 
+    mean distance to segment centers for correctly detected points.
+
     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.
 
+    For more information, see the original paper:
+    https://ceur-ws.org/Vol-1226/paper31.pdf
 
     Returns:
     float: The absolute detection distance.
@@ -837,13 +1084,28 @@ def total_detected_in_range(y_true: np.array, y_pred: np.array, k: int):
     """
     Calculate total detected in range for anomaly detection in time series.
 
+    This metric measures the proportion of true anomaly events that are correctly detected.
+    It is defined as:
+        TDIR = (EM + DA) / (EM + DA + MA)
+
+    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:
     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.
-    k (int): The maximum number of time steps within which an anomaly must be predicted to be considered detected.
+    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.
 
     Returns:
-    float: The total detected in range.
+    float: The total detected in range score.
     """
     if np.sum(y_pred) == 0:
         return 0
@@ -857,10 +1119,25 @@ def detection_accuracy_in_range(y_true: np.array, y_pred: np.array, k: int):
     """
     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:
+        DAIR = (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:
     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.
-    k (int): The maximum number of time steps within which an anomaly must be predicted to be considered detected.
+    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.
 
     Returns:
     float: The total detected in range.
@@ -876,7 +1153,28 @@ def detection_accuracy_in_range(y_true: np.array, y_pred: np.array, k: int):
 def weighted_detection_difference(y_true: np.array, y_pred: np.array, k: int):
     """
     Calculate weighted detection difference for anomaly detection in time series.
-    The weighted detection difference is the difference between the number of true positives and the number of false positives, weighted by the number of true positives.
+
+    For each true anomaly segment, each point in the segment is assigned a weight based on a
+    Gaussian function centered at the segment’s midpoint: points closer to the center receive higher
+    weights, which decay with distance according to the standard deviation sigma. These weights form
+    the basis for scoring both correct detections and false alarms.
+
+    WS (Weighted Sum) is defined as the sum of Gaussian weights for all predicted anomaly points that
+    fall within any true anomaly segment (extended by delta time steps at the ends).
+    WF (False Alarm Weight) is the sum of Gaussian weights for all predicted anomaly points that do
+    not overlap any true anomaly segment (within the same extension).
+
+    The final score is:
+        WDD = WS - WF*FA
+
+    Where:
+        WS = Σ weights_true_predictions
+        WF = Σ weights_false_positives
+        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:
     y_true (np.array): The ground truth binary labels for the time series data.
@@ -923,7 +1221,17 @@ def weighted_detection_difference(y_true: np.array, y_pred: np.array, k: int):
 def binary_pate(y_true: np.array, y_pred: np.array, early: int, delay: int):
     """
     Calculate PATE score for anomaly detection in time series.
-    The PATE score is the ratio of the number of true positives to the sum of true positives, false positives, and false negatives, within a given early and delay range.
+    
+    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.
+
+    For more information, see the original paper:
+    https://arxiv.org/abs/2405.12096
 
     Parameters:
     y_true (np.array): The ground truth binary labels for the time series data.
@@ -940,12 +1248,22 @@ def binary_pate(y_true: np.array, y_pred: np.array, early: int, delay: int):
 def mean_time_to_detect(y_true: np.array, y_pred: np.array):
     """
     Calculate mean time to detect for anomaly detection in time series.
-    The mean time to detect is the average number of time steps between the ground truth anomaly and the predicted anomaly.
+    
+    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 j ≥ i be the first index within that segment where the model predicts an anomaly.  
+    The detection delay for that event is defined as:
+        Δ = j - i
+    The MTTD is the mean of all such Δ 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.
 
     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.
 
+    For more information, see the original paper:
+    https://arxiv.org/pdf/2211.05244
+
     Returns:
     float: The mean time to detect.
     """
@@ -953,10 +1271,10 @@ def mean_time_to_detect(y_true: np.array, y_pred: np.array):
     b = Binary_detection(len(y_true),y_true,y_pred)
     a_events = b.get_gt_anomalies_segmentwise()
     t_sum = 0
-    for _,b in a_events:
-        for i in range(b,len(y_pred)):
+    for a,_ in a_events:
+        for i in range(a,len(y_pred)):
             if y_pred[i] == 1:
-                t_sum+=i-b
+                t_sum+=i-a
                 break
     
     return t_sum/len(a_events)