Skip to main content

solow_emplike/
lib.rs

1//! # solow-emplike
2//!
3//! Empirical-likelihood (EL) inference on descriptive statistics of a univariate
4//! sample, following Owen (2001) and validated against the reference
5//! `emplike.descriptive` module.
6//!
7//! The entry point is [`DescStat`], which exposes
8//!
9//! * [`DescStat::test_mean`] — EL test of a hypothesized mean `mu0`,
10//! * [`DescStat::ci_mean`] — EL confidence interval for the mean,
11//! * [`DescStat::test_var`] — EL test of a hypothesized variance `sig2_0`.
12//!
13//! ## Method
14//!
15//! For a hypothesized mean `mu0`, the empirical-likelihood weights `w_i` maximize
16//! `sum log(w_i)` subject to `sum w_i = 1` and `sum w_i (x_i - mu0) = 0`. The dual
17//! solution is `w_i = 1 / (n (1 + eta (x_i - mu0)))`, where the Lagrange
18//! multiplier `eta` is the root of `sum (x_i - mu0) / (1 + eta (x_i - mu0)) = 0`.
19//! The EL test statistic is `-2 sum log(n w_i)`, asymptotically chi-squared with
20//! one degree of freedom.
21//!
22//! The variance test profiles out a nuisance mean: for each candidate mean it
23//! solves a two-parameter EL dual by a modified Newton iteration, then minimizes
24//! the resulting `-2 logELR` over the nuisance mean.
25
26mod root;
27
28use root::{brentq, fminbound};
29use solow_distributions::{chi2_ppf, chi2_sf};
30
31/// Empirical-likelihood inference for a univariate sample.
32#[derive(Clone, Debug)]
33pub struct DescStat {
34    endog: Vec<f64>,
35    nobs: usize,
36}
37
38/// Result of an EL hypothesis test: the `-2 logELR` statistic and its p-value.
39#[derive(Clone, Copy, Debug, PartialEq)]
40pub struct TestResult {
41    /// The `-2 log` empirical-likelihood-ratio statistic.
42    pub stat: f64,
43    /// The asymptotic p-value, from the chi-squared survival function.
44    pub pvalue: f64,
45}
46
47impl DescStat {
48    /// Build a [`DescStat`] from a sample. Panics if fewer than two points.
49    pub fn new(endog: &[f64]) -> Self {
50        assert!(endog.len() >= 2, "need at least two observations");
51        DescStat {
52            endog: endog.to_vec(),
53            nobs: endog.len(),
54        }
55    }
56
57    /// Number of observations.
58    pub fn nobs(&self) -> usize {
59        self.nobs
60    }
61
62    fn min(&self) -> f64 {
63        self.endog.iter().cloned().fold(f64::INFINITY, f64::min)
64    }
65
66    fn max(&self) -> f64 {
67        self.endog.iter().cloned().fold(f64::NEG_INFINITY, f64::max)
68    }
69
70    /// EL test of a hypothesized mean `mu0`.
71    ///
72    /// Returns the `-2 logELR` statistic and the chi-squared(1) p-value.
73    pub fn test_mean(&self, mu0: f64) -> TestResult {
74        let n = self.nobs as f64;
75        let endog = &self.endog;
76
77        // Bracket for the Lagrange multiplier, matching the reference.
78        let eta_min = (1.0 - 1.0 / n) / (mu0 - self.max());
79        let eta_max = (1.0 - 1.0 / n) / (mu0 - self.min());
80
81        let find_eta = |eta: f64| -> f64 {
82            endog
83                .iter()
84                .map(|&xi| (xi - mu0) / (1.0 + eta * (xi - mu0)))
85                .sum()
86        };
87        let eta_star = brentq(find_eta, eta_min, eta_max);
88
89        let llr: f64 = endog
90            .iter()
91            .map(|&xi| {
92                let w = (1.0 / n) / (1.0 + eta_star * (xi - mu0));
93                (n * w).ln()
94            })
95            .sum::<f64>()
96            * -2.0;
97
98        TestResult {
99            stat: llr,
100            pvalue: chi2_sf(llr, 1.0),
101        }
102    }
103
104    /// EL confidence interval for the mean at significance level `sig`
105    /// (e.g. `0.05` for a 95% interval), using the "gamma" root-finding method.
106    ///
107    /// Returns `(low, high)`.
108    pub fn ci_mean(&self, sig: f64) -> (f64, f64) {
109        self.ci_mean_opts(sig, 1e-8, -1e10, 1e10)
110    }
111
112    /// [`Self::ci_mean`] with explicit search parameters, mirroring the reference
113    /// defaults (`epsilon = 1e-8`, `gamma_low = -1e10`, `gamma_high = 1e10`).
114    pub fn ci_mean_opts(
115        &self,
116        sig: f64,
117        epsilon: f64,
118        gamma_low: f64,
119        gamma_high: f64,
120    ) -> (f64, f64) {
121        let endog = &self.endog;
122        let n = self.nobs as f64;
123        let r0 = chi2_ppf(1.0 - sig, 1.0);
124
125        // sum(log(n*w(gamma))) test function: -2 sum log(n w) - r0, with
126        // w(gamma) = (x - gamma)^-1 / sum((x - gamma)^-1).
127        let find_gamma = |gamma: f64| -> f64 {
128            let denom: f64 = endog.iter().map(|&xi| 1.0 / (xi - gamma)).sum();
129            let llr: f64 = endog
130                .iter()
131                .map(|&xi| {
132                    let w = (1.0 / (xi - gamma)) / denom;
133                    (n * w).ln()
134                })
135                .sum();
136            -2.0 * llr - r0
137        };
138
139        let gamma_star_l = brentq(find_gamma, gamma_low, self.min() - epsilon);
140        let gamma_star_u = brentq(find_gamma, self.max() + epsilon, gamma_high);
141
142        let mu_at = |gamma: f64| -> f64 {
143            let denom: f64 = endog.iter().map(|&xi| 1.0 / (xi - gamma)).sum();
144            endog
145                .iter()
146                .map(|&xi| ((1.0 / (xi - gamma)) / denom) * xi)
147                .sum()
148        };
149
150        (mu_at(gamma_star_l), mu_at(gamma_star_u))
151    }
152
153    /// EL test of a hypothesized variance `sig2_0`.
154    ///
155    /// Profiles out the nuisance mean by minimizing the `-2 logELR` over the
156    /// mean, then returns that statistic and the chi-squared(1) p-value.
157    pub fn test_var(&self, sig2_0: f64) -> TestResult {
158        let mu_min = self.min();
159        let mu_max = self.max();
160        let mut opt_var = |nuisance_mu: f64| self.opt_var(nuisance_mu, sig2_0);
161        let (_xf, llr) = fminbound(&mut opt_var, mu_min, mu_max);
162        TestResult {
163            stat: llr,
164            pvalue: chi2_sf(llr, 1.0),
165        }
166    }
167
168    /// `-2 logELR` for the variance test at a fixed nuisance mean.
169    fn opt_var(&self, nuisance_mu: f64, sig2_0: f64) -> f64 {
170        let n = self.nobs as f64;
171        // Estimating equations: [x - mu, (x - mu)^2 - sig2_0].
172        let est: Vec<[f64; 2]> = self
173            .endog
174            .iter()
175            .map(|&x| {
176                let m = x - nuisance_mu;
177                [m, m * m - sig2_0]
178            })
179            .collect();
180
181        let eta = modif_newton(&est, self.nobs);
182
183        let llr: f64 = est
184            .iter()
185            .map(|e| {
186                let denom = 1.0 + eta[0] * e[0] + eta[1] * e[1];
187                let w = (1.0 / n) / denom;
188                (n * w).ln()
189            })
190            .sum();
191        -2.0 * llr
192    }
193}
194
195/// Modified Newton solver for the two-parameter EL dual, faithfully mirroring the
196/// reference `_modif_newton` / `_fit_newton` (weights `1/n`, `tol = 1e-8`,
197/// `ridge_factor = 1e-10`, `maxiter = 50`).
198///
199/// Minimizes `-sum log_star(eta)` over the Lagrange multiplier `eta` in R^2.
200fn modif_newton(est: &[[f64; 2]], nobs: usize) -> [f64; 2] {
201    let n = nobs as f64;
202    let weights = 1.0 / n; // every observation weight is 1/n
203    let sum_w = 1.0; // sum of weights
204    let inv_n = 1.0 / n;
205    let start = inv_n;
206    let mut params = [start, start];
207    let mut oldparams = [f64::INFINITY, f64::INFINITY];
208    let tol = 1e-8;
209    let ridge = 1e-10;
210    let maxiter = 50;
211
212    let mut iters = 0;
213    while iters < maxiter
214        && ((params[0] - oldparams[0]).abs() > tol || (params[1] - oldparams[1]).abs() > tol)
215    {
216        // Negative gradient and negative Hessian of sum(log_star).
217        // _fit_newton minimizes f = -sum(log_star), so score = -grad, hess = -hess.
218        let (grad, hess) = grad_hess(est, &params, weights, sum_w, n);
219        // score = -grad ; H = -hess ; regularize H diagonal with ridge.
220        let h = [
221            [-hess[0][0] + ridge, -hess[0][1]],
222            [-hess[1][0], -hess[1][1] + ridge],
223        ];
224        let s = [-grad[0], -grad[1]];
225
226        // Solve H * step = s (2x2 closed form).
227        let det = h[0][0] * h[1][1] - h[0][1] * h[1][0];
228        let step = [
229            (h[1][1] * s[0] - h[0][1] * s[1]) / det,
230            (-h[1][0] * s[0] + h[0][0] * s[1]) / det,
231        ];
232
233        oldparams = params;
234        params = [oldparams[0] - step[0], oldparams[1] - step[1]];
235        iters += 1;
236    }
237    params
238}
239
240/// Gradient and Hessian of `sum(log_star(eta))` for the 2-parameter problem,
241/// including the small-`data_star` linearization branch from the reference.
242fn grad_hess(
243    est: &[[f64; 2]],
244    eta: &[f64; 2],
245    weights: f64,
246    sum_w: f64,
247    nobs: f64,
248) -> ([f64; 2], [[f64; 2]; 2]) {
249    let mut grad = [0.0_f64; 2];
250    let mut hess = [[0.0_f64; 2]; 2];
251    let thr = 1.0 / nobs;
252
253    for e in est {
254        let ds = sum_w + eta[0] * e[0] + eta[1] * e[1];
255
256        // First-derivative factor (data_star_prime).
257        let dsp = if ds < thr {
258            nobs * (2.0 - nobs * ds)
259        } else {
260            1.0 / ds
261        };
262        let gfac = weights * dsp;
263        grad[0] += gfac * e[0];
264        grad[1] += gfac * e[1];
265
266        // Second-derivative factor (data_star_doub_prime).
267        let dspp = if ds < thr {
268            -nobs * nobs
269        } else {
270            -1.0 / (ds * ds)
271        };
272        let hfac = weights * dspp;
273        hess[0][0] += hfac * e[0] * e[0];
274        hess[0][1] += hfac * e[0] * e[1];
275        hess[1][0] += hfac * e[1] * e[0];
276        hess[1][1] += hfac * e[1] * e[1];
277    }
278    (grad, hess)
279}
280
281#[cfg(test)]
282mod tests {
283    use super::*;
284    use approx::assert_abs_diff_eq;
285
286    fn ramp() -> Vec<f64> {
287        (1..=10).map(|i| i as f64).collect()
288    }
289
290    #[test]
291    fn test_mean_at_sample_mean_is_zero() {
292        let d = DescStat::new(&ramp());
293        // sample mean is 5.5; statistic should be (numerically) zero, p ~ 1.
294        let r = d.test_mean(5.5);
295        assert_abs_diff_eq!(r.stat, 0.0, epsilon = 1e-9);
296        assert_abs_diff_eq!(r.pvalue, 1.0, epsilon = 1e-9);
297    }
298
299    #[test]
300    fn test_mean_is_symmetric_about_mean() {
301        let d = DescStat::new(&ramp());
302        // Symmetric data: mu0 = 5 and mu0 = 6 are mirror images about 5.5.
303        let a = d.test_mean(5.0);
304        let b = d.test_mean(6.0);
305        assert_abs_diff_eq!(a.stat, b.stat, epsilon = 1e-9);
306    }
307
308    #[test]
309    fn ci_mean_brackets_sample_mean() {
310        let d = DescStat::new(&ramp());
311        let (lo, hi) = d.ci_mean(0.05);
312        assert!(lo < 5.5 && 5.5 < hi, "CI [{lo}, {hi}] must contain 5.5");
313        // The statistic at each endpoint equals chi2_ppf(0.95, 1).
314        let crit = chi2_ppf(0.95, 1.0);
315        assert_abs_diff_eq!(d.test_mean(lo).stat, crit, epsilon = 1e-6);
316        assert_abs_diff_eq!(d.test_mean(hi).stat, crit, epsilon = 1e-6);
317    }
318
319    #[test]
320    fn test_var_at_sample_variance_is_zero() {
321        let d = DescStat::new(&ramp());
322        // population variance of 1..10 is 8.25.
323        let r = d.test_var(8.25);
324        assert_abs_diff_eq!(r.stat, 0.0, epsilon = 1e-7);
325    }
326
327    #[test]
328    fn pvalue_matches_chi2_sf() {
329        let d = DescStat::new(&ramp());
330        let r = d.test_mean(4.0);
331        assert_abs_diff_eq!(r.pvalue, chi2_sf(r.stat, 1.0), epsilon = 1e-12);
332    }
333}