use std::any::Any;
use super::population_std;
use crate::error::GprError;
pub trait UnfittedTarget: Send + Sync {
fn fit(self: Box<Self>, y: &[f64]) -> Result<Box<dyn TargetTransform>, GprError>;
fn clone_box(&self) -> Box<dyn UnfittedTarget>;
fn as_any(&self) -> &dyn Any;
fn persist_id(&self) -> Option<&'static str> {
None
}
fn persist_state(&self) -> Result<serde_json::Value, GprError> {
Err(GprError::PersistFailed {
kind: crate::error::PersistErrorKind::NotPersistable,
reason: "this target transform does not implement persist_state".to_owned(),
})
}
}
pub trait TargetTransform: Send + Sync {
fn transform(&self, y: &mut [f64]) -> Result<(), GprError>;
fn inverse_transform_mean(&self, mean: &mut [f64]) -> Result<(), GprError>;
fn inverse_transform_variance(&self, var: &mut [f64]) -> Result<(), GprError>;
fn inverse_transform_covariance(&self, cov: &mut [f64]) -> Result<(), GprError> {
self.inverse_transform_variance(cov)
}
fn clone_box(&self) -> Box<dyn TargetTransform>;
fn as_any(&self) -> &dyn Any;
fn persist_id(&self) -> Option<&'static str> {
None
}
fn persist_state(&self) -> Result<serde_json::Value, GprError> {
Err(GprError::PersistFailed {
kind: crate::error::PersistErrorKind::NotPersistable,
reason: "this target transform does not implement persist_state".to_owned(),
})
}
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct IdentityTarget;
impl IdentityTarget {
pub fn fit(self, y: &[f64]) -> Result<Self, GprError> {
crate::data::require_finite(y)?;
Ok(self)
}
}
impl UnfittedTarget for IdentityTarget {
fn fit(self: Box<Self>, y: &[f64]) -> Result<Box<dyn TargetTransform>, GprError> {
(*self).fit(y).map(|t| Box::new(t) as _)
}
fn clone_box(&self) -> Box<dyn UnfittedTarget> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
impl TargetTransform for IdentityTarget {
fn transform(&self, y: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(y)
}
fn inverse_transform_mean(&self, mean: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(mean)
}
fn inverse_transform_variance(&self, var: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(var)
}
fn clone_box(&self) -> Box<dyn TargetTransform> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct StandardizeTarget;
impl StandardizeTarget {
pub fn new() -> Self {
Self
}
pub fn fit(self, y: &[f64]) -> Result<FittedStandardizeTarget, GprError> {
crate::data::require_nonempty(y.len())?;
crate::data::require_finite(y)?;
let n = y.len() as f64;
let mean = y.iter().sum::<f64>() / n;
Ok(FittedStandardizeTarget {
mean,
std: population_std(y, mean),
})
}
}
impl UnfittedTarget for StandardizeTarget {
fn fit(self: Box<Self>, y: &[f64]) -> Result<Box<dyn TargetTransform>, GprError> {
(*self).fit(y).map(|t| Box::new(t) as _)
}
fn clone_box(&self) -> Box<dyn UnfittedTarget> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FittedStandardizeTarget {
mean: f64,
std: f64,
}
impl FittedStandardizeTarget {
pub fn mean(&self) -> f64 {
self.mean
}
pub fn std(&self) -> f64 {
self.std
}
pub(crate) fn from_parts(mean: f64, std: f64) -> Result<Self, GprError> {
if !mean.is_finite() || !std.is_finite() || std <= 0.0 {
return Err(GprError::InvalidHyperparameter {
reason: format!(
"fitted standardize target stats must be finite with positive scale, got mean={mean}, std={std}"
),
});
}
Ok(Self { mean, std })
}
}
impl TargetTransform for FittedStandardizeTarget {
fn transform(&self, y: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(y)?;
let mean = self.mean;
let std = self.std;
for value in y {
*value = (*value - mean) / std;
}
Ok(())
}
fn inverse_transform_mean(&self, mean: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(mean)?;
let loc = self.mean;
let std = self.std;
for value in mean {
*value = loc + std * *value;
}
Ok(())
}
fn inverse_transform_variance(&self, var: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(var)?;
let scale = self.std * self.std;
for value in var {
*value *= scale;
}
Ok(())
}
fn clone_box(&self) -> Box<dyn TargetTransform> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MinMaxTarget {
range_lo: f64,
range_hi: f64,
}
impl MinMaxTarget {
pub fn new() -> Self {
Self {
range_lo: 0.0,
range_hi: 1.0,
}
}
pub fn with_feature_range(lo: f64, hi: f64) -> Result<Self, GprError> {
require_feature_range(lo, hi)?;
Ok(Self {
range_lo: lo,
range_hi: hi,
})
}
pub fn feature_range(&self) -> (f64, f64) {
(self.range_lo, self.range_hi)
}
pub fn fit(self, y: &[f64]) -> Result<FittedMinMaxTarget, GprError> {
crate::data::require_nonempty(y.len())?;
crate::data::require_finite(y)?;
let mut min = y[0];
let mut max = y[0];
for &value in &y[1..] {
if value < min {
min = value;
}
if value > max {
max = value;
}
}
Ok(FittedMinMaxTarget {
data_min: min,
data_max: max,
range_lo: self.range_lo,
range_hi: self.range_hi,
})
}
}
impl Default for MinMaxTarget {
fn default() -> Self {
Self::new()
}
}
impl UnfittedTarget for MinMaxTarget {
fn fit(self: Box<Self>, y: &[f64]) -> Result<Box<dyn TargetTransform>, GprError> {
(*self).fit(y).map(|t| Box::new(t) as _)
}
fn clone_box(&self) -> Box<dyn UnfittedTarget> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FittedMinMaxTarget {
data_min: f64,
data_max: f64,
range_lo: f64,
range_hi: f64,
}
impl FittedMinMaxTarget {
pub fn feature_range(&self) -> (f64, f64) {
(self.range_lo, self.range_hi)
}
pub fn min(&self) -> f64 {
self.data_min
}
pub fn max(&self) -> f64 {
self.data_max
}
fn data_span(&self) -> f64 {
let span = self.data_max - self.data_min;
if span > 0.0 && span.is_finite() {
span
} else {
1.0
}
}
fn out_span(&self) -> f64 {
self.range_hi - self.range_lo
}
pub(crate) fn from_parts(
data_min: f64,
data_max: f64,
range_lo: f64,
range_hi: f64,
) -> Result<Self, GprError> {
require_feature_range(range_lo, range_hi)?;
if !data_min.is_finite() || !data_max.is_finite() {
return Err(GprError::NonFiniteInput);
}
if data_min > data_max {
return Err(GprError::InvalidHyperparameter {
reason: format!(
"fitted min-max target needs data_min <= data_max, got {data_min} > {data_max}"
),
});
}
Ok(Self {
data_min,
data_max,
range_lo,
range_hi,
})
}
}
impl TargetTransform for FittedMinMaxTarget {
fn transform(&self, y: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(y)?;
let min = self.data_min;
let span = self.data_span();
let lo = self.range_lo;
let out_span = self.out_span();
for value in y {
*value = lo + out_span * (*value - min) / span;
}
Ok(())
}
fn inverse_transform_mean(&self, mean: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(mean)?;
let min = self.data_min;
let span = self.data_span();
let lo = self.range_lo;
let out_span = self.out_span();
for value in mean {
*value = min + span * (*value - lo) / out_span;
}
Ok(())
}
fn inverse_transform_variance(&self, var: &mut [f64]) -> Result<(), GprError> {
crate::data::require_finite(var)?;
let scale = self.data_span() / self.out_span();
let scale2 = scale * scale;
for value in var {
*value *= scale2;
}
Ok(())
}
fn clone_box(&self) -> Box<dyn TargetTransform> {
Box::new(*self)
}
fn as_any(&self) -> &dyn Any {
self
}
}
fn require_feature_range(lo: f64, hi: f64) -> Result<(), GprError> {
if !lo.is_finite() || !hi.is_finite() || hi <= lo {
return Err(GprError::InvalidConfig {
reason: format!("feature range must satisfy lo < hi and both finite, got [{lo}, {hi}]"),
});
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::{
FittedMinMaxTarget, FittedStandardizeTarget, IdentityTarget, MinMaxTarget,
StandardizeTarget, TargetTransform,
};
use crate::error::GprError;
const TOL: f64 = 1e-10;
use crate::test_check::{assert_close, assert_send_sync};
#[test]
fn is_send_sync() {
assert_send_sync::<IdentityTarget>();
assert_send_sync::<StandardizeTarget>();
assert_send_sync::<FittedStandardizeTarget>();
assert_send_sync::<MinMaxTarget>();
assert_send_sync::<FittedMinMaxTarget>();
}
#[test]
fn identity_is_a_no_op() {
let t = IdentityTarget.fit(&[1.0, 2.0]).expect("finite");
let mut y = [1.0, 2.0];
t.transform(&mut y).expect("finite");
assert_close(y[0], 1.0, TOL);
assert_close(y[1], 2.0, TOL);
t.inverse_transform_mean(&mut y).expect("finite");
t.inverse_transform_variance(&mut y).expect("finite");
assert_close(y[0], 1.0, TOL);
assert_close(y[1], 2.0, TOL);
}
#[test]
fn standardize_centers_and_unit_scales() {
let y = [1.0, 3.0, 5.0];
let t = StandardizeTarget::new().fit(&y).expect("valid");
assert_close(t.mean(), 3.0, TOL);
assert_close(t.std(), (8.0 / 3.0_f64).sqrt(), TOL);
let mut z = y;
t.transform(&mut z).expect("finite");
let z_mean = z.iter().sum::<f64>() / 3.0;
assert_close(z_mean, 0.0, TOL);
let z_var = z.iter().map(|v| v * v).sum::<f64>() / 3.0;
assert_close(z_var, 1.0, TOL);
}
#[test]
fn inverse_mean_recovers_original_targets() {
let y = [1.0, 3.0, 5.0];
let t = StandardizeTarget::new().fit(&y).expect("valid");
let mut z = y;
t.transform(&mut z).expect("finite");
t.inverse_transform_mean(&mut z).expect("finite");
assert_close(z[0], y[0], TOL);
assert_close(z[1], y[1], TOL);
assert_close(z[2], y[2], TOL);
}
#[test]
fn inverse_variance_is_std_squared() {
let y = [1.0, 3.0, 5.0];
let t = StandardizeTarget::new().fit(&y).expect("valid");
let s = t.std();
let mut var = [0.25, 1.0, 4.0];
t.inverse_transform_variance(&mut var).expect("finite");
assert_close(var[0], 0.25 * s * s, TOL);
assert_close(var[1], 1.0 * s * s, TOL);
assert_close(var[2], 4.0 * s * s, TOL);
}
#[test]
fn inverse_covariance_is_std_squared() {
let y = [1.0, 3.0, 5.0];
let t = StandardizeTarget::new().fit(&y).expect("valid");
let s = t.std();
let mut cov = [1.0, 0.5, 0.5, 4.0];
t.inverse_transform_covariance(&mut cov).expect("finite");
let s2 = s * s;
assert_close(cov[0], 1.0 * s2, TOL);
assert_close(cov[1], 0.5 * s2, TOL);
assert_close(cov[2], 0.5 * s2, TOL);
assert_close(cov[3], 4.0 * s2, TOL);
}
#[test]
fn affine_closed_form_matches_unstandardized_scale() {
let t = StandardizeTarget::new()
.fit(&[2.0, 4.0, 6.0, 8.0])
.expect("valid");
let mu = t.mean();
let s = t.std();
let mut mean = [0.0, 1.0, -0.5];
let mut var = [1.0, 0.25, 4.0];
t.inverse_transform_mean(&mut mean).expect("finite");
t.inverse_transform_variance(&mut var).expect("finite");
assert_close(mean[0], mu, TOL);
assert_close(mean[1], mu + s, TOL);
assert_close(mean[2], mu - 0.5 * s, TOL);
assert_close(var[0], s * s, TOL);
assert_close(var[1], 0.25 * s * s, TOL);
assert_close(var[2], 4.0 * s * s, TOL);
}
#[test]
fn constant_target_uses_unit_scale() {
let t = StandardizeTarget::new()
.fit(&[4.0, 4.0, 4.0])
.expect("valid");
assert_close(t.mean(), 4.0, TOL);
assert_close(t.std(), 1.0, TOL);
let mut y = [4.0, 4.0];
t.transform(&mut y).expect("finite");
assert_close(y[0], 0.0, TOL);
t.inverse_transform_mean(&mut y).expect("finite");
assert_close(y[0], 4.0, TOL);
}
#[test]
fn standardize_rejects_empty_and_non_finite() {
let t = StandardizeTarget::new();
assert!(matches!(t.fit(&[]), Err(GprError::EmptyInput)));
assert!(matches!(
StandardizeTarget::new().fit(&[1.0, f64::NAN]),
Err(GprError::NonFiniteInput)
));
}
#[test]
fn identity_rejects_non_finite() {
assert!(matches!(
IdentityTarget.fit(&[f64::INFINITY]),
Err(GprError::NonFiniteInput)
));
}
#[test]
fn minmax_scales_and_inverts() {
let y = [1.0, 3.0, 5.0];
let t = MinMaxTarget::new().fit(&y).expect("valid");
assert_close(t.min(), 1.0, TOL);
assert_close(t.max(), 5.0, TOL);
let mut z = y;
t.transform(&mut z).expect("finite");
assert_close(z[0], 0.0, TOL);
assert_close(z[1], 0.5, TOL);
assert_close(z[2], 1.0, TOL);
t.inverse_transform_mean(&mut z).expect("finite");
assert_close(z[0], y[0], TOL);
assert_close(z[1], y[1], TOL);
assert_close(z[2], y[2], TOL);
let mut var = [1.0, 0.25];
t.inverse_transform_variance(&mut var).expect("finite");
assert_close(var[0], 16.0, TOL);
assert_close(var[1], 4.0, TOL);
}
#[test]
fn minmax_constant_target_maps_to_lo() {
let t = MinMaxTarget::new().fit(&[4.0, 4.0, 4.0]).expect("valid");
let mut y = [4.0, 4.0];
t.transform(&mut y).expect("finite");
assert_close(y[0], 0.0, TOL);
t.inverse_transform_mean(&mut y).expect("finite");
assert_close(y[0], 4.0, TOL);
}
#[test]
fn minmax_target_rejects() {
assert!(MinMaxTarget::with_feature_range(1.0, 0.0).is_err());
}
#[test]
fn fitted_min_max_target_rejects_reversed_extrema() {
assert!(matches!(
FittedMinMaxTarget::from_parts(2.0, 1.0, 0.0, 1.0),
Err(GprError::InvalidHyperparameter { .. })
));
assert!(FittedMinMaxTarget::from_parts(1.0, 1.0, 0.0, 1.0).is_ok());
assert!(FittedMinMaxTarget::from_parts(1.0, 2.0, 0.0, 1.0).is_ok());
}
}