optimal-classification-cutoffs 3.0.0__tar.gz → 3.0.2__tar.gz

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.
Files changed (27) hide show
  1. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/PKG-INFO +1 -1
  2. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/api.py +32 -42
  3. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/core.py +4 -1
  4. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/metrics_core.py +2 -2
  5. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/multiclass.py +49 -15
  6. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/optimize.py +75 -47
  7. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/piecewise.py +14 -61
  8. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/validation.py +18 -18
  9. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/pyproject.toml +9 -10
  10. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/pyproject.toml.orig +11 -10
  11. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/LICENSE +0 -0
  12. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/README.md +0 -0
  13. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/__init__.py +0 -0
  14. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/algorithms/__init__.py +0 -0
  15. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/algorithms/binary.py +0 -0
  16. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/algorithms/expected.py +0 -0
  17. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/algorithms/multiclass.py +0 -0
  18. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/algorithms/multilabel.py +0 -0
  19. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/bayes/__init__.py +0 -0
  20. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/bayes_core.py +0 -0
  21. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/binary.py +0 -0
  22. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/cv/__init__.py +0 -0
  23. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/expected.py +0 -0
  24. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/metrics/__init__.py +0 -0
  25. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/multilabel.py +0 -0
  26. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/numba_utils.py +0 -0
  27. {optimal_classification_cutoffs-3.0.0 → optimal_classification_cutoffs-3.0.2}/optimal_cutoffs/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: optimal-classification-cutoffs
3
- Version: 3.0.0
3
+ Version: 3.0.2
4
4
  Summary: Utilities for computing optimal classification cutoffs for binary and multiclass classification
5
5
  Keywords: classification,threshold,cutoff,f1-score,cost-sensitive-learning,machine-learning
6
6
  Author: Gaurav Sood
