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

docs/conf.py

@@ -0,0 +1,43 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+
+project = 'TSADmetrics'
+copyright = '2025, Pedro Rafael Velasco Priego'
+author = 'Pedro Rafael Velasco Priego'
+release = 'MIT'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon'
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+epub_show_urls = 'footnote'
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

tests/test_binary.py

@@ -454,19 +454,19 @@ class TestEnhancedTSAwareMetrics(unittest.TestCase):
         """
         Prueba para la función ts_aware_f_score.
         """
-        f_score = round(enhanced_ts_aware_f_score(self.y_true1, self.y_pred1,1, 0.5, 0.1),2)
+        f_score = round(enhanced_ts_aware_f_score(self.y_true1, self.y_pred1, 0.5, 0.1),2)
         expected_f_score = 0.67
         self.assertAlmostEqual(f_score, expected_f_score, places=4)
 
-        f_score = round(enhanced_ts_aware_f_score(self.y_true1, self.y_pred2,1, 0.5, 0.1),2)
+        f_score = round(enhanced_ts_aware_f_score(self.y_true1, self.y_pred2, 0.5, 0.1),2)
         expected_f_score = 0.72
         self.assertAlmostEqual(f_score, expected_f_score, places=4)
 
-        f_score = round(enhanced_ts_aware_f_score(self.y_true2, self.y_pred21,1, 0.5, 0.1),2)
+        f_score = round(enhanced_ts_aware_f_score(self.y_true2, self.y_pred21, 0.5, 0.1),2)
         expected_f_score = 0.77
         self.assertAlmostEqual(f_score, expected_f_score, places=4)
 
-        f_score = round(enhanced_ts_aware_f_score(self.y_true2, self.y_pred22,1, 0.5, 0.1),2)
+        f_score = round(enhanced_ts_aware_f_score(self.y_true2, self.y_pred22, 0.5, 0.1),2)
         expected_f_score = 0.67
         self.assertAlmostEqual(f_score, expected_f_score, places=4)
         
@@ -474,12 +474,12 @@ class TestEnhancedTSAwareMetrics(unittest.TestCase):
         try:
             y_true = np.random.choice([0, 1], size=(100,))
             y_pred = np.zeros(100)
-            enhanced_ts_aware_f_score(y_true, y_pred, 1, random.random(), random.random())
+            enhanced_ts_aware_f_score(y_true, y_pred, random.random(), random.random())
             for _ in range(100):
                 y_true = np.random.choice([0, 1], size=(100,))
                 y_pred = np.random.choice([0, 1], size=(100,))
 
