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 +5 -0
- labelfree/metrics/__init__.py +48 -0
- labelfree/metrics/asoi.py +125 -0
- labelfree/metrics/autouad.py +94 -0
- labelfree/metrics/consensus.py +95 -0
- labelfree/metrics/ireos.py +356 -0
- labelfree/metrics/laplacian.py +55 -0
- labelfree/metrics/mass_volume.py +147 -0
- labelfree/metrics/score_cluster.py +57 -0
- labelfree/metrics/sireos.py +66 -0
- labelfree/metrics/stability.py +126 -0
- labelfree/utils/__init__.py +1 -0
- labelfree/utils/validation.py +77 -0
- labelfree-1.0.0.dist-info/METADATA +82 -0
- labelfree-1.0.0.dist-info/RECORD +17 -0
- labelfree-1.0.0.dist-info/WHEEL +4 -0
- labelfree-1.0.0.dist-info/licenses/LICENSE +21 -0
labelfree/__init__.py
ADDED
|
@@ -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
|