1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
//! Post-hoc probability calibration around an already-fitted classifier.
//!
//! FerricML gates model quality on Brier score and log loss, which is a claim
//! that probability quality matters. This module is the remedy for a model that
//! ranks well but whose probabilities are miscalibrated — forests and boosted
//! ensembles in particular.
//!
//! # What a calibrator is
//!
//! A [`Calibrator`] is a fitted monotone map of one raw model score onto a
//! probability. Two are shipped: [`IsotonicRegression`], which is
//! non-parametric and assumes only monotonicity, and [`PlattCalibrator`], which
//! is a one-dimensional logistic fit through the crate's shared objective
//! contract. Both are deterministic functions of the calibration sample alone.
//!
//! # Boundaries
//!
//! - Calibration reaches a wrapped model only through the public
//! [`ProbabilisticClassifier`](crate::api::ProbabilisticClassifier) contract,
//! so it works for a model FerricML does not ship and names no estimator
//! family. `scripts/check_source_layout.py` enforces that mechanically.
//! - The score being calibrated is the wrapped model's **positive-class
//! probability**, which is the one score that contract requires. A classifier
//! that declares no probability is outside the wrapper's bound entirely, so
//! there is no case where it has to invent one. Calibrating a raw decision
//! function instead is the classical formulation, but `decision_function` is
//! an inherent method of one estimator rather than part of any classifier
//! contract, so a generic wrapper cannot reach it.
//! [`Capabilities::decision_function`] records which types have one, which is
//! what a consumer selecting its behavior at compile time reads.
//!
//! [`Capabilities::decision_function`]: crate::api::Capabilities::decision_function
//! - The calibration sample is supplied by the caller and is never taken from
//! the wrapped model's own training rows implicitly. A calibrator fitted on
//! the rows its model was trained on measures the model's memory, not its
//! probabilities, and FerricML makes that the caller's explicit choice.
pub use CalibratedClassifier;
pub use ;
pub use ;
use crateModelError;
use crateBinaryTargets;
/// A fitted monotone map of one model score onto a calibrated probability.
///
/// Implementations are stateless functions of their fitted parameters: the same
/// score always produces the same probability, with no interior mutability and
/// no dependence on call order. The map must be monotone in the score.
///
/// # What monotone does and does not guarantee
///
/// Monotone is strictly weaker than ranking-preserving, and the gap is not a
/// technicality: both shipped calibrators reach it on calibration samples a
/// caller can plausibly supply.
///
/// - A **strictly increasing** map preserves the ranking of any two rows
/// exactly, so a threshold-sweeping score such as ROC AUC is unchanged.
/// [`PlattCalibrator`] is this case exactly when its fitted
/// [`slope`](PlattCalibrator::slope) is positive.
/// - A **non-decreasing** map may send two distinct scores to one value. It
/// never inverts a pair, but a pair it ties no longer contributes a full
/// correct ordering, so ROC AUC is not guaranteed unchanged.
/// [`IsotonicRegression`] is this case whenever pool-adjacent-violators
/// pools; pooled into one block it is constant and ROC AUC becomes `0.5`.
/// - A **decreasing** map is monotone too, and reverses every pairwise
/// comparison: ROC AUC becomes `1.0 - auc`. `PlattCalibrator` is this case
/// whenever its fitted slope is negative, which is the maximum-likelihood
/// answer for a calibration sample whose positive rows carry a *lower* mean
/// score than its negative rows.
///
/// So calibration changes *how confident* a prediction is, and on a calibration
/// sample that disagrees with the wrapped model it can also change *which way
/// round* two rows are ordered. The fitted parameters are public because that
/// check is the caller's: `PlattCalibrator::slope` and
/// [`IsotonicRegression::values`] say which of the three cases a fit landed in.
/// Neither is rejected at fit time, because a sample that inverts the model's
/// ranking is a fact about the sample rather than a failure of the fit.
///
/// The trait is open so a caller can supply a calibration family FerricML does
/// not ship. Such a calibrator composes with [`CalibratedClassifier`] for
/// prediction; the capability declaration on the composition is written per
/// shipped calibrator, because what a composition can do depends on which
/// calibrator it holds, so a caller-defined one carries no declaration.
/// Validates a `(scores, labels)` calibration sample before any fitting work.
///
/// Stated once here so both calibrators reject the same undefined cases in the
/// same order: empty, mismatched, non-finite, single-class.