use crate::api::ModelError;
use crate::data::BinaryTargets;
use crate::loss::{BinaryLogLoss, accumulate_newton_row, newton_decrement, raw_score};
use crate::numeric::{sigmoid_f32, sum_in_order};
use super::Calibrator;
#[derive(Clone, Debug, PartialEq)]
pub struct PlattParams {
max_iter: usize,
tol: f32,
}
impl Default for PlattParams {
fn default() -> Self {
Self {
max_iter: 100,
tol: 1.0e-6,
}
}
}
impl PlattParams {
#[must_use]
pub fn with_max_iter(mut self, max_iter: usize) -> Self {
self.max_iter = max_iter;
self
}
#[must_use]
pub fn with_tol(mut self, tol: f32) -> Self {
self.tol = tol;
self
}
pub const fn max_iter(&self) -> usize {
self.max_iter
}
pub const fn tol(&self) -> f32 {
self.tol
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct PlattCalibrator {
slope: f32,
intercept: f32,
centre: f32,
centred_intercept: f32,
params: PlattParams,
iterations: usize,
}
impl PlattCalibrator {
pub fn fit(
scores: &[f32],
targets: &BinaryTargets,
params: PlattParams,
) -> Result<Self, ModelError> {
validate_params(¶ms)?;
super::validate_calibration_sample(scores, targets)?;
let positives = targets
.as_slice()
.iter()
.filter(|&&label| label == 1)
.count();
let negatives = targets.len() - positives;
let high = (positives as f64 + 1.0) / (positives as f64 + 2.0);
let low = 1.0 / (negatives as f64 + 2.0);
let mut theta = [0.0_f64; PARAMETERS];
let mut gradient = [0.0_f64; PARAMETERS];
let mut hessian = [0.0_f64; PARAMETERS * PARAMETERS];
let mut iterations = 0;
let mut converged = false;
let mut decrement = f64::INFINITY;
for iteration in 0..params.max_iter {
gradient.fill(0.0);
hessian.fill(0.0);
for (&score, &label) in scores.iter().zip(targets.as_slice()) {
let design_row = [f64::from(score), 1.0];
let target = if label == 1 { high } else { low };
let raw = raw_score(&theta, &design_row, 1, Some(1));
accumulate_newton_row::<BinaryLogLoss>(
&design_row,
raw,
target,
1.0,
&mut gradient,
&mut hessian,
);
}
let update = solve_symmetric_2x2(&hessian, &gradient)?;
let max_update = update
.iter()
.fold(0.0_f64, |max, value| max.max(value.abs()));
decrement = newton_decrement(&gradient, &update);
for (value, step) in theta.iter_mut().zip(update) {
*value -= step;
}
iterations = iteration + 1;
if max_update <= f64::from(params.tol) {
converged = true;
break;
}
}
let certified = decrement <= f64::from(params.tol);
if !converged && !certified {
return Err(ModelError::SolverDidNotConverge { iterations });
}
let slope = theta[0] as f32;
let intercept = theta[1] as f32;
let centre = (sum_in_order(scores.iter().map(|&score| f64::from(score)))
/ scores.len() as f64) as f32;
let centred_intercept = (theta[1] + theta[0] * f64::from(centre)) as f32;
if !slope.is_finite()
|| !intercept.is_finite()
|| !centre.is_finite()
|| !centred_intercept.is_finite()
{
return Err(ModelError::LinearSolveFailed);
}
Ok(Self {
slope,
intercept,
centre,
centred_intercept,
params,
iterations,
})
}
pub const fn slope(&self) -> f32 {
self.slope
}
pub const fn intercept(&self) -> f32 {
self.intercept
}
pub const fn get_params(&self) -> &PlattParams {
&self.params
}
pub const fn n_iter(&self) -> usize {
self.iterations
}
pub fn decision_score(&self, score: f32) -> f32 {
self.slope
.mul_add(score - self.centre, self.centred_intercept)
}
}
const PARAMETERS: usize = 2;
fn validate_params(params: &PlattParams) -> Result<(), ModelError> {
if params.max_iter == 0 {
return Err(ModelError::InvalidIterationCount);
}
if !params.tol.is_finite() || params.tol <= 0.0 {
return Err(ModelError::InvalidTolerance);
}
Ok(())
}
fn solve_symmetric_2x2(hessian: &[f64], gradient: &[f64]) -> Result<[f64; 2], ModelError> {
let (a, b, d) = (hessian[0], hessian[2], hessian[3]);
let determinant = a * d - b * b;
if !determinant.is_finite() || determinant <= 0.0 {
return Err(ModelError::LinearSolveFailed);
}
let update = [
(d * gradient[0] - b * gradient[1]) / determinant,
(a * gradient[1] - b * gradient[0]) / determinant,
];
if update.iter().any(|value| !value.is_finite()) {
return Err(ModelError::LinearSolveFailed);
}
Ok(update)
}
impl Calibrator for PlattCalibrator {
fn calibrate(&self, score: f32) -> f32 {
sigmoid_f32(self.decision_score(score))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::loss::Objective;
fn sample() -> (Vec<f32>, BinaryTargets) {
let scores = vec![
0.05_f32, 0.12, 0.18, 0.25, 0.31, 0.44, 0.52, 0.58, 0.63, 0.71, 0.77, 0.84, 0.90, 0.95,
];
let labels = vec![0, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1, 1, 1, 1];
(scores, BinaryTargets::new(labels).unwrap())
}
fn objective(scores: &[f32], targets: &[f64], slope: f64, intercept: f64) -> f64 {
scores
.iter()
.zip(targets)
.map(|(&score, &target)| {
BinaryLogLoss::value(slope * f64::from(score) + intercept, target)
})
.sum()
}
fn corrected_targets(targets: &BinaryTargets) -> Vec<f64> {
let positives = targets
.as_slice()
.iter()
.filter(|&&label| label == 1)
.count();
let negatives = targets.len() - positives;
let high = (positives as f64 + 1.0) / (positives as f64 + 2.0);
let low = 1.0 / (negatives as f64 + 2.0);
targets
.as_slice()
.iter()
.map(|&label| if label == 1 { high } else { low })
.collect()
}
#[test]
fn the_fit_is_a_stationary_point_of_the_objective_it_claims_to_minimize() {
let (scores, targets) = sample();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
let corrected = corrected_targets(&targets);
let (slope, intercept) = (f64::from(fitted.slope()), f64::from(fitted.intercept()));
let step = 1.0e-5;
let base = objective(&scores, &corrected, slope, intercept);
let d_slope = (objective(&scores, &corrected, slope + step, intercept)
- objective(&scores, &corrected, slope - step, intercept))
/ (2.0 * step);
let d_intercept = (objective(&scores, &corrected, slope, intercept + step)
- objective(&scores, &corrected, slope, intercept - step))
/ (2.0 * step);
assert!(d_slope.abs() <= 1.0e-4, "slope gradient {d_slope}");
assert!(
d_intercept.abs() <= 1.0e-4,
"intercept gradient {d_intercept}"
);
for (delta_slope, delta_intercept) in [
(1.0e-2, 0.0),
(-1.0e-2, 0.0),
(0.0, 1.0e-2),
(0.0, -1.0e-2),
(1.0e-2, 1.0e-2),
(-1.0e-2, 1.0e-2),
] {
let neighbour = objective(
&scores,
&corrected,
slope + delta_slope,
intercept + delta_intercept,
);
assert!(
neighbour > base,
"neighbour ({delta_slope}, {delta_intercept}) scored {neighbour} against {base}"
);
}
}
#[test]
fn a_separable_sample_still_has_a_finite_fit() {
let scores: Vec<f32> = (0..20).map(|step| step as f32 * 0.1).collect();
let labels: Vec<u8> = (0..20).map(|step| u8::from(step >= 10)).collect();
let targets = BinaryTargets::new(labels).unwrap();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
assert!(fitted.slope().is_finite() && fitted.intercept().is_finite());
assert!(
fitted.slope() > 0.0,
"slope {} is not positive",
fitted.slope()
);
assert!(fitted.n_iter() < fitted.get_params().max_iter());
for &score in &scores {
let probability = fitted.calibrate(score);
assert!(
probability > 0.0 && probability < 1.0,
"score {score} calibrated to {probability}"
);
}
}
#[test]
fn the_calibrated_map_is_monotone_in_the_score() {
let (scores, targets) = sample();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
assert!(fitted.slope() > 0.0);
let mut previous = f32::NEG_INFINITY;
for step in -100..=200 {
let probability = fitted.calibrate(step as f32 * 0.01);
assert!(probability >= previous, "map decreased at {step}");
assert!((0.0..=1.0).contains(&probability));
previous = probability;
}
let flipped: Vec<f32> = scores.iter().map(|score| -score).collect();
let mirrored = PlattCalibrator::fit(&flipped, &targets, PlattParams::default()).unwrap();
assert!(mirrored.slope() < 0.0);
assert!((mirrored.slope() + fitted.slope()).abs() <= 1.0e-4);
}
#[test]
fn the_slope_takes_the_sign_of_the_calibration_sample_s_class_mean_gap() {
let scores = [0.05_f32, 0.2, 0.4, 0.55, 0.7, 0.9];
let mut fitted = 0;
let mut positive = 0;
let mut negative = 0;
for mask in 1_u32..(1 << scores.len()) - 1 {
let labels: Vec<u8> = (0..scores.len())
.map(|index| u8::from(mask >> index & 1 == 1))
.collect();
let targets = BinaryTargets::new(labels.clone()).unwrap();
let fit = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
let mut sums = [0.0_f64; 2];
let mut counts = [0_usize; 2];
for (&score, &label) in scores.iter().zip(&labels) {
sums[usize::from(label)] += f64::from(score);
counts[usize::from(label)] += 1;
}
let gap = sums[1] / counts[1] as f64 - sums[0] / counts[0] as f64;
fitted += 1;
assert_eq!(
gap > 0.0,
fit.slope() > 0.0,
"labels {labels:?}: mean gap {gap} against slope {}",
fit.slope()
);
if gap > 0.0 {
positive += 1;
} else {
negative += 1;
}
}
assert_eq!(fitted, (1 << scores.len()) - 2);
assert!(
positive > 0 && negative > 0,
"{positive} against {negative}"
);
}
#[test]
fn refitting_the_same_sample_reproduces_the_same_parameters() {
let (scores, targets) = sample();
let first = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
let second = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
assert_eq!(first, second);
assert_eq!(first.slope().to_bits(), second.slope().to_bits());
assert_eq!(first.intercept().to_bits(), second.intercept().to_bits());
}
#[test]
fn undefined_and_invalid_inputs_are_reported_rather_than_fitted() {
let (scores, targets) = sample();
assert_eq!(
PlattCalibrator::fit(&scores, &targets, PlattParams::default().with_max_iter(0)),
Err(ModelError::InvalidIterationCount)
);
assert_eq!(
PlattCalibrator::fit(&scores, &targets, PlattParams::default().with_tol(0.0)),
Err(ModelError::InvalidTolerance)
);
assert_eq!(
PlattCalibrator::fit(&scores, &targets, PlattParams::default().with_tol(f32::NAN)),
Err(ModelError::InvalidTolerance)
);
assert_eq!(
PlattCalibrator::fit(
&[0.1, 0.2, 0.3],
&BinaryTargets::new(vec![1, 1, 1]).unwrap(),
PlattParams::default()
),
Err(ModelError::RequiresTwoClasses)
);
assert_eq!(
PlattCalibrator::fit(
&[0.1, 0.2],
&BinaryTargets::new(vec![0, 1, 1]).unwrap(),
PlattParams::default()
),
Err(ModelError::TargetLength {
rows: 2,
targets: 3,
})
);
assert_eq!(
PlattCalibrator::fit(
&[],
&BinaryTargets::new(vec![0, 1]).unwrap(),
PlattParams::default()
),
Err(ModelError::EmptyData)
);
assert_eq!(
PlattCalibrator::fit(
&[0.1, f32::INFINITY],
&BinaryTargets::new(vec![0, 1]).unwrap(),
PlattParams::default()
),
Err(ModelError::NonFiniteFeature { row: 1, column: 0 })
);
}
#[test]
fn a_constant_score_column_is_reported_instead_of_solved() {
let scores = [0.5_f32; 8];
let targets = BinaryTargets::new(vec![0, 1, 0, 1, 0, 1, 0, 1]).unwrap();
assert_eq!(
PlattCalibrator::fit(&scores, &targets, PlattParams::default()),
Err(ModelError::LinearSolveFailed)
);
}
fn conditioned_minimizer(scores: &[f32], targets: &[f64]) -> (f64, f64) {
let rows = scores.len() as f64;
let mean = scores.iter().map(|&s| f64::from(s)).sum::<f64>() / rows;
let variance = scores
.iter()
.map(|&s| (f64::from(s) - mean).powi(2))
.sum::<f64>()
/ rows;
let scale = variance.sqrt();
assert!(scale > 0.0, "a constant column has no conditioned form");
let centred: Vec<f64> = scores
.iter()
.map(|&s| (f64::from(s) - mean) / scale)
.collect();
let mut theta = [0.0_f64; PARAMETERS];
for _ in 0..100 {
let mut gradient = [0.0_f64; PARAMETERS];
let mut hessian = [0.0_f64; PARAMETERS * PARAMETERS];
for (&value, &target) in centred.iter().zip(targets) {
let design_row = [value, 1.0];
let raw = raw_score(&theta, &design_row, 1, Some(1));
accumulate_newton_row::<BinaryLogLoss>(
&design_row,
raw,
target,
1.0,
&mut gradient,
&mut hessian,
);
}
let update = solve_symmetric_2x2(&hessian, &gradient).expect("conditioned solve");
for (value, step) in theta.iter_mut().zip(update) {
*value -= step;
}
let largest = update.iter().fold(0.0_f64, |max, v| max.max(v.abs()));
if largest <= 1.0e-14 * theta.iter().fold(1.0_f64, |max, v| max.max(v.abs())) {
break;
}
}
(theta[0] / scale, theta[1] - theta[0] * mean / scale)
}
fn near_constant_neighbourhood() -> Vec<(Vec<f32>, BinaryTargets)> {
let mut state = 0x0517_2026_0726_0001_u64;
let mut next = move || {
state = state
.wrapping_mul(6_364_136_223_846_793_005)
.wrapping_add(1_442_695_040_888_963_407);
(state >> 33) as u32
};
let mut cases = Vec::new();
for base in [0.5_f64, 0.0, -3.0, 10.0] {
for exponent in 4..=8_i32 {
let spread = 10.0_f64.powi(-exponent);
for rows in [4_usize, 5, 7, 9, 13, 16] {
for _ in 0..4 {
let scores: Vec<f32> = (0..rows)
.map(|_| {
let unit = f64::from(next()) / f64::from(1_u32 << 31) / 2.0;
(base + spread * (unit - 0.5)) as f32
})
.collect();
let mut labels: Vec<u8> = (0..rows).map(|_| (next() & 1) as u8).collect();
labels[0] = 1;
labels[rows - 1] = 0;
cases.push((scores, BinaryTargets::new(labels).unwrap()));
}
}
}
}
cases
}
#[test]
fn a_near_constant_score_column_that_reaches_its_minimum_is_fitted_not_refused() {
let cases = near_constant_neighbourhood();
let mut fitted = 0_usize;
let mut exhausted = 0_usize;
let mut singular = 0_usize;
for (index, (scores, targets)) in cases.iter().enumerate() {
match PlattCalibrator::fit(scores, targets, PlattParams::default()) {
Ok(fit) => {
fitted += 1;
if fit.n_iter() == fit.get_params().max_iter() {
exhausted += 1;
}
assert!(
fit.slope().is_finite() && fit.intercept().is_finite(),
"case {index} fitted a non-finite map: {scores:?}"
);
}
Err(ModelError::LinearSolveFailed) => singular += 1,
Err(other) => panic!("case {index} was refused with {other:?}: {scores:?}"),
}
}
assert_eq!(fitted + singular, cases.len());
assert!(
exhausted * 4 >= fitted,
"only {exhausted} of {fitted} fits exhausted max_iter, so this region no \
longer exercises the acceptance path at all"
);
}
#[test]
fn the_same_region_is_refused_when_the_budget_really_is_too_short() {
let cases = near_constant_neighbourhood();
let mut reachable = 0_usize;
let mut refused = 0_usize;
for (scores, targets) in &cases {
if PlattCalibrator::fit(scores, targets, PlattParams::default()).is_err() {
continue;
}
reachable += 1;
if let Err(error) =
PlattCalibrator::fit(scores, targets, PlattParams::default().with_max_iter(1))
{
assert_eq!(error, ModelError::SolverDidNotConverge { iterations: 1 });
refused += 1;
}
}
assert!(reachable > 0, "the region produced no fits to starve");
assert!(
refused * 10 >= reachable * 9,
"only {refused} of {reachable} single-iteration fits were refused; an \
acceptance rule this permissive would accept anything"
);
}
#[test]
fn an_exhausted_budget_reports_the_iterations_it_spent() {
let (scores, targets) = sample();
for budget in [1_usize, 2] {
assert_eq!(
PlattCalibrator::fit(
&scores,
&targets,
PlattParams::default().with_max_iter(budget)
),
Err(ModelError::SolverDidNotConverge { iterations: budget })
);
}
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default())
.expect("the same sample fits with its default budget");
assert!(fitted.n_iter() < fitted.get_params().max_iter());
}
#[test]
fn the_reported_near_constant_case_fits_the_parameters_it_always_did() {
let scores = [0.4999987_f32, 0.49999943, 0.50000125, 0.50000066];
let targets = BinaryTargets::new(vec![1, 1, 0, 0]).unwrap();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default())
.expect("a converged iterate whose step floor is above tol is still a fit");
assert_eq!(fitted.n_iter(), 100);
assert_eq!(fitted.slope().to_bits(), (-1_055_545.6_f32).to_bits());
assert_eq!(fitted.intercept().to_bits(), 527_772.8_f32.to_bits());
let corrected = corrected_targets(&targets);
let (slope, intercept) = conditioned_minimizer(&scores, &corrected);
assert_eq!(fitted.slope().to_bits(), (slope as f32).to_bits());
assert_eq!(fitted.intercept().to_bits(), (intercept as f32).to_bits());
}
#[test]
fn a_near_constant_fit_evaluates_the_probability_its_solve_found() {
let cases = near_constant_neighbourhood();
let mut checked = 0_usize;
let mut worst = 0.0_f64;
for (index, (scores, targets)) in cases.iter().enumerate() {
let Ok(fitted) = PlattCalibrator::fit(scores, targets, PlattParams::default()) else {
continue;
};
let corrected = corrected_targets(targets);
let (slope, intercept) = conditioned_minimizer(scores, &corrected);
for &score in scores {
let truth = 1.0 / (1.0 + (-(slope * f64::from(score) + intercept)).exp());
let error = (f64::from(fitted.calibrate(score)) - truth).abs();
worst = worst.max(error);
assert!(
error <= 1.0e-6,
"case {index} at score {score} calibrated to {} against {truth}",
fitted.calibrate(score)
);
}
checked += 1;
}
assert!(
checked >= 150,
"only {checked} fits were checked; the near-constant region no longer covers \
the cancellation this test exists for"
);
let extreme = cases
.iter()
.filter_map(|(scores, targets)| {
PlattCalibrator::fit(scores, targets, PlattParams::default()).ok()
})
.filter(|fit| fit.slope().abs() >= 1.0e5)
.count();
assert!(
extreme >= 100,
"only {extreme} fits reached a slope of 1e5, so this region no longer forces \
the cancellation the centred storage removes"
);
println!("worst calibrated probability error {worst:.3e}");
}
#[test]
fn subtracting_the_centre_keeps_its_error_relative() {
let cases = near_constant_neighbourhood();
let mut checked = 0_usize;
let mut exact = 0_usize;
let mut rounded = 0_usize;
for (scores, targets) in &cases {
if PlattCalibrator::fit(scores, targets, PlattParams::default()).is_err() {
continue;
}
let rows = scores.len() as f64;
let centre = (scores.iter().map(|&s| f64::from(s)).sum::<f64>() / rows) as f32;
for &score in scores {
let narrow = f64::from(score - centre);
let wide = f64::from(score) - f64::from(centre);
let sterbenz = score == centre
|| (score / centre >= 0.5 && score / centre <= 2.0)
|| (centre / score >= 0.5 && centre / score <= 2.0);
if narrow == wide {
exact += 1;
} else {
assert!(
!sterbenz,
"Sterbenz's precondition held for score {score} and centre \
{centre} but the subtraction rounded"
);
rounded += 1;
}
assert!(
(narrow - wide).abs() <= f64::from(f32::EPSILON) * wide.abs() * 0.5,
"score {score} minus centre {centre} rounded beyond half an ulp"
);
}
checked += 1;
}
assert!(checked >= 150, "only {checked} samples were checked");
assert!(
exact > 0 && rounded > 0,
"{exact} exact against {rounded} rounded; the region no longer contains both \
cases, so one half of this test proves nothing"
);
}
#[test]
fn the_intercept_accessor_is_still_the_raw_score_at_a_score_of_zero() {
let (scores, targets) = sample();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
let at_zero = fitted.decision_score(0.0);
assert!(
(at_zero - fitted.intercept()).abs() <= 4.0 * f32::EPSILON * at_zero.abs().max(1.0),
"decision_score(0) = {at_zero} against intercept {}",
fitted.intercept()
);
for &score in &scores {
let by_accessors = fitted.slope().mul_add(score, fitted.intercept());
assert!(
(by_accessors - fitted.decision_score(score)).abs()
<= 1.0e-4 * by_accessors.abs().max(1.0),
"score {score}: {by_accessors} against {}",
fitted.decision_score(score)
);
}
}
#[test]
fn the_decision_score_is_the_logit_of_the_calibrated_probability() {
let (scores, targets) = sample();
let fitted = PlattCalibrator::fit(&scores, &targets, PlattParams::default()).unwrap();
for &score in &scores {
let raw = fitted.decision_score(score);
assert_eq!(fitted.calibrate(score), sigmoid_f32(raw));
let probability = f64::from(fitted.calibrate(score));
assert!(
(f64::from(raw) - (probability / (1.0 - probability)).ln()).abs() <= 1.0e-5,
"score {score}"
);
}
}
}