@@ -195,6 +195,13 @@ def optimize_thresholds(
195
195
 
196
196
  # 2. Average strategy selection
197
197
  match average:
198
+ case Average.AUTO if (
199
+ inferred_task == Task.MULTICLASS
200
+ and mode == "empirical"
201
+ and method == "micro"
202
+ ):
203
+ inferred_average = Average.MICRO
204
+ all_notes.append("Using micro averaging for the shared-cutoff method")
198
205
  case Average.AUTO:
199
206
  inferred_average, avg_notes = select_average_with_explanation(
200
207
  inferred_task, metric
@@ -208,7 +215,10 @@ def optimize_thresholds(
208
215
  if method == "auto":
209
216
  n_samples = len(y_true)
210
217
  inferred_method, method_notes = select_method_with_explanation(
211
- inferred_task, metric, n_samples
218
+ inferred_task,
219
+ metric,
220
+ n_samples,
221
+ average=inferred_average if mode == "empirical" else Average.AUTO,
212
222
  )
213
223
  all_notes.extend(method_notes)
214
224
  else:
@@ -519,6 +529,23 @@ def _optimize_multiclass(
519
529
  )
520
530
 
521
531
  # Empirical mode
532
+ if average == Average.MICRO:
533
+ if method not in {"micro", "sort_scan", "minimize"}:
534
+ raise ValueError("Micro averaging requires a shared-cutoff method")
535
+ from .multiclass import optimize_micro_multiclass
536
+
537
+ return optimize_micro_multiclass(
538
+ y_true,
539
+ y_score,
540
+ metric=metric,
541
+ method="auto" if method == "micro" else method,
542
+ sample_weight=sample_weight,
543
+ comparison=comparison,
544
+ tolerance=tolerance,
545
+ **kwargs,
546
+ )
547
+
548
+ class_average = "weighted" if average == Average.WEIGHTED else "macro"
522
549
  match method:
523
550
  case "coord_ascent":
524
551
  # coord_ascent only supports ">" comparison
@@ -530,19 +557,21 @@ def _optimize_multiclass(
530
557
  y_true,
531
558
  y_score,
532
559
  metric=metric,
560
+ average=class_average,
533
561
  sample_weight=sample_weight,
534
562
  comparison=comparison,
535
563
  tolerance=tolerance,
536
564
  **kwargs,
537
565
  )
538
566
 
539
- case "independent":
567
+ case "independent" | "sort_scan" | "minimize":
540
568
  from .multiclass import optimize_ovr_independent
541
569
 
542
570
  return optimize_ovr_independent(
543
571
  y_true,
544
572
  y_score,
545
573
  metric=metric,
574
+ average=class_average,
546
575
  sample_weight=sample_weight,
547
576
  comparison=comparison,
548
577
  tolerance=tolerance,
@@ -550,46 +579,7 @@ def _optimize_multiclass(
550
579
  )
551
580
 
552
581
  case "micro":
553
- from .multiclass import optimize_micro_multiclass
554
-
555
- return optimize_micro_multiclass(
556
- y_true,
557
- y_score,
558
- metric=metric,
559
- sample_weight=sample_weight,
560
- comparison=comparison,
561
- tolerance=tolerance,
562
- **kwargs,
563
- )
564
-
565
- case "sort_scan":
566
- # For multiclass, sort_scan should route to appropriate OvR method
567
- from .multiclass import optimize_ovr_independent
568
-
569
- return optimize_ovr_independent(
570
- y_true,
571
- y_score,
572
- metric=metric,
573
- sample_weight=sample_weight,
574
- comparison=comparison,
575
- tolerance=tolerance,
576
- **kwargs,
577
- )
578
-
579
- case "minimize":
580
- # minimize method for multiclass routes to independent optimization
581
- from .multiclass import optimize_ovr_independent
582
-
583
- return optimize_ovr_independent(
584
- y_true,
585
- y_score,
586
- metric=metric,
587
- sample_weight=sample_weight,
588
- comparison=comparison,
589
- tolerance=tolerance,
590
- **kwargs,
591
- )
592
-
582
+ raise ValueError("The multiclass micro method requires average='micro'")
593
583
  case _:
594
584
  raise ValueError(
595
585
  f"Invalid optimization method: '{method}' is not supported for "
@@ -151,7 +151,7 @@ def infer_task_with_explanation(
151
151
 
152
152
 
153
153
  def select_method_with_explanation(
154
- task: Task, metric: str, n_samples: int
154
+ task: Task, metric: str, n_samples: int, *, average: Average = Average.AUTO
155
155
  ) -> tuple[str, list[str]]:
156
156
  """Select optimization method with explanation.
157
157
 
@@ -159,6 +159,7 @@ def select_method_with_explanation(
159
159
  task: Classification task type
160
160
  metric: Metric to optimize
161
161
  n_samples: Number of samples (may influence method selection)
162
+ average: Requested empirical averaging strategy.
162
163
 
163
164
  Returns:
164
165
  Selected method name
@@ -184,6 +185,8 @@ def select_method_with_explanation(
184
185
  return "minimize", notes
185
186
 
186
187
  case Task.MULTICLASS:
188
+ if average == Average.MICRO:
189
+ return "micro", ["Using a shared cutoff for micro averaging"]
187
190
  if metric == "f1":
188
191
  notes.append("Using coordinate ascent for coupled multiclass F1")
189
192
  return "coord_ascent", notes
@@ -387,7 +387,7 @@ def confusion_matrix_at_threshold(
387
387
 
388
388
  # Validate threshold
389
389
  if require_proba:
390
- validate_threshold(threshold, allow_epsilon_outside=False)
390
+ validate_threshold(threshold, allow_epsilon_outside=True)
391
391
 
392
392
  _validate_comparison_operator(comparison)
393
393
 
@@ -839,7 +839,7 @@ def multiclass_confusion_matrices_at_thresholds(
839
839
  )
840
840
 
841
841
  if require_proba:
842
- validate_threshold(thresholds, n_classes)
842
+ validate_threshold(thresholds, n_classes, allow_epsilon_outside=True)
843
843
 
844
844
  confusion_matrices = []
845
845
 
@@ -18,7 +18,7 @@ from typing import TYPE_CHECKING
18
18
 
19
19
  import numpy as np
20
20
 
21
- from .core import OptimizationResult, Task
21
+ from .core import Average, OptimizationResult, Task
22
22
  from .validation import validate_multiclass_classification
23
23
 
24
24
  if TYPE_CHECKING:
@@ -30,6 +30,7 @@ def optimize_ovr_independent(
30
30
  y_score: ArrayLike,
31
31
  *,
32
32
  metric: str = "f1",
33
+ average: str = "macro",
33
34
  method: str = "auto",
34
35
  sample_weight: ArrayLike | None = None,
35
36
  comparison: str = ">",
@@ -48,6 +49,7 @@ def optimize_ovr_independent(
48
49
  y_true: True class labels in {0, 1, ..., K-1}. Shape: (n_samples,).
49
50
  y_score: Predicted probabilities for each class. Shape: (n_samples, n_classes).
50
51
  metric: Metric to optimize per class. Defaults to "f1".
52
+ average: Use "macro" for equal class weights or "weighted" for class support.
51
53
  method: Binary optimization method. Defaults to "auto".
52
54
  sample_weight: Sample weights. Shape: (n_samples,). Optional.
53
55
  comparison: Comparison operator. Defaults to ">".
@@ -56,6 +58,9 @@ def optimize_ovr_independent(
56
58
  Returns:
57
59
  Result with per-class thresholds optimized independently
58
60
 
61
+ Raises:
62
+ ValueError: If the averaging strategy is unsupported.
63
+
59
64
  Examples:
60
65
  >>> y_true = [0, 1, 2, 0, 1]
61
66
  >>> y_score = [[0.7, 0.2, 0.1], [0.1, 0.8, 0.1], [0.1, 0.1, 0.8], ...]
@@ -64,6 +69,9 @@ def optimize_ovr_independent(
64
69
  """
65
70
  from .binary import optimize_metric_binary
66
71
 
72
+ if average not in {"macro", "weighted"}:
73
+ raise ValueError("Use macro or weighted averaging for this multiclass method")
74
+
67
75
  # Validate inputs
68
76
  y_true, y_score, sample_weight = validate_multiclass_classification(
69
77
  y_true, y_score, sample_weight, require_proba=True
@@ -94,8 +102,12 @@ def optimize_ovr_independent(
94
102
  optimal_thresholds[k] = result_k.thresholds[0]
95
103
  optimal_scores[k] = result_k.scores[0]
96
104
 
97
- # Macro average score
98
- macro_score = np.mean(optimal_scores)
105
+ class_weights = (
106
+ np.bincount(y_true, weights=sample_weight, minlength=n_classes)
107
+ if average == "weighted"
108
+ else None
109
+ )
110
+ average_score = np.average(optimal_scores, weights=class_weights)
99
111
 
100
112
  from .validation import apply_threshold
101
113
 
@@ -109,10 +121,11 @@ def optimize_ovr_independent(
109
121
 
110
122
  return OptimizationResult(
111
123
  thresholds=optimal_thresholds,
112
- scores=np.array([macro_score], dtype=np.float64),
124
+ scores=np.array([average_score], dtype=np.float64),
113
125
  predict=predict_multiclass_independent,
114
126
  task=Task.MULTICLASS,
115
- metric=f"macro_{metric}_ovr_independent",
127
+ average=Average(average),
128
+ metric=f"{average}_{metric}_ovr_independent",
116
129
  n_classes=n_classes,
117
130
  )
118
131
 
@@ -122,6 +135,7 @@ def optimize_ovr_margin(
122
135
  y_score: ArrayLike,
123
136
  *,
124
137
  metric: str = "f1",
138
+ average: str = "macro",
125
139
  max_iter: int = 30,
126
140
  sample_weight: ArrayLike | None = None,
127
141
  comparison: str = ">",
@@ -140,6 +154,7 @@ def optimize_ovr_margin(
140
154
  y_true: True class labels in {0, 1, ..., K-1}. Shape: (n_samples,).
141
155
  y_score: Predicted probabilities for each class. Shape: (n_samples, n_classes).
142
156
  metric: Metric to optimize (currently supports "f1" only). Defaults to "f1".
157
+ average: Use "macro" for equal class weights or "weighted" for class support.
143
158
  max_iter: Maximum coordinate ascent iterations. Defaults to 30.
144
159
  sample_weight: Sample weights. Shape: (n_samples,). Optional.
145
160
  comparison: Comparison operator (only ">" supported for margin rule). Defaults
@@ -150,6 +165,7 @@ def optimize_ovr_margin(
150
165
  Result with per-class thresholds optimized via coordinate ascent
151
166
 
152
167
  Raises:
168
+ ValueError: If the averaging strategy is unsupported.
153
169
  NotImplementedError: If `metric` is not "f1" or `comparison` is not ">".
154
170
 
155
171
  Examples:
@@ -164,6 +180,9 @@ def optimize_ovr_margin(
164
180
  """
165
181
  from .optimize import coordinate_ascent_kernel
166
182
 
183
+ if average not in {"macro", "weighted"}:
184
+ raise ValueError("Use macro or weighted averaging for this multiclass method")
185
+
167
186
  # Validate inputs
168
187
  y_true, y_score, sample_weight = validate_multiclass_classification(
169
188
  y_true, y_score, sample_weight, require_proba=True
@@ -192,6 +211,7 @@ def optimize_ovr_margin(
192
211
  weights,
193
212
  max_iter=max_iter,
194
213
  tol=tolerance,
214
+ support_weighted=average == "weighted",
195
215
  )
196
216
 
197
217
  from .validation import make_margin_predictor
@@ -201,7 +221,8 @@ def optimize_ovr_margin(
201
221
  scores=np.array([best_score]),
202
222
  predict=make_margin_predictor(thresholds),
203
223
  task=Task.MULTICLASS,
204
- metric=f"macro_{metric}_margin_rule",
224
+ average=Average(average),
225
+ metric=f"{average}_{metric}_margin_rule",
205
226
  n_classes=n_classes,
206
227
  )
207
228
 
@@ -218,9 +239,10 @@ def optimize_micro_multiclass(
218
239
  ) -> OptimizationResult:
219
240
  """Optimize micro-averaged multiclass metrics using single threshold.
220
241
 
221
- For micro averaging, we use a single threshold applied to all classes,
222
- then predict the class with highest valid probability. This reduces to
223
- a single binary optimization problem on flattened data.
242
+ Fit the shared cutoff on pooled one-vs-rest decisions. For single-label
243
+ prediction, the highest probability always wins: if it fails the shared
244
+ cutoff, all other classes fail too and the fallback selects the same class.
245
+ The returned score evaluates these single-label predictions.
224
246
 
225
247
  Decision rule: ŷ = argmax{j: p_j ≥ τ} p_j (or argmax p_j if none valid)
226
248
 
@@ -276,15 +298,20 @@ def optimize_micro_multiclass(
276
298
 
277
299
  optimal_threshold = result.thresholds[0]
278
300
 
301
+ from .metrics_core import compute_multiclass_metrics_from_labels
279
302
  from .validation import make_multiclass_predictor
280
303
 
281
- # Return same threshold for all classes
282
304
  thresholds = np.full(n_classes, optimal_threshold, dtype=np.float64)
305
+ predict = make_multiclass_predictor(thresholds, comparison)
306
+ score = compute_multiclass_metrics_from_labels(
307
+ y_true, predict(y_score), metric, "micro", sample_weight, n_classes
308
+ )
283
309
 
284
310
  return OptimizationResult(
285
311
  thresholds=thresholds,
286
- scores=result.scores,
287
- predict=make_multiclass_predictor(thresholds, comparison),
312
+ scores=np.atleast_1d(score),
313
+ average=Average.MICRO,
314
+ predict=predict,
288
315
  task=Task.MULTICLASS,
289
316
  metric=f"micro_{metric}",
290
317
  n_classes=n_classes,
@@ -314,7 +341,8 @@ def optimize_multiclass(
314
341
  y_true: True class labels in {0, 1, ..., K-1}. Shape: (n_samples,).
315
342
  y_score: Predicted probabilities for each class. Shape: (n_samples, n_classes).
316
343
  metric: Metric to optimize. Defaults to "f1".
317
- average: Averaging strategy. One of {"macro", "micro"}. Defaults to "macro".
344
+ average: Equal class weights ("macro"), support weights ("weighted"),
345
+ or pooled counts ("micro"). Defaults to "macro".
318
346
  method: Optimization method, defaults to "auto":
319
347
  - "auto": For macro, uses coord_ascent (margin rule)
320
348
  - "coord_ascent": Margin rule with coordinate ascent
@@ -350,7 +378,7 @@ def optimize_multiclass(
350
378
  comparison=comparison,
351
379
  tolerance=tolerance,
352
380
  )
353
- case "macro":
381
+ case "macro" | "weighted":
354
382
  match method:
355
383
  case "auto":
356
384
  # Auto method: choose best method based on metric and comparison
@@ -362,6 +390,7 @@ def optimize_multiclass(
362
390
  y_true,
363
391
  y_score,
364
392
  metric=metric,
393
+ average=average,
365
394
  max_iter=30,
366
395
  sample_weight=sample_weight,
367
396
  comparison=comparison,
@@ -373,6 +402,7 @@ def optimize_multiclass(
373
402
  y_true,
374
403
  y_score,
375
404
  metric=metric,
405
+ average=average,
376
406
  method="auto",
377
407
  sample_weight=sample_weight,
378
408
  comparison=comparison,
@@ -383,6 +413,7 @@ def optimize_multiclass(
383
413
  y_true,
384
414
  y_score,
385
415
  metric=metric,
416
+ average=average,
386
417
  max_iter=30,
387
418
  sample_weight=sample_weight,
388
419
  comparison=comparison,
@@ -396,6 +427,7 @@ def optimize_multiclass(
396
427
  y_true,
397
428
  y_score,
398
429
  metric=metric,
430
+ average=average,
399
431
  method="auto",
400
432
  sample_weight=sample_weight,
401
433
  comparison=comparison,
@@ -404,7 +436,9 @@ def optimize_multiclass(
404
436
  case _:
405
437
  raise ValueError(f"Unknown method for macro averaging: {method}")
406
438
  case _:
407
- raise ValueError(f"Unknown average: {average}. Use 'macro' or 'micro'")
439
+ raise ValueError(
440
+ f"Unknown average: {average}. Use 'macro', 'weighted', or 'micro'"
441
+ )
408
442
 
409
443
 
410
444
  __all__ = [
@@ -144,16 +144,18 @@ def sort_scan_kernel(
144
144
 
145
145
 
146
146
  @jit(nopython=True, fastmath=True, cache=True)
147
- def compute_macro_f1(tp: np.ndarray, fp: np.ndarray, support: np.ndarray) -> float:
148
- """Compute macro F1 from per-class TP/FP and support (FN = support - TP)."""
147
+ def _average_f1(
148
+ tp: np.ndarray, fp: np.ndarray, support: np.ndarray, class_weights: np.ndarray
149
+ ) -> float:
150
+ """Average per-class F1 using normalized weights (FN = support - TP)."""
149
151
  f1_sum = 0.0
150
152
  k = tp.shape[0]
151
153
  for c in range(k):
152
154
  fn = support[c] - tp[c]
153
155
  denom = 2.0 * tp[c] + fp[c] + fn
154
156
  if denom > 0.0:
155
- f1_sum += 2.0 * tp[c] / denom
156
- return f1_sum / float(k)
157
+ f1_sum += class_weights[c] * (2.0 * tp[c] / denom)
158
+ return f1_sum
157
159
 
158
160
 
159
161
  @jit(nopython=True, fastmath=True, cache=True)
@@ -163,8 +165,9 @@ def coordinate_ascent_kernel(
163
165
  weights: np.ndarray,
164
166
  max_iter: int,
165
167
  tol: float,
168
+ support_weighted: bool = False,
166
169
  ) -> tuple[np.ndarray, float, np.ndarray]:
167
- """Numba coordinate ascent for multiclass macro-F1 with sample weights.
170
+ """Coordinate ascent for multiclass macro or support-weighted F1.
168
171
 
169
172
  Predict via argmax over (p - tau). We iteratively adjust one class's
170
173
  threshold at a time by scanning the implied breakpoints for that class.
@@ -180,6 +183,8 @@ def coordinate_ascent_kernel(
180
183
  for i in range(n):
181
184
  support[y_true[i]] += weights[i]
182
185
 
186
+ class_weights = support / support.sum() if support_weighted else np.full(k, 1.0 / k)
187
+
183
188
  # Initialize by assigning every sample to its current best class
184
189
  tp = np.zeros(k, dtype=np.float64)
185
190
  fp = np.zeros(k, dtype=np.float64)
@@ -197,7 +202,7 @@ def coordinate_ascent_kernel(
197
202
  else:
198
203
  fp[pred] += w
199
204
 
200
- best_score = compute_macro_f1(tp, fp, support)
205
+ best_score = _average_f1(tp, fp, support, class_weights)
201
206
  no_improve_rounds = 0
202
207
 
203
208
  for it in range(max_iter):
@@ -233,43 +238,55 @@ def coordinate_ascent_kernel(
233
238
  else:
234
239
  fp_cand[pred] += w
235
240
 
236
- baseline = compute_macro_f1(tp_cand, fp_cand, support)
237
- current_best = baseline
238
- best_idx = -1
239
-
240
- # Simulate crossing each breakpoint in order
241
- for rank in range(n):
242
- idx = order[rank]
243
- w = weights[idx]
244
- old_pred = alternatives[idx]
245
-
246
- if y_true[idx] == old_pred:
247
- tp_cand[old_pred] -= w
248
- else:
249
- fp_cand[old_pred] -= w
250
-
251
- if y_true[idx] == c:
252
- tp_cand[c] += w
253
- else:
254
- fp_cand[c] += w
255
-
256
- score = compute_macro_f1(tp_cand, fp_cand, support)
257
- if score > current_best:
258
- current_best = score
259
- best_idx = rank
260
-
261
- # If we found an improvement for this coordinate, commit it
262
- if best_idx >= 0 and current_best > baseline + tol:
263
- sorted_breaks = breakpoints[order]
264
- if best_idx + 1 < n:
265
- new_threshold = 0.5 * (
266
- sorted_breaks[best_idx] + sorted_breaks[best_idx + 1]
267
- )
268
- else:
269
- new_threshold = sorted_breaks[best_idx] - 1e-6
270
-
241
+ # Above the highest breakpoint everyone takes their alternative.
242
+ current_best = _average_f1(tp_cand, fp_cand, support, class_weights)
243
+ new_threshold = breakpoints[order[0]] + 1.0
244
+ start = 0
245
+ while start < n:
246
+ cut = breakpoints[order[start]]
247
+ end = start + 1
248
+ while end < n and breakpoints[order[end]] == cut:
249
+ end += 1
250
+
251
+ # At equality argmax chooses the lowest class index. Just below
252
+ # the breakpoint, the entire group chooses c. Other splits of
253
+ # equal breakpoints cannot be realized by a scalar threshold.
254
+ for at_equality in (True, False):
255
+ moved = 0
256
+ for rank in range(start, end):
257
+ idx = order[rank]
258
+ old_pred = alternatives[idx]
259
+ if (c < old_pred) != at_equality:
260
+ continue
261
+ moved += 1
262
+ w = weights[idx]
263
+ if y_true[idx] == old_pred:
264
+ tp_cand[old_pred] -= w
265
+ else:
266
+ fp_cand[old_pred] -= w
267
+ if y_true[idx] == c:
268
+ tp_cand[c] += w
269
+ else:
270
+ fp_cand[c] += w
271
+
272
+ if at_equality and (moved == 0 or moved == end - start):
273
+ continue
274
+ score = _average_f1(tp_cand, fp_cand, support, class_weights)
275
+ if score > current_best:
276
+ current_best = score
277
+ if at_equality:
278
+ new_threshold = cut
279
+ elif end < n:
280
+ new_threshold = (cut + breakpoints[order[end]]) * 0.5
281
+ else:
282
+ new_threshold = cut - 1.0
283
+ start = end
284
+
285
+ if current_best > best_score + tol:
286
+ # Re-evaluate the actual floating-point margin rule before
287
+ # accepting a move. A rounded boundary can change a tied decision.
288
+ previous_threshold = thresholds[c]
271
289
  thresholds[c] = new_threshold
272
- # Rebuild committed tp/fp to match current thresholds
273
290
  tp[:] = 0.0
274
291
  fp[:] = 0.0
275
292
  for i in range(n):
@@ -286,10 +303,12 @@ def coordinate_ascent_kernel(
286
303
  else:
287
304
  fp[pred] += w
288
305
 
289
- new_global = compute_macro_f1(tp, fp, support)
290
- if new_global > best_score + tol:
291
- best_score = new_global
292
- improved_any = True
306
+ attained = _average_f1(tp, fp, support, class_weights)
307
+ if attained > best_score + tol:
308
+ best_score = attained
309
+ improved_any = True
310
+ else:
311
+ thresholds[c] = previous_threshold
293
312
 
294
313
  history[it] = best_score
295
314
 
@@ -308,6 +327,13 @@ def coordinate_ascent_kernel(
308
327
  # ============================================================================
309
328
 
310
329
 
330
+ def _probability_cut(threshold: float) -> float:
331
+ """Use the adjacent float64 cut for thresholds outside the probability range."""
332
+ return float(
333
+ np.clip(threshold, np.nextafter(0.0, -np.inf), np.nextafter(1.0, np.inf))
334
+ )
335
+
336
+
311
337
  def optimize_sort_scan(
312
338
  labels: np.ndarray,
313
339
  scores: np.ndarray,
@@ -330,6 +356,7 @@ def optimize_sort_scan(
330
356
  # _generic_sort_scan can handle None weights, but pass the array for consistency
331
357
  threshold, score = _generic_sort_scan(labels, scores, metric, weights, operator)
332
358
 
359
+ threshold = _probability_cut(threshold)
333
360
  from .validation import make_binary_predictor
334
361
 
335
362
  return OptimizationResult(
@@ -415,7 +442,7 @@ def optimize_scipy(
415
442
  objective, bounds=bounds, method=method, options={"xatol": tol}
416
443
  )
417
444
  # scipy's OptimizeResult is typed as a bare object in its stubs.
418
- optimal_threshold = float(result.x) # pyright: ignore[reportAttributeAccessIssue]
445
+ optimal_threshold = _probability_cut(result.x) # pyright: ignore[reportAttributeAccessIssue]
419
446
  optimal_score = -float(result.fun) # pyright: ignore[reportAttributeAccessIssue]
420
447
  except Exception:
421
448
  logger.warning("Scipy optimization failed, falling back to sort_scan")
@@ -481,6 +508,7 @@ def optimize_gradient(
481
508
  threshold += learning_rate * grad
482
509
  threshold = float(np.clip(threshold, lo, hi))
483
510
 
511
+ threshold = _probability_cut(threshold)
484
512
  final_score = evaluate_metric(threshold)
485
513
 
486
514
  from .validation import make_binary_predictor
@@ -94,19 +94,14 @@ def _compute_threshold_midpoint(
94
94
  exc = float(p_sorted[k_star])
95
95
 
96
96
  if inc - exc > tolerance:
97
- thr = 0.5 * (inc + exc)
98
- # For '>=' we bias a half-ulp downward so equals land in the included side
99
- return float(np.nextafter(thr, -np.inf)) if inclusive else thr
100
-
101
- # Tied (or nearly tied) scores: choose side per operator
102
- tied = exc
103
- # For '>', place threshold just above tied to exclude equals.
104
- # For '>=', place just below tied to include equals.
105
- return (
106
- float(np.nextafter(tied, np.inf))
107
- if not inclusive
108
- else float(np.nextafter(tied, -np.inf))
109
- )
97
+ midpoint = 0.5 * inc + 0.5 * exc
98
+ if inclusive:
99
+ midpoint = float(np.nextafter(midpoint, -np.inf))
100
+ if exc < midpoint < inc:
101
+ return midpoint
102
+
103
+ # Adjacent floating-point scores have no representable midpoint.
104
+ return inc if inclusive else exc
110
105
 
111
106
 
112
107
  def _realized_k(p_sorted: Array, threshold: float, inclusive: bool) -> int:
@@ -202,8 +197,12 @@ def optimal_threshold_sortscan(
202
197
  k_star = int(np.argmax(score_vec))
203
198
  score_theoretical = float(score_vec[k_star])
204
199
 
205
- # 5) Convert k* to a concrete threshold with correct > / >= semantics
206
- threshold = _compute_threshold_midpoint(p_sorted, k_star, inclusive, tolerance)
200
+ # A scalar threshold can include either all or none of a tied score group.
201
+ k_cut = k_star
202
+ if 0 < k_star < n and p_sorted[k_star - 1] == p_sorted[k_star]:
203
+ cuts = np.flatnonzero(np.r_[True, p_sorted[:-1] != p_sorted[1:], True])
204
+ k_cut = int(cuts[np.argmax(score_vec[cuts])])
205
+ threshold = _compute_threshold_midpoint(p_sorted, k_cut, inclusive, tolerance)
207
206
 
208
207
  # 6) Evaluate the achieved score at that threshold (handles ties & numerics)
209
208
  pred_labels = _predict_from_threshold(p, threshold, inclusive)
@@ -212,52 +211,6 @@ def optimal_threshold_sortscan(
212
211
  )
213
212
  score_actual = _evaluate_metric_scalar_efficient(metric_fn, tp, tn, fp, fn)
214
213
 
215
- # 7) If the realized score differs meaningfully (e.g., due to ties), probe a few
216
- # locally optimal alternatives (extremes and one-ULP nudges around the boundary).
217
- tie_discrepancy = abs(score_actual - score_theoretical)
218
- if tie_discrepancy > max(1e-6, 100 * tolerance):
219
- best_thr = threshold
220
- best_score = score_actual
221
-
222
- min_s = float(p_sorted[-1])
223
- max_s = float(p_sorted[0])
224
-
225
- candidates: list[float] = []
226
- if inclusive:
227
- # Include all vs exclude all
228
- candidates.extend([min_s, float(np.nextafter(max_s, np.inf))])
229
- else:
230
- candidates.extend([float(np.nextafter(min_s, -np.inf)), max_s])
231
-
232
- if 0 < k_star < n:
233
- inc = float(p_sorted[k_star - 1]) # last included by k*
234
- exc = float(p_sorted[k_star]) # first excluded by k*
235
- candidates.extend(
236
- [
237
- float(np.nextafter(inc, -np.inf)), # just below included
238
- float(np.nextafter(exc, np.inf)), # just above excluded
239
- ]
240
- )
241
-
242
- # Evaluate candidates
243
- for t in candidates:
244
- # If require_proba, clamp only if it does not alter intended decision
245
- # boundary;
246
- # we accept tiny excursions beyond [0,1] when necessary for semantics.
247
- t_eval = t
248
- pred_labels_alt = _predict_from_threshold(p, t_eval, inclusive)
249
- tp2, tn2, fp2, fn2 = confusion_matrix_from_predictions(
250
- y, pred_labels_alt, sample_weight=weights
251
- )
252
- s2 = _evaluate_metric_scalar_efficient(metric_fn, tp2, tn2, fp2, fn2)
253
- if s2 > best_score:
254
- best_score = s2
255
- best_thr = t_eval
256
-
257
- threshold = best_thr
258
- score_actual = best_score
259
-
260
- # 8) Diagnostics and final return
261
214
  k_real = _realized_k(p_sorted, threshold, inclusive)
262
215
 
263
216
  def predict_binary(probs: Array) -> Array:
@@ -207,9 +207,8 @@ def validate_threshold(
207
207
  Args:
208
208
  threshold: Threshold(s) to validate
209
209
  n_classes: For multiclass, expected number of thresholds
210
- allow_epsilon_outside: If True, allow values slightly outside [0,1] by
211
- floating-point epsilon.
212
- Used internally for thresholds that are nudged by nextafter().
210
+ allow_epsilon_outside: Accept the adjacent float64 values just below
211
+ zero and just above one that represent endpoint cuts.
213
212
 
214
213
  Returns:
215
214
  Validated threshold(s)
@@ -222,22 +221,20 @@ def validate_threshold(
222
221
  if not np.all(np.isfinite(arr)):
223
222
  raise ValueError("Thresholds must be finite")
224
223
 
225
- # Check bounds
226
224
  if allow_epsilon_outside:
227
- # Lenient check: allow tiny epsilon outside [0,1] for internal use
228
- eps = np.finfo(np.float64).eps * 100
229
- if np.any(arr < -eps) or np.any(arr > 1 + eps):
230
- raise ValueError(
231
- f"Thresholds far outside valid range: "
232
- f"[{arr.min():.6f}, {arr.max():.6f}]"
233
- )
225
+ low, high = np.nextafter(0.0, -np.inf), np.nextafter(1.0, np.inf)
234
226
  else:
235
- # Strict check for user-provided thresholds
236
- if np.any(arr < 0) or np.any(arr > 1):
237
- raise ValueError(
238
- f"Thresholds must be in [0, 1], got range "
239
- f"[{arr.min():.3f}, {arr.max():.3f}]"
240
- )
227
+ low, high = 0.0, 1.0
228
+ if np.any(arr < low) or np.any(arr > high):
229
+ allowed = (
230
+ "[0, 1] or its adjacent endpoint cuts"
231
+ if allow_epsilon_outside
232
+ else "[0, 1]"
233
+ )
234
+ raise ValueError(
235
+ f"Thresholds must be in {allowed}, got range "
236
+ f"[{arr.min():.3g}, {arr.max():.3g}]"
237
+ )
241
238
 
242
239
  # Check count
243
240
  if n_classes is not None and len(arr) != n_classes:
@@ -285,6 +282,9 @@ def apply_threshold(
285
282
  Returns:
286
283
  Binary predictions (0 or 1) as int32
287
284
  """
285
+ # Fitting compares float64 scores. With a float32 array, NumPy can
286
+ # otherwise round a Python scalar threshold onto an adjacent score.
287
+ values = np.asarray(values, dtype=np.float64)
288
288
  if comparison == ">=":
289
289
  return (values >= threshold).astype(np.int32)
290
290
  return (values > threshold).astype(np.int32)
@@ -741,7 +741,7 @@ def _validate_threshold_inputs(
741
741
 
742
742
  # Validate threshold
743
743
  if require_proba:
744
- validate_threshold(threshold, allow_epsilon_outside=False)
744
+ validate_threshold(threshold, allow_epsilon_outside=True)
745
745
  else:
746
746
  # For scores, just check it's a finite number
747
747
  if not np.isfinite(threshold):
@@ -1,10 +1,10 @@
1
1
  [build-system]
2
- requires = ["uv_build>=0.12.5,<0.13"]
2
+ requires = ["uv_build>=0.12.5,<0.14"]
3
3
  build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "optimal-classification-cutoffs"
7
- version = "3.0.0"
7
+ version = "3.0.2"
8
8
  description = "Utilities for computing optimal classification cutoffs for binary and multiclass classification"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -50,10 +50,7 @@ module-root = "."
50
50
  [tool.ruff]
51
51
  line-length = 88
52
52
  target-version = "py312"
53
- exclude = [
54
- "docs/",
55
- "*.ipynb",
56
- ]
53
+ exclude = ["docs/"]
57
54
 
58
55
  [tool.ruff.lint]
59
56
  external = ["DOC"]
@@ -165,7 +162,6 @@ exclude = [
165
162
  ".venv",
166
163
  "build",
167
164
  "dist",
168
- '.*\.ipynb$',
169
165
  ]
170
166
  extend_exclude = [
171
167
  "tests",
@@ -183,6 +179,9 @@ psutil = "psutil"
183
179
  DEP004 = ["numba"]
184
180
  DEP003 = ["IPython"]
185
181
 
182
+ [tool.codespell]
183
+ builtin = "clear,rare,en-GB_to_en-US"
184
+
186
185
  [dependency-groups]
187
186
  examples = [
188
187
  "matplotlib",
@@ -195,11 +194,11 @@ docs = [
195
194
  "sphinx>=8",
196
195
  "py-canon @ git+https://github.com/gojiplus/py-canon@v1",
197
196
  "furo",
198
- "myst-nb>=1.1",
197
+ "myst-parser",
199
198
  "sphinx-copybutton",
199
+ "sphinx-gallery>=0.19",
200
200
  "matplotlib",
201
- "pandas",
202
- "ipywidgets",
201
+ "scikit-learn",
203
202
  ]
204
203
  dev = [
205
204
  "ruff>=0.14",
@@ -1,10 +1,10 @@
1
1
  [build-system]
2
- requires = ["uv_build>=0.12.5,<0.13"]
2
+ requires = ["uv_build>=0.12.5,<0.14"]
3
3
  build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "optimal-classification-cutoffs"
7
- version = "3.0.0"
7
+ version = "3.0.2"
8
8
  description = "Utilities for computing optimal classification cutoffs for binary and multiclass classification"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -51,7 +51,6 @@ line-length = 88
51
51
  target-version = "py312"
52
52
  exclude = [
53
53
  "docs/",
54
- "*.ipynb", # Exclude Jupyter notebooks
55
54
  ]
56
55
 
57
56
  [tool.ruff.lint]
@@ -71,7 +70,7 @@ convention = "google"
71
70
 
72
71
  [tool.ruff.lint.per-file-ignores]
73
72
  # Unused fixture arguments and private-member access are how tests are written.
74
- # N802/N806: test names and locals carry the same maths notation as the code
73
+ # N802/N806: test names and locals carry the same math notation as the code
75
74
  # under test (D for the utility denominator, P for a probability matrix).
76
75
  # T201: several suites print diagnostics; pytest captures them.
77
76
  "tests/**" = ["S101", "D", "ARG", "SLF", "B007", "N802", "N803", "N806", "T201", "PT017"]
@@ -126,13 +125,12 @@ docs = [
126
125
  "sphinx>=8",
127
126
  "py-canon @ git+https://github.com/gojiplus/py-canon@v1",
128
127
  "furo",
129
- # myst-nb pulls myst-parser in and renders docs/examples/*.ipynb without
130
- # the pandoc binary nbsphinx required.
131
- "myst-nb>=1.1",
128
+ "myst-parser",
132
129
  "sphinx-copybutton",
130
+ # sphinx-gallery runs the scripts in docs/examples during the build.
131
+ "sphinx-gallery>=0.19",
133
132
  "matplotlib",
134
- "pandas",
135
- "ipywidgets",
133
+ "scikit-learn",
136
134
  ]
137
135
 
138
136
  dev = [
@@ -176,7 +174,7 @@ show-filenames-in-every-violation-message = true
176
174
 
177
175
  [tool.deptry]
178
176
  # Exclude specific paths from analysis
179
- exclude = [".venv", "build", "dist", ".*\\.ipynb$"]
177
+ exclude = [".venv", "build", "dist"]
180
178
  extend_exclude = ["tests", "examples", "docs"]
181
179
  known_first_party = ["optimal_cutoffs"]
182
180
 
@@ -192,3 +190,6 @@ DEP004 = ["numba"]
192
190
 
193
191
  # DEP003: Allow transitive dependencies in examples/notebooks
194
192
  DEP003 = ["IPython"]
193
+
194
+ [tool.codespell]
195
+ builtin = "clear,rare,en-GB_to_en-US"