-                f_score = enhanced_ts_aware_f_score(y_true, y_pred, 1, random.random(), random.random())
+                f_score = enhanced_ts_aware_f_score(y_true, y_pred, random.random(), random.random())
         except Exception as e:
             self.fail(f"enhanced_ts_aware_f_score raised an exception {e}")
 

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,6 +495,11 @@ 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:
@@ -414,10 +514,10 @@ def composite_f_score(y_true: np.array, y_pred: np.array, beta=1):
     """
     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 +527,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 +552,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 +574,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 +606,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 +637,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 +670,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 +704,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 +738,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 +775,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 +817,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 +844,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 +868,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 +898,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 +920,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 +943,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 +968,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 +989,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 +1003,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 +1013,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 +1047,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 +1081,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 +1116,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 +1150,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 +1218,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 +1245,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 +1268,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)

tsadmetrics/metric_utils.py

@@ -262,16 +262,29 @@ def transform_to_full_series(length: int, anomalies: np.array):
 
 def counting_method(y_true: np.array, y_pred: np.array, k: int):
     em,da,ma,fa = 0,0,0,0
-    for gt,pa in zip(y_true,y_pred):
+    for i_gt in range(len(y_true)):
+        i_pa = i_gt
+        gt = y_true[i_gt]
+        pa = y_pred[i_pa]
         if gt==1 and pa==1:
             em+=1
         elif gt==0 and pa==1:
             fa+=1
-        else:
+        elif gt==1 and pa==0:
+            anom_range = y_pred[i_gt-k:i_pa+k+1]
+            detected = False
+            for r in anom_range:
+                if r==1:
+                    em+=1
+                    detected=True
+                    break
+            if not detected:
+                ma+=1
+        elif gt==0 and pa==0:
             pass
-    b = DelayThresholdedPointAdjust(len(y_true),y_true,y_pred,k=k)
-    da = b.tp-em
-    ma = b.fn
+    # b = DelayThresholdedPointAdjust(len(y_true),y_true,y_pred,k=k)
+    # da = b.tp-em
+    # ma = b.fn
 
     return em,da,ma,fa
 

tsadmetrics/non_binary_metrics.py

@@ -1,16 +1,42 @@
 import numpy as np
 from ._tsadeval.metrics import *
-from .metric_utils import transform_to_full_series
 from sklearn.metrics import auc
-from .binary_metrics import point_adjusted_precision, point_adjusted_recall, segment_wise_precision, segment_wise_recall
 from pate.PATE_metric import PATE
-def precision_at_k(y_true : np.array ,y_anomaly_scores:  np.array):
-    
+def precision_at_k(y_true : np.array, y_anomaly_scores:  np.array):
+    """
+    Calculate the precision at k score for anomaly detection in time series.
+
+    This metric evaluates how many of the top-k points (with highest anomaly scores)
+    actually correspond to true anomalies. It is particularly useful when we are 
+    interested in identifying the most anomalous points, without needing to set a 
+    fixed threshold.
+
+    The value of k is automatically set to the number of true anomalies present in 
+    y_true. That is, k = sum(y_true).
+
+    Parameters:
+    y_true (np.array): The ground truth binary labels for the time series data.
+    y_anomaly_scores (np.array): The predicted anomaly scores for the time series data.
+    """
     m = PatK_pw(y_true,y_anomaly_scores)
 
     return m.get_score()
 
-def auc_roc_pw(y_true : np.array ,y_anomaly_scores:  np.array):
+def auc_roc_pw(y_true : np.array, y_anomaly_scores:  np.array):
+    """
+    Calculate the AUC-ROC score for anomaly detection in time series.
+
+    This is the standard Area Under the Receiver Operating Characteristic Curve (AUC-ROC),
+    computed in a point-wise manner. That is, each point in the time series is treated
+    independently when calculating true positives, false positives, and false negatives.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels for the time series (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Continuous anomaly scores assigned to each point in the series.
+
+    Returns:
+        float: AUC-ROC score.
+    """
     
     m = AUC_ROC(y_true,y_anomaly_scores)
 
@@ -18,7 +44,20 @@ def auc_roc_pw(y_true : np.array ,y_anomaly_scores:  np.array):
 
 
 def auc_pr_pw(y_true : np.array ,y_anomaly_scores:  np.array):
-    
+    """
+    Calculate the AUC-PR score for anomaly detection in time series.
+
+    This is the standard Area Under the Precision-Recall Curve (AUC-PR),
+    computed in a point-wise manner. That is, each point in the time series is treated
+    independently when calculating precision and recall.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels for the time series (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Continuous anomaly scores assigned to each point in the series.
+
+    Returns:
+        float: AUC-PR score.
+    """
     m = AUC_PR_pw(y_true,y_anomaly_scores)
 
     return m.get_score()
@@ -26,6 +65,25 @@ def auc_pr_pw(y_true : np.array ,y_anomaly_scores:  np.array):
 
 
 def auc_pr_pa(y_true: np.array, y_anomaly_scores: np.array):
+    """
+    Calculate the AUC-PR score using point-adjusted evaluation for anomaly detection in time series.
+
+    This is the standard Area Under the Precision-Recall Curve (AUC-PR), but instead of computing 
+    precision and recall point-wise, it uses a point-adjusted approach. Specifically, for each 
+    ground-truth anomalous segment, if at least one point within that segment is predicted as anomalous, 
+    the entire segment is considered correctly detected. The adjusted predictions are then compared 
+    to the ground-truth labels to compute true positives, false positives, and false negatives,
+    which are used to construct the PR curve.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels for the time series (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Continuous anomaly scores assigned to each point in the series.
+
+    Returns:
+        float: AUC-PR score (with point-adjusted evaluation).
+    """
+        
+    
     precisions = [1]
     recalls = [0]
     tps,fps,fns = [],[],[]
@@ -96,6 +154,25 @@ def auc_pr_pa(y_true: np.array, y_anomaly_scores: np.array):
 
 
 def auc_pr_sw(y_true: np.array, y_anomaly_scores: np.array):
+    """
+    Calculate the AUC-PR score using segment-wise evaluation for anomaly detection in time series.
+
+    This is the standard Area Under the Precision-Recall Curve (AUC-PR), but it uses a segment-wise 
+    adjustment when computing precision and recall. In this evaluation, each contiguous segment of 
+    anomalous ground-truth points is treated as a single unit. A true positive is counted if at least 
+    one predicted anomaly overlaps with the segment. A false negative occurs when a segment is 
+    completely missed, and a false positive is recorded for each predicted anomalous segment 
+    that does not overlap with any ground-truth anomaly. These adjusted counts are then used 
+    to compute precision and recall for constructing the PR curve.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels for the time series (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Continuous anomaly scores assigned to each point in the series.
+
+    Returns:
+        float: AUC-PR score (with segment-wise evaluation).
+    """
+
     precisions = [1]
     recalls = [0]
     tps,fps,fns = [],[],[]
@@ -185,14 +262,51 @@ def auc_pr_sw(y_true: np.array, y_anomaly_scores: np.array):
 
 
 def vus_roc(y_true : np.array ,y_anomaly_scores:  np.array, window=4):
-    
+    """
+    Calculate the VUS-ROC (Volume Under the ROC Surface) score for anomaly detection in time series.
+
+    This metric extends the classical AUC-ROC by introducing a temporal tolerance parameter `l`, which
+    smooths the binary ground-truth labels. The idea is to allow a flexible evaluation that tolerates
+    small misalignments in the detection of anomalies. The final score is computed by integrating 
+    the ROC-AUC over different values of the tolerance parameter, from 0 to `window`, thus producing
+    a volume under the ROC surface.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Anomaly scores for each time point.
+        window (int): Maximum temporal tolerance `l` used to smooth the evaluation.
+
+    Returns:
+        float: VUS-ROC score.
+
+    For more information, see the original paper:
+    https://dl.acm.org/doi/10.14778/3551793.3551830
+    """
     m = VUS_ROC(y_true,y_anomaly_scores,max_window=window)
 
     return m.get_score()
 
 
 def vus_pr(y_true : np.array ,y_anomaly_scores:  np.array,  window=4):
-    
+    """
+    Calculate the VUS-PR (Volume Under the PR Surface) score for anomaly detection in time series.
+
+    This metric is an extension of the classical AUC-PR, incorporating a temporal tolerance parameter `l`
+    that smooths the binary ground-truth labels. It allows for some flexibility in the detection of 
+    anomalies that are temporally close to the true events. The final metric integrates the PR-AUC
+    over several levels of temporal tolerance (from 0 to `window`), yielding a volume under the PR surface.
+
+    Parameters:
+        y_true (np.array): Ground-truth binary labels (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Anomaly scores for each time point.
+        window (int): Maximum temporal tolerance `l` used to smooth the evaluation.
+
+    Returns:
+        float: VUS-PR score.
+
+    For more information, see the original paper:
+    https://dl.acm.org/doi/10.14778/3551793.3551830
+    """
     m = VUS_PR(y_true,y_anomaly_scores,max_window=window)
 
     return m.get_score()
@@ -200,17 +314,29 @@ def vus_pr(y_true : np.array ,y_anomaly_scores:  np.array,  window=4):
 
 def real_pate(y_true: np.array, y_anomaly_scores: 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.
+    Calculate PATE score for anomaly detection in time series using real-valued anomaly scores.
+
+    This version of PATE evaluates real-valued anomaly scores by assigning weights to predictions 
+    based on their temporal proximity to the true anomaly intervals. It defines an early buffer of 
+    length `early` before each anomaly and a delay buffer of length `delay` after it. Detections with 
+    high scores within the anomaly interval receive full weight, while those in the buffer zones are 
+    assigned linearly decaying weights depending on their distance from the interval. Scores outside 
+    these zones contribute to false positives, and intervals with insufficient detection are penalized 
+    as false negatives.
+
+    The final PATE score aggregates these weighted contributions across all time steps, yielding 
+    a smooth performance measure that is sensitive to both the timing and confidence of the predictions.
+
+    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.
-    y_anomaly_scores (np.array): The predicted binary labels for the time series data.
-    early (int): The maximum number of time steps before an anomaly must be predicted to be considered early.
-    delay (int): The maximum number of time steps after an anomaly must be predicted to be considered delayed.
+        y_true (np.array): Ground truth binary labels (0 = normal, 1 = anomaly).
+        y_anomaly_scores (np.array): Real-valued anomaly scores for each time point.
+        early (int): Length of the early buffer zone before each anomaly interval.
+        delay (int): Length of the delay buffer zone after each anomaly interval.
 
     Returns:
-    float: The PATE score.
+        float: The real-valued PATE score.
     """
-    
     return PATE(y_true, y_anomaly_scores, early, delay, binary_scores=False)

tsadmetrics/utils.py

@@ -2,7 +2,7 @@ import numpy as np
 import pandas as pd
 import time
 
-def compute_metrics(y_true: np.array,y_pred: np.array,metrics: list, metrics_params: dict, is_anomaly_score = False, verbose = False):
+def compute_metrics(y_true: np.array,y_pred: np.array, metrics: list, metrics_params: dict, is_anomaly_score = False, verbose = False):
     """
     Computes the specified metrics for the given true and predicted values.
 

{tsadmetrics-0.1.10.dist-info → tsadmetrics-0.1.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tsadmetrics
-Version: 0.1.10
+Version: 0.1.11
 Summary: =?unknown-8bit?q?Librer=C3=ADa_para_evaluaci=C3=B3n_de_detecci=C3=B3n_de_anomal=C3=ADas?= en series temporales
 Home-page: https://github.com/pathsko/TSADmetrics
 Author: Pedro Rafael Velasco Priego

{tsadmetrics-0.1.10.dist-info → tsadmetrics-0.1.11.dist-info}/RECORD

@@ -1,3 +1,4 @@
+docs/conf.py,sha256=skVqctOiByesc7wNDW5DpjyTxUCP0wxlpWA1fsJYZhk,1384
 entorno/bin/activate_this.py,sha256=45dnJsdtOWIt5LtVSBmBfB8E7AlKcnhnZe9e3WGclak,1199
 entorno/bin/rst2html.py,sha256=h4RydG-iAectsUra0lNFGwB4_1mngxrtPPgQrxUWQ3A,643
 entorno/bin/rst2html4.py,sha256=Xiv3Zb1gk4jT7DYFVlf5w4LJtI5ZI3pW3b1KLxyPS5A,765
@@ -12,14 +13,14 @@ entorno/bin/rst2xetex.py,sha256=spisB81JgqAmMAkjdTaP8awFQS_Zuob9HIcbMi1kOS8,922
 entorno/bin/rst2xml.py,sha256=uoIfpn3prnir2tzqdycsAjOg-OWw663XOK47IeHCZdY,651
 entorno/bin/rstpep2html.py,sha256=sthYQHEgYfj4JqwG45URwVbRAs-HYuwKget7SUwp9fc,719
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tests/test_binary.py,sha256=3uLdXzdbQcqLRfXeKDmt2g2XQTU5lZOFQoiy-r9Olqo,29801
+tests/test_binary.py,sha256=dj9BsKBo5rpWw4JGiKKoVkg4rIW4YylTie2VxH2DAGo,29787
 tests/test_non_binary.py,sha256=syANlwm0DKsL6geGeq6nQI6ZVe6T_YXWTyk2-Hmck4s,11308
 tsadmetrics/__init__.py,sha256=MTWOa43fgOdkMNo5NglCReRnB8hoF0ob2PIvDziCNHw,1575
-tsadmetrics/binary_metrics.py,sha256=nwfPdfHAc_4tJMNlyIwMwFQRLvCU-ik9lQLqlaWLqTs,37741
-tsadmetrics/metric_utils.py,sha256=Y_lOE01_uyC22wnw3_G-kKUEJdqevDIWMWvSDE8Cjms,10477
-tsadmetrics/non_binary_metrics.py,sha256=hmARpwaYNl_u36uOHcTZqO3nd0LkHpJjPBtbqT6yP_g,6739
+tsadmetrics/binary_metrics.py,sha256=pEIe8s3_obGN1hHhfvQwg0BXKafs4lQ3l1-K03P3Ews,60067
+tsadmetrics/metric_utils.py,sha256=fm8v0X37_AlqWpkcUT9r3680QsjLljrHe2YuXkRLAZ4,10873
+tsadmetrics/non_binary_metrics.py,sha256=yo620BWZIq-OkBqQV7t7ynjGhcuX6QWQ6iq_7eJq9gI,13074
 tsadmetrics/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tsadmetrics/utils.py,sha256=fV5sJE094C_GjBbqrI34Wpy-4hcZtXc9y207ffQB7Mc,2360
+tsadmetrics/utils.py,sha256=15X_RkHdCxhu_-OH8fEm3gRVQ4tTMqCkNaQsQoloEYQ,2361
 tsadmetrics/_tsadeval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tsadmetrics/_tsadeval/auc_roc_pr_plot.py,sha256=PHqJUXq2qI248XV9o04D8SsUJgowetaKq0Cu5bYrIAE,12689
 tsadmetrics/_tsadeval/discontinuity_graph.py,sha256=Ci65l_DPi6HTtb8NvQJe1najgGrRuEpOMWvSyi2AeR0,4088
@@ -52,7 +53,7 @@ tsadmetrics/_tsadeval/prts/time_series_metrics/fscore.py,sha256=pJz4iuPyVGNvwsaR
 tsadmetrics/_tsadeval/prts/time_series_metrics/precision.py,sha256=jLkcMg7UNl25SHtZUBGkP-RV8HsvaZCtjakryl7PFWU,3204
 tsadmetrics/_tsadeval/prts/time_series_metrics/precision_recall.py,sha256=OhUJSm_I7VZ_gX_SSg8AYUq3_NW9rMIy7lAVsnOFw4Q,417
 tsadmetrics/_tsadeval/prts/time_series_metrics/recall.py,sha256=LL-0pPer3ymovVRlktaHo5XDzpgiDhWOVfdPOzKR6og,3152
-tsadmetrics-0.1.10.dist-info/METADATA,sha256=qYloOTiFkW1RZqlJMvIAm6rjYg_atf4i11aF6lrCQXU,831
-tsadmetrics-0.1.10.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
-tsadmetrics-0.1.10.dist-info/top_level.txt,sha256=WHaYe-ubr_88yhxe-SaZC8HuAMvlSjXCo-wIdkTeKtA,26
-tsadmetrics-0.1.10.dist-info/RECORD,,
+tsadmetrics-0.1.11.dist-info/METADATA,sha256=JrsyLRUVbWIhrBkE56hn3ALYUycm3j52kSmmcq8TMhA,831
+tsadmetrics-0.1.11.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+tsadmetrics-0.1.11.dist-info/top_level.txt,sha256=s2VIr_ePl-WZbYt9FsYbsDGM7J-Qc5cgpwEOeQ3FVpM,31
+tsadmetrics-0.1.11.dist-info/RECORD,,

{tsadmetrics-0.1.10.dist-info → tsadmetrics-0.1.11.dist-info}/top_level.txt

@@ -1,3 +1,4 @@
+docs
 entorno
 tests
 tsadmetrics