labelfree 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
labelfree/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Label-free metrics for unsupervised anomaly detector evaluation."""
2
+
3
+ __version__ = "1.0.0"
4
+
5
+ __all__ = ["__version__"]
@@ -0,0 +1,48 @@
1
+ """Metric functions."""
2
+
3
+ from labelfree.metrics.asoi import asi_score, asoi_score
4
+ from labelfree.metrics.autouad import (
5
+ expected_anomaly_gap_score,
6
+ normalized_pseudo_discrepancy_score,
7
+ relative_top_median_score,
8
+ )
9
+ from labelfree.metrics.consensus import (
10
+ average_rank_consensus_scores,
11
+ hits_model_scores,
12
+ model_centrality_scores,
13
+ )
14
+ from labelfree.metrics.ireos import ireos_score, ireos_scores
15
+ from labelfree.metrics.laplacian import laplacian_score
16
+ from labelfree.metrics.mass_volume import (
17
+ bounding_box_volume,
18
+ excess_mass_auc,
19
+ excess_mass_curve,
20
+ mass_volume_auc,
21
+ mass_volume_curve,
22
+ )
23
+ from labelfree.metrics.score_cluster import score_cluster_metrics
24
+ from labelfree.metrics.sireos import sireos_score
25
+ from labelfree.metrics.stability import ranking_stability_score, top_k_stability_score
26
+
27
+ __all__ = [
28
+ "asi_score",
29
+ "asoi_score",
30
+ "average_rank_consensus_scores",
31
+ "bounding_box_volume",
32
+ "excess_mass_auc",
33
+ "excess_mass_curve",
34
+ "expected_anomaly_gap_score",
35
+ "hits_model_scores",
36
+ "ireos_score",
37
+ "ireos_scores",
38
+ "laplacian_score",
39
+ "mass_volume_auc",
40
+ "mass_volume_curve",
41
+ "model_centrality_scores",
42
+ "normalized_pseudo_discrepancy_score",
43
+ "relative_top_median_score",
44
+ "ranking_stability_score",
45
+ "score_cluster_metrics",
46
+ "sireos_score",
47
+ "top_k_stability_score",
48
+ ]
@@ -0,0 +1,125 @@
1
+ """ASI and ASOI metrics for predicted anomaly partitions."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+
7
+ import numpy as np
8
+
9
+ from labelfree.utils.validation import as_2d_finite, split_score_labels
10
+
11
+
12
+ def asi_score(
13
+ X,
14
+ scores,
15
+ *,
16
+ n_outliers: int | None = None,
17
+ contamination: float | None = None,
18
+ score_polarity: str = "higher_is_anomalous",
19
+ ) -> float:
20
+ """Anomaly Separation Index from Mahmud, Farou, and Lendak.
21
+
22
+ Returns Eq. 3 from the paper: a multivariate standardized mean difference
23
+ between predicted normal and anomaly groups. Higher is better.
24
+ """
25
+ normal, anomaly = _split_X(
26
+ X,
27
+ scores,
28
+ n_outliers=n_outliers,
29
+ contamination=contamination,
30
+ score_polarity=score_polarity,
31
+ )
32
+ if len(normal) < 2 or len(anomaly) < 2:
33
+ raise ValueError("ASI requires at least two normal and two anomaly samples")
34
+
35
+ mean_distance = float(np.linalg.norm(normal.mean(axis=0) - anomaly.mean(axis=0)))
36
+ pooled_var = (
37
+ (len(normal) - 1) * normal.var(axis=0, ddof=1)
38
+ + (len(anomaly) - 1) * anomaly.var(axis=0, ddof=1)
39
+ ) / (len(normal) + len(anomaly) - 2)
40
+ scale = float(np.sqrt(np.sum(pooled_var)))
41
+ if scale == 0:
42
+ return math.inf if mean_distance > 0 else 0.0
43
+ return mean_distance / scale
44
+
45
+
46
+ def asoi_score(
47
+ X,
48
+ scores,
49
+ *,
50
+ n_outliers: int | None = None,
51
+ contamination: float | None = None,
52
+ score_polarity: str = "higher_is_anomalous",
53
+ alpha: float = 0.5314,
54
+ beta: float = 0.4686,
55
+ ) -> float:
56
+ """Anomaly Separation and Overlap Index.
57
+
58
+ Combines mean anomaly-to-normal-centroid separation with average
59
+ feature-wise Hellinger distance as defined by Mahmud et al. Higher is
60
+ better. The separation term is scale-dependent, so scale ``X`` before
61
+ comparing results across datasets.
62
+ """
63
+ _check_weights(alpha, beta)
64
+ normal, anomaly = _split_X(
65
+ X,
66
+ scores,
67
+ n_outliers=n_outliers,
68
+ contamination=contamination,
69
+ score_polarity=score_polarity,
70
+ )
71
+ normal_center = normal.mean(axis=0)
72
+ separation = float(np.linalg.norm(anomaly - normal_center, axis=1).mean())
73
+
74
+ hellinger = float(
75
+ np.mean(
76
+ [
77
+ _hellinger_feature(anomaly[:, feature], normal[:, feature])
78
+ for feature in range(normal.shape[1])
79
+ ]
80
+ )
81
+ )
82
+ return alpha * separation + beta * hellinger
83
+
84
+
85
+ def _split_X(
86
+ X,
87
+ scores,
88
+ *,
89
+ n_outliers: int | None,
90
+ contamination: float | None,
91
+ score_polarity: str,
92
+ ) -> tuple[np.ndarray, np.ndarray]:
93
+ X = as_2d_finite(X, name="X")
94
+ _, labels = split_score_labels(
95
+ scores,
96
+ n_outliers=n_outliers,
97
+ contamination=contamination,
98
+ score_polarity=score_polarity,
99
+ )
100
+ if X.shape[0] != labels.size:
101
+ raise ValueError("X and scores must have the same number of samples")
102
+ return X[labels == 0], X[labels == 1]
103
+
104
+
105
+ def _hellinger_feature(anomaly: np.ndarray, normal: np.ndarray) -> float:
106
+ low = min(float(anomaly.min()), float(normal.min()))
107
+ high = max(float(anomaly.max()), float(normal.max()))
108
+ if low == high:
109
+ return 0.0
110
+
111
+ bins = math.ceil(2 * (anomaly.size + normal.size) ** (1 / 3))
112
+ anomaly_counts, edges = np.histogram(anomaly, bins=bins, range=(low, high))
113
+ normal_counts, _ = np.histogram(normal, bins=edges)
114
+ anomaly_mass = anomaly_counts / anomaly.size
115
+ normal_mass = normal_counts / normal.size
116
+ return float(
117
+ np.linalg.norm(np.sqrt(anomaly_mass) - np.sqrt(normal_mass)) / math.sqrt(2)
118
+ )
119
+
120
+
121
+ def _check_weights(alpha: float, beta: float) -> None:
122
+ if alpha < 0 or beta < 0:
123
+ raise ValueError("alpha and beta must be non-negative")
124
+ if not math.isclose(alpha + beta, 1.0):
125
+ raise ValueError("alpha and beta must sum to 1")
@@ -0,0 +1,94 @@
1
+ """Score-distribution metrics from AutoUAD."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+
7
+ import numpy as np
8
+
9
+ from labelfree.utils.validation import orient_scores
10
+
11
+ EPSILON = 1e-6
12
+
13
+
14
+ def relative_top_median_score(
15
+ scores,
16
+ *,
17
+ top_fraction: float = 0.05,
18
+ score_polarity: str = "higher_is_anomalous",
19
+ eps: float = EPSILON,
20
+ ) -> float:
21
+ """Relative Top-Median score-tail separation. Higher is better."""
22
+ scores = orient_scores(scores, score_polarity=score_polarity)
23
+ top = _top_scores(scores, top_fraction)
24
+ median = float(np.median(scores))
25
+ return (float(np.mean(top)) - median) / (median + eps)
26
+
27
+
28
+ def expected_anomaly_gap_score(
29
+ scores,
30
+ *,
31
+ top_fraction: float = 0.2,
32
+ score_polarity: str = "higher_is_anomalous",
33
+ eps: float = EPSILON,
34
+ ) -> float:
35
+ """Expected Anomaly Gap over top-tail thresholds. Higher is better."""
36
+ scores = np.sort(orient_scores(scores, score_polarity=score_polarity))[::-1]
37
+ _check_fraction(top_fraction)
38
+ n_samples = scores.size
39
+ top_count = min(math.ceil(n_samples * top_fraction), n_samples - 1)
40
+ if top_count < 1:
41
+ raise ValueError("scores must contain at least two values")
42
+
43
+ k = np.arange(1, top_count + 1, dtype=float)
44
+ high_sum = np.cumsum(scores)[:top_count]
45
+ high_sum_sq = np.cumsum(scores * scores)[:top_count]
46
+ total = float(np.sum(scores))
47
+ total_sq = float(np.sum(scores * scores))
48
+
49
+ low_count = n_samples - k
50
+ high_mean = high_sum / k
51
+ low_sum = total - high_sum
52
+ low_mean = low_sum / low_count
53
+ high_var = np.maximum(high_sum_sq / k - high_mean * high_mean, 0.0)
54
+ low_var = np.maximum(
55
+ (total_sq - high_sum_sq) / low_count - low_mean * low_mean,
56
+ 0.0,
57
+ )
58
+
59
+ numerator = k * low_count * (high_mean - low_mean) ** 2
60
+ denominator = n_samples * (k * high_var + low_count * low_var + eps)
61
+ return float(np.mean(numerator / denominator))
62
+
63
+
64
+ def normalized_pseudo_discrepancy_score(
65
+ validation_scores,
66
+ generated_scores,
67
+ *,
68
+ score_polarity: str = "higher_is_anomalous",
69
+ eps: float = EPSILON,
70
+ ) -> float:
71
+ """Discrepancy between validation and generated score vectors. Higher is better."""
72
+ validation_scores = orient_scores(
73
+ validation_scores,
74
+ score_polarity=score_polarity,
75
+ )
76
+ generated_scores = orient_scores(
77
+ generated_scores,
78
+ score_polarity=score_polarity,
79
+ )
80
+ mean_gap = float(np.mean(generated_scores) - np.mean(validation_scores))
81
+ variance_sum = float(np.var(generated_scores) + np.var(validation_scores))
82
+ return mean_gap * mean_gap / (2 * variance_sum + eps)
83
+
84
+
85
+ def _top_scores(scores: np.ndarray, top_fraction: float) -> np.ndarray:
86
+ _check_fraction(top_fraction)
87
+ count = max(1, math.ceil(scores.size * top_fraction))
88
+ threshold = np.partition(scores, -count)[-count]
89
+ return scores[scores >= threshold]
90
+
91
+
92
+ def _check_fraction(value: float) -> None:
93
+ if not 0 < value < 1:
94
+ raise ValueError("top_fraction must be between 0 and 1")
@@ -0,0 +1,95 @@
1
+ """Consensus metrics over candidate anomaly-score matrices."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+
7
+ from labelfree.utils.validation import average_ranks, orient_scores
8
+
9
+
10
+ def model_centrality_scores(
11
+ score_matrix,
12
+ *,
13
+ score_polarity: str = "higher_is_anomalous",
14
+ ) -> np.ndarray:
15
+ """Average pairwise rank agreement for model-by-sample scores. Higher is better."""
16
+ ranks = _rank_matrix(score_matrix, score_polarity=score_polarity)
17
+ n_models = ranks.shape[0]
18
+ similarity = np.eye(n_models)
19
+ for i in range(n_models):
20
+ for j in range(i + 1, n_models):
21
+ corr = _pearson(ranks[i], ranks[j])
22
+ similarity[i, j] = corr
23
+ similarity[j, i] = corr
24
+ return (similarity.sum(axis=1) - 1.0) / (n_models - 1)
25
+
26
+
27
+ def average_rank_consensus_scores(
28
+ score_matrix,
29
+ *,
30
+ score_polarity: str = "higher_is_anomalous",
31
+ ) -> np.ndarray:
32
+ """Agreement with the average rank across model-by-sample scores. Higher is better."""
33
+ ranks = _rank_matrix(score_matrix, score_polarity=score_polarity)
34
+ consensus = ranks.mean(axis=0)
35
+ return np.array([_pearson(row, consensus) for row in ranks], dtype=float)
36
+
37
+
38
+ def hits_model_scores(
39
+ score_matrix,
40
+ *,
41
+ score_polarity: str = "higher_is_anomalous",
42
+ max_iter: int = 100,
43
+ tol: float = 1e-10,
44
+ ) -> np.ndarray:
45
+ """HITS hubness for a model-by-sample score matrix. Higher is better."""
46
+ if max_iter < 1:
47
+ raise ValueError("max_iter must be positive")
48
+ if tol < 0:
49
+ raise ValueError("tol must be non-negative")
50
+ ranks = _rank_matrix(score_matrix, score_polarity=score_polarity)
51
+ weights = ranks / ranks.shape[1]
52
+ hub = np.full(ranks.shape[0], 1 / np.sqrt(ranks.shape[0]))
53
+
54
+ for _ in range(max_iter):
55
+ authority = _unit(weights.T @ hub)
56
+ next_hub = _unit(weights @ authority)
57
+ if np.linalg.norm(next_hub - hub) <= tol:
58
+ hub = next_hub
59
+ break
60
+ hub = next_hub
61
+ return hub
62
+
63
+
64
+ def _rank_matrix(score_matrix, *, score_polarity: str) -> np.ndarray:
65
+ matrix = np.asarray(score_matrix, dtype=float)
66
+ if matrix.ndim != 2:
67
+ raise ValueError("score_matrix must be 2D with shape (n_models, n_samples)")
68
+ if min(matrix.shape) < 2:
69
+ raise ValueError(
70
+ "score_matrix must contain at least two models and two samples"
71
+ )
72
+ if not np.isfinite(matrix).all():
73
+ raise ValueError("score_matrix contains non-finite values")
74
+ return np.vstack(
75
+ [
76
+ average_ranks(orient_scores(row, score_polarity=score_polarity))
77
+ for row in matrix
78
+ ]
79
+ )
80
+
81
+
82
+ def _pearson(x: np.ndarray, y: np.ndarray) -> float:
83
+ x = x - x.mean()
84
+ y = y - y.mean()
85
+ denominator = float(np.linalg.norm(x) * np.linalg.norm(y))
86
+ if denominator == 0:
87
+ return 0.0
88
+ return float(np.dot(x, y) / denominator)
89
+
90
+
91
+ def _unit(values: np.ndarray) -> np.ndarray:
92
+ norm = float(np.linalg.norm(values))
93
+ if norm == 0:
94
+ return values
95
+ return values / norm