Skip to main content

xsf/scipy_special/
boxcox.rs

1// ported from `scipy/special/_boxcox.pxd`
2
3const MIN_ABS_LAMBDA: f64 = 1e-19;
4const MAX_ABS_LAMBDA: f64 = 1e+273;
5const MIN_ABS_LOG_X: f64 = 1e-289;
6const LOG_F64_MAX: f64 = 709.78;
7const SQRT_F64_MIN_POSITIVE: f64 = 1.49e-154;
8
9/// Box-Cox transformation
10///
11/// The Box-Cox transformation is:
12///
13/// - `x.ln()` if `lambda == 0.0`
14/// - `(x.powf(lambda) - 1.0) / lambda` if `lambda != 0.0`
15///
16/// Returns [`f64::NAN`] if `x < 0.0`.
17/// Returns [`f64::NEG_INFINITY`] if `x == 0.0 && lambda < 0.0`.
18///
19/// Corresponds to [`scipy.special.boxcox`][scipy].
20///
21/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.boxcox.html
22///
23/// # See also
24/// - [`inv_boxcox`]: Inverse of the Box-Cox transformation
25/// - [`boxcox1p`]: Box-Cox transformation of 1 + `x`
26#[must_use]
27#[inline]
28pub fn boxcox(x: f64, lambda: f64) -> f64 {
29    // if lmbda << 1 and x.ln() < 1.0, the lmbda*x.ln() product can lose
30    // precision, furthermore, expm1(x) == x for x < eps.
31    // For f64, the range of log is -744.44 to +709.78, with eps being
32    // the smallest value produced. This range means that we will have
33    // abs(lmbda)*x.ln() < eps whenever abs(lmbda) <= eps/-log(min double)
34    // which is ~2.98e-19.
35    let abs_lambda = lambda.abs();
36    if abs_lambda < MIN_ABS_LAMBDA {
37        return x.ln();
38    }
39
40    let lambda_log_x = lambda * x.ln();
41    if lambda_log_x < LOG_F64_MAX {
42        lambda_log_x.exp_m1() / lambda
43    } else {
44        1.0_f64.copysign(lambda) * (lambda_log_x - abs_lambda.ln()).exp() - 1.0 / lambda
45    }
46}
47
48/// Box-Cox transformation of 1 + `x`
49///
50/// For small `x` and `lambda`, this transformation is more numerically stable than [`boxcox`].
51///
52/// Returns [`f64::NAN`] if `x < -1.0`.
53/// Returns [`f64::NEG_INFINITY`] if `x == -1.0 && lambda < 0.0`.
54///
55/// Corresponds to [`scipy.special.boxcox1p`][scipy].
56///
57/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.boxcox1p.html
58///
59/// # See also
60/// - [`inv_boxcox1p`]: Inverse of the Box-Cox transformation of 1 + `x`
61/// - [`boxcox`]: Box-Cox transformation of `x`
62#[doc(alias = "boxcox_1p")]
63#[must_use]
64#[inline]
65pub fn boxcox1p(x: f64, lambda: f64) -> f64 {
66    // The argument given above in boxcox applies here with the modification
67    // that the smallest value produced by log1p is the minimum representable
68    // value, rather than eps.  The second condition here prevents underflow
69    // when log1p(x) is < eps.
70    let log_x = x.ln_1p();
71    let abs_lambda = lambda.abs();
72    if abs_lambda < MIN_ABS_LAMBDA || (abs_lambda < MAX_ABS_LAMBDA && log_x.abs() < MIN_ABS_LOG_X) {
73        return log_x;
74    }
75
76    let lambda_log_x = lambda * log_x;
77    if lambda_log_x < LOG_F64_MAX {
78        lambda_log_x.exp_m1() / lambda
79    } else {
80        1.0_f64.copysign(lambda) * (lambda_log_x - abs_lambda.ln()).exp() - 1.0 / lambda
81    }
82}
83
84/// Inverse of the Box-Cox transformation
85///
86/// Compute the compositional inverse of `y = boxcox(x, lambda)` for `x`.
87///
88/// Corresponds to [`scipy.special.inv_boxcox`][scipy].
89///
90/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.inv_boxcox.html
91///
92/// # See also
93/// - [`boxcox`]: Box-Cox transformation of `x`
94/// - [`inv_boxcox1p`]: Inverse of the Box-Cox transformation of `1 + x`
95#[doc(alias = "boxcox_inv")]
96#[must_use]
97#[inline]
98pub fn inv_boxcox(y: f64, lambda: f64) -> f64 {
99    if lambda == 0.0 {
100        return y.exp();
101    }
102
103    let lambda_y = lambda * y;
104    let log_term = if lambda_y < f64::MAX {
105        lambda_y.ln_1p()
106    } else {
107        (1.0_f64.copysign(lambda) * (y + 1.0 / lambda)).ln() + lambda.abs().ln()
108    };
109    (log_term / lambda).exp()
110}
111
112/// Inverse of the Box-Cox transformation of 1 + `x`
113///
114/// Compute the compositional inverse of `y = boxcox1p(x, lambda)` for `x`.
115///
116/// Corresponds to [`scipy.special.inv_boxcox1p`][scipy].
117///
118/// [scipy]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.inv_boxcox1p.html
119///
120/// # See also
121/// - [`boxcox1p`]: Box-Cox transformation of `1 + x`
122/// - [`inv_boxcox`]: Inverse of the Box-Cox transformation of `x`
123#[doc(alias = "boxcox_1p_inv", alias = "inv_boxcox_1p")]
124#[must_use]
125#[inline]
126pub fn inv_boxcox1p(y: f64, lambda: f64) -> f64 {
127    if lambda == 0.0 {
128        return y.exp_m1();
129    }
130
131    let lambda_y = lambda * y;
132    if lambda_y.abs() < SQRT_F64_MIN_POSITIVE {
133        return y.exp_m1();
134    }
135
136    let log_term = if lambda_y < f64::MAX {
137        lambda_y.ln_1p()
138    } else {
139        (1.0_f64.copysign(lambda) * (y + 1.0 / lambda)).ln() + lambda.abs().ln()
140    };
141    (log_term / lambda).exp_m1()
142}