Skip to main content

solow_bayes/
lib.rs

1//! # solow-bayes
2//!
3//! Bayesian generalized linear mixed models fit by **mean-field variational
4//! Bayes** (deterministic; no MCMC). Two families are provided with a
5//! random-effects design (`exog_vc`): [`BinomialBayesMixedGLM`] (logit link) and
6//! [`PoissonBayesMixedGLM`] (log link). Both are fit by [`BayesMixedGlm::fit_vb`],
7//! which maximizes the evidence lower bound (ELBO) of a factored Gaussian
8//! variational posterior over the fixed effects, the variance-component
9//! parameters (log standard deviations of the random effects), and the random
10//! effect realizations.
11//!
12//! The parameterization, ELBO and its gradient mirror the canonical
13//! statistical-computing reference's `genmod.bayes_mixed_glm` module exactly, so
14//! the posterior means ([`BayesMixedGlmResults::fe_mean`],
15//! [`BayesMixedGlmResults::vcp_mean`], [`BayesMixedGlmResults::vc_mean`]) and the
16//! ELBO ([`BayesMixedGlmResults::elbo`] / [`BayesMixedGlmResults::llf`]) agree to
17//! optimizer tolerance.
18//!
19//! ## Model
20//!
21//! For observation `i` the linear predictor is
22//! `eta_i = x_i · fe + z_i · vc`, where `x` is `exog` (fixed effects) and `z` is
23//! `exog_vc` (random effects). Each random effect realization `vc_j` is
24//! Gaussian with mean zero and standard deviation `exp(vcp[ident[j]])`; the
25//! `vcp` parameters (log standard deviations) have a `N(0, vcp_p²)` prior and the
26//! fixed effects a `N(0, fe_p²)` prior.
27
28use ndarray::{Array1, Array2};
29use solow_core::error::{Error, Result};
30use solow_optimize::minimize_bfgs;
31
32mod map_estimation;
33pub use map_estimation::MapResult;
34
35/// Ten-point Gauss–Legendre nodes/weights on `[-1, 1]` (weight, node), used to
36/// integrate the family contribution against a standard Gaussian. Identical to
37/// the reference's `glw` table.
38const GLW: [(f64, f64); 10] = [
39    (0.295_524_224_714_752_9, -0.148_874_338_981_631_2),
40    (0.295_524_224_714_752_9, 0.148_874_338_981_631_2),
41    (0.269_266_719_309_996_3, -0.433_395_394_129_247_2),
42    (0.269_266_719_309_996_3, 0.433_395_394_129_247_2),
43    (0.219_086_362_515_982, -0.679_409_568_299_024_4),
44    (0.219_086_362_515_982, 0.679_409_568_299_024_4),
45    (0.149_451_349_150_580_6, -0.865_063_366_688_984_5),
46    (0.149_451_349_150_580_6, 0.865_063_366_688_984_5),
47    (0.066_671_344_308_688_1, -0.973_906_528_517_171_7),
48    (0.066_671_344_308_688_1, 0.973_906_528_517_171_7),
49];
50
51/// Integration half-range for the Gaussian quadrature (`-RNG..RNG`).
52const RNG: f64 = 5.0;
53
54/// The GLM family for the Bayesian mixed model.
55#[derive(Clone, Copy, Debug, PartialEq, Eq)]
56pub enum Family {
57    /// Binomial family with the logit link (0/1 responses).
58    Binomial,
59    /// Poisson family with the log link (count responses).
60    Poisson,
61}
62
63/// A Bayesian mixed GLM with a random-effects design, fit by variational Bayes.
64///
65/// Construct with [`BayesMixedGlm::new`], then call [`BayesMixedGlm::fit_vb`].
66#[derive(Clone, Debug)]
67pub struct BayesMixedGlm {
68    family: Family,
69    endog: Array1<f64>,
70    exog: Array2<f64>,
71    exog2: Array2<f64>,
72    exog_vc: Array2<f64>,
73    exog_vc2: Array2<f64>,
74    ident: Vec<usize>,
75    k_fep: usize,
76    k_vcp: usize,
77    k_vc: usize,
78    vcp_p: f64,
79    fe_p: f64,
80}
81
82impl BayesMixedGlm {
83    /// Build a model.
84    ///
85    /// * `endog` — response vector (`0/1` for binomial, counts for Poisson).
86    /// * `exog` — fixed-effects design, shape `(n, k_fep)`.
87    /// * `exog_vc` — random-effects design, shape `(n, k_vc)`; each column is one
88    ///   independent random effect realization.
89    /// * `ident` — length `k_vc`; columns sharing an `ident` value share a
90    ///   variance-component (log-sd) parameter. Values must be `0..k_vcp`.
91    /// * `vcp_p` — prior sd for the variance-component (log-sd) parameters.
92    /// * `fe_p` — prior sd for the fixed-effects parameters.
93    pub fn new(
94        family: Family,
95        endog: Array1<f64>,
96        exog: Array2<f64>,
97        exog_vc: Array2<f64>,
98        ident: Vec<usize>,
99        vcp_p: f64,
100        fe_p: f64,
101    ) -> Result<Self> {
102        let n = endog.len();
103        if exog.nrows() != n || exog_vc.nrows() != n {
104            return Err(Error::Shape(
105                "endog, exog and exog_vc must have matching row counts".into(),
106            ));
107        }
108        if ident.len() != exog_vc.ncols() {
109            return Err(Error::Shape(
110                "len(ident) must equal the number of columns of exog_vc".into(),
111            ));
112        }
113        if family == Family::Binomial && !endog.iter().all(|&y| y == 0.0 || y == 1.0) {
114            return Err(Error::Value("binomial endog values must be 0 or 1".into()));
115        }
116        let k_fep = exog.ncols();
117        let k_vc = exog_vc.ncols();
118        let k_vcp = ident.iter().copied().max().map(|m| m + 1).unwrap_or(0);
119        let exog2 = exog.mapv(|v| v * v);
120        let exog_vc2 = exog_vc.mapv(|v| v * v);
121        Ok(Self {
122            family,
123            endog,
124            exog,
125            exog2,
126            exog_vc,
127            exog_vc2,
128            ident,
129            k_fep,
130            k_vcp,
131            k_vc,
132            vcp_p,
133            fe_p,
134        })
135    }
136
137    /// Total number of variational mean (or sd) parameters. Also the length of
138    /// the stacked `[fep, vcp, vc]` MAP parameter vector.
139    pub(crate) fn dim(&self) -> usize {
140        self.k_fep + self.k_vcp + self.k_vc
141    }
142
143    /// Split a stacked vector into `(fep, vcp, vc)` views by length.
144    pub(crate) fn unpack<'a>(&self, v: &'a [f64]) -> (&'a [f64], &'a [f64], &'a [f64]) {
145        let a = self.k_fep;
146        let b = a + self.k_vcp;
147        (&v[..a], &v[a..b], &v[b..])
148    }
149
150    /// The GLM family.
151    pub(crate) fn family(&self) -> Family {
152        self.family
153    }
154
155    /// The response vector.
156    pub(crate) fn endog(&self) -> &Array1<f64> {
157        &self.endog
158    }
159
160    /// The fixed-effects design matrix.
161    pub(crate) fn exog(&self) -> &Array2<f64> {
162        &self.exog
163    }
164
165    /// The random-effects design matrix.
166    pub(crate) fn exog_vc(&self) -> &Array2<f64> {
167        &self.exog_vc
168    }
169
170    /// The variance-component index for random-effect column `j`.
171    pub(crate) fn ident_at(&self, j: usize) -> usize {
172        self.ident[j]
173    }
174
175    /// Number of fixed-effects parameters.
176    pub(crate) fn k_fep(&self) -> usize {
177        self.k_fep
178    }
179
180    /// Number of variance-component (log-sd) parameters.
181    pub(crate) fn k_vcp(&self) -> usize {
182        self.k_vcp
183    }
184
185    /// Prior sd for the variance-component parameters.
186    pub(crate) fn vcp_p(&self) -> f64 {
187        self.vcp_p
188    }
189
190    /// Prior sd for the fixed-effects parameters.
191    pub(crate) fn fe_p(&self) -> f64 {
192        self.fe_p
193    }
194
195    /// Mean and variance of the linear predictor for every observation under the
196    /// variational posterior. Mirrors `_lp_stats`.
197    fn lp_stats(
198        &self,
199        fep_mean: &[f64],
200        fep_sd: &[f64],
201        vc_mean: &[f64],
202        vc_sd: &[f64],
203    ) -> (Array1<f64>, Array1<f64>) {
204        let n = self.endog.len();
205        let mut tm = Array1::<f64>::zeros(n);
206        let mut tv = Array1::<f64>::zeros(n);
207        for i in 0..n {
208            let mut m = 0.0;
209            let mut var = 0.0;
210            for k in 0..self.k_fep {
211                m += self.exog[[i, k]] * fep_mean[k];
212                var += self.exog2[[i, k]] * fep_sd[k] * fep_sd[k];
213            }
214            for k in 0..self.k_vc {
215                m += self.exog_vc[[i, k]] * vc_mean[k];
216                var += self.exog_vc2[[i, k]] * vc_sd[k] * vc_sd[k];
217            }
218            tm[i] = m;
219            tv[i] = var;
220        }
221        (tm, tv)
222    }
223
224    /// The per-observation `h(z)` contribution of the family to the ELBO.
225    /// `h(z) = -log(1 + exp(lp))` (binomial) or `-exp(lp)` (Poisson) with
226    /// `lp = tm + sqrt(tv) z`.
227    fn h(&self, z: f64, tm: &Array1<f64>, tv_sqrt: &Array1<f64>) -> Array1<f64> {
228        match self.family {
229            Family::Binomial => Array1::from_iter(
230                tm.iter()
231                    .zip(tv_sqrt.iter())
232                    .map(|(&m, &s)| -log1pexp(m + s * z)),
233            ),
234            Family::Poisson => Array1::from_iter(
235                tm.iter()
236                    .zip(tv_sqrt.iter())
237                    .map(|(&m, &s)| -(m + s * z).exp()),
238            ),
239        }
240    }
241
242    /// The derivative factor `h'`-like term used in the gradient. For the
243    /// binomial this is `-sigmoid(lp)`; for the Poisson it is `-exp(lp)`.
244    fn h_grad(&self, z: f64, tm: &Array1<f64>, tv_sqrt: &Array1<f64>) -> Array1<f64> {
245        match self.family {
246            Family::Binomial => Array1::from_iter(
247                tm.iter()
248                    .zip(tv_sqrt.iter())
249                    .map(|(&m, &s)| -sigmoid(m + s * z)),
250            ),
251            Family::Poisson => Array1::from_iter(
252                tm.iter()
253                    .zip(tv_sqrt.iter())
254                    .map(|(&m, &s)| -(m + s * z).exp()),
255            ),
256        }
257    }
258
259    /// Terms of the ELBO common to all families: `p(vc|vcp) p(vcp) p(fe)`.
260    /// Mirrors `_elbo_common`.
261    fn elbo_common(
262        &self,
263        fep_mean: &[f64],
264        fep_sd: &[f64],
265        vcp_mean: &[f64],
266        vcp_sd: &[f64],
267        vc_mean: &[f64],
268        vc_sd: &[f64],
269    ) -> f64 {
270        let mut iv = 0.0;
271        // p(vc | vcp): `m`/`s` are the per-column vcp params via `ident`, so the
272        // `-sum(m)` term sums over all k_vc columns (one log-sd per realization),
273        // matching `np.sum(vcp_mean[ident])`.
274        for j in 0..self.k_vc {
275            let m = vcp_mean[self.ident[j]];
276            let s = vcp_sd[self.ident[j]];
277            let u = vc_mean[j] * vc_mean[j] + vc_sd[j] * vc_sd[j];
278            iv -= u * (2.0 * (s * s - m)).exp() / 2.0;
279            iv -= m;
280        }
281        // p(vcp)
282        for k in 0..self.k_vcp {
283            iv -= 0.5 * (vcp_mean[k] * vcp_mean[k] + vcp_sd[k] * vcp_sd[k])
284                / (self.vcp_p * self.vcp_p);
285        }
286        // p(fe)
287        for k in 0..self.k_fep {
288            iv -=
289                0.5 * (fep_mean[k] * fep_mean[k] + fep_sd[k] * fep_sd[k]) / (self.fe_p * self.fe_p);
290        }
291        iv
292    }
293
294    /// The ELBO at variational mean vector `vb_mean` and sd vector `vb_sd`
295    /// (natural scale). Mirrors `vb_elbo` / `vb_elbo_base`.
296    pub fn vb_elbo(&self, vb_mean: &[f64], vb_sd: &[f64]) -> f64 {
297        let (fep_mean, vcp_mean, vc_mean) = self.unpack(vb_mean);
298        let (fep_sd, vcp_sd, vc_sd) = self.unpack(vb_sd);
299        let (tm, tv) = self.lp_stats(fep_mean, fep_sd, vc_mean, vc_sd);
300        let tv_sqrt = tv.mapv(f64::sqrt);
301
302        let n = self.endog.len();
303        // p(y | vc): quadrature of the family contribution + endog·tm.
304        let mut iv_vec = Array1::<f64>::zeros(n);
305        for &(w, node) in GLW.iter() {
306            let z = RNG * node;
307            let hz = self.h(z, &tm, &tv_sqrt);
308            let f = w * (-z * z / 2.0).exp();
309            iv_vec.scaled_add(f, &hz);
310        }
311        iv_vec /= (2.0 * std::f64::consts::PI).sqrt();
312        iv_vec *= RNG;
313        let mut iv: f64 = 0.0;
314        for i in 0..n {
315            iv += iv_vec[i] + self.endog[i] * tm[i];
316        }
317
318        iv += self.elbo_common(fep_mean, fep_sd, vcp_mean, vcp_sd, vc_mean, vc_sd);
319
320        let log_sd: f64 = vb_sd.iter().map(|&s| s.ln()).sum();
321        iv + log_sd
322    }
323
324    /// Gradient of the ELBO with respect to `(mean, sd)` (natural sd scale).
325    /// Mirrors `vb_elbo_grad` / `vb_elbo_grad_base`. Returns
326    /// `(mean_grad, sd_grad)`.
327    pub fn vb_elbo_grad(&self, vb_mean: &[f64], vb_sd: &[f64]) -> (Array1<f64>, Array1<f64>) {
328        let (fep_mean, vcp_mean, vc_mean) = self.unpack(vb_mean);
329        let (fep_sd, vcp_sd, vc_sd) = self.unpack(vb_sd);
330        let (tm, tv) = self.lp_stats(fep_mean, fep_sd, vc_mean, vc_sd);
331        let tv_sqrt = tv.mapv(f64::sqrt);
332        let n = self.endog.len();
333
334        let mut fep_mean_grad = Array1::<f64>::zeros(self.k_fep);
335        let mut vc_mean_grad = Array1::<f64>::zeros(self.k_vc);
336        let mut fep_sd_grad = Array1::<f64>::zeros(self.k_fep);
337        let mut vc_sd_grad = Array1::<f64>::zeros(self.k_vc);
338
339        for &(w, node) in GLW.iter() {
340            let z = RNG * node;
341            // u = h'(z) * N(z)
342            let hz = self.h_grad(z, &tm, &tv_sqrt);
343            let u: Array1<f64> = Array1::from_iter(
344                hz.iter()
345                    .map(|&v| v * (-z * z / 2.0).exp() / (2.0 * std::f64::consts::PI).sqrt()),
346            );
347            // r = u / sqrt(tv)
348            let r: Array1<f64> =
349                Array1::from_iter(u.iter().zip(tv_sqrt.iter()).map(|(&a, &b)| a / b));
350
351            // fep_mean_grad += w * u·exog
352            for k in 0..self.k_fep {
353                let mut acc = 0.0;
354                for i in 0..n {
355                    acc += u[i] * self.exog[[i, k]];
356                }
357                fep_mean_grad[k] += w * acc;
358            }
359            // vc_mean_grad += w * exog_vc^T u
360            for k in 0..self.k_vc {
361                let mut acc = 0.0;
362                for i in 0..n {
363                    acc += u[i] * self.exog_vc[[i, k]];
364                }
365                vc_mean_grad[k] += w * acc;
366            }
367            // fep_sd_grad += w * z * (r · (exog^2 * fep_sd))
368            for k in 0..self.k_fep {
369                let mut acc = 0.0;
370                for i in 0..n {
371                    acc += r[i] * self.exog2[[i, k]] * fep_sd[k];
372                }
373                fep_sd_grad[k] += w * z * acc;
374            }
375            // vc_sd_grad += w * z * (exog_vc2 * vc_sd)^T r
376            for k in 0..self.k_vc {
377                let mut acc = 0.0;
378                for i in 0..n {
379                    acc += self.exog_vc2[[i, k]] * vc_sd[k] * r[i];
380                }
381                vc_sd_grad[k] += w * z * acc;
382            }
383        }
384
385        fep_mean_grad *= RNG;
386        vc_mean_grad *= RNG;
387        fep_sd_grad *= RNG;
388        vc_sd_grad *= RNG;
389
390        // + endog·exog and exog_vc^T endog
391        for k in 0..self.k_fep {
392            let mut acc = 0.0;
393            for i in 0..n {
394                acc += self.endog[i] * self.exog[[i, k]];
395            }
396            fep_mean_grad[k] += acc;
397        }
398        for k in 0..self.k_vc {
399            let mut acc = 0.0;
400            for i in 0..n {
401                acc += self.endog[i] * self.exog_vc[[i, k]];
402            }
403            vc_mean_grad[k] += acc;
404        }
405
406        // Common (prior + p(vc|vcp)) contributions. Mirrors `_elbo_grad_common`.
407        let mut vcp_mean_grad = Array1::<f64>::zeros(self.k_vcp);
408        let mut vcp_sd_grad = Array1::<f64>::zeros(self.k_vcp);
409        for j in 0..self.k_vc {
410            let id = self.ident[j];
411            let m = vcp_mean[id];
412            let s = vcp_sd[id];
413            let u = vc_mean[j] * vc_mean[j] + vc_sd[j] * vc_sd[j];
414            let ve = (2.0 * (s * s - m)).exp();
415            vcp_mean_grad[id] += u * ve - 1.0;
416            vcp_sd_grad[id] += -2.0 * u * ve * s;
417            vc_mean_grad[j] += -vc_mean[j] * ve;
418            vc_sd_grad[j] += -vc_sd[j] * ve;
419        }
420        for k in 0..self.k_vcp {
421            vcp_mean_grad[k] -= vcp_mean[k] / (self.vcp_p * self.vcp_p);
422            vcp_sd_grad[k] -= vcp_sd[k] / (self.vcp_p * self.vcp_p);
423        }
424        for k in 0..self.k_fep {
425            fep_mean_grad[k] -= fep_mean[k] / (self.fe_p * self.fe_p);
426            fep_sd_grad[k] -= fep_sd[k] / (self.fe_p * self.fe_p);
427        }
428
429        // Entropy term d/d sd of sum(log sd) = 1/sd.
430        for k in 0..self.k_fep {
431            fep_sd_grad[k] += 1.0 / fep_sd[k];
432        }
433        for k in 0..self.k_vcp {
434            vcp_sd_grad[k] += 1.0 / vcp_sd[k];
435        }
436        for k in 0..self.k_vc {
437            vc_sd_grad[k] += 1.0 / vc_sd[k];
438        }
439
440        let mut mean_grad = Array1::<f64>::zeros(self.dim());
441        let mut sd_grad = Array1::<f64>::zeros(self.dim());
442        let (a, b) = (self.k_fep, self.k_fep + self.k_vcp);
443        for k in 0..self.k_fep {
444            mean_grad[k] = fep_mean_grad[k];
445            sd_grad[k] = fep_sd_grad[k];
446        }
447        for k in 0..self.k_vcp {
448            mean_grad[a + k] = vcp_mean_grad[k];
449            sd_grad[a + k] = vcp_sd_grad[k];
450        }
451        for k in 0..self.k_vc {
452            mean_grad[b + k] = vc_mean_grad[k];
453            sd_grad[b + k] = vc_sd_grad[k];
454        }
455        (mean_grad, sd_grad)
456    }
457
458    /// Fit the model by maximizing the ELBO (mean-field variational Bayes).
459    ///
460    /// The optimizer works on the stacked vector `[mean; log(sd)]`. Internally we
461    /// minimize `-ELBO` with the analytic gradient (transformed for the log-sd
462    /// reparameterization) via BFGS, matching the reference's `fit_vb`.
463    ///
464    /// * `mean_start` — starting variational means, length `dim()`. If `None`,
465    ///   zeros (with the `vcp` block floored at `-1`, as in the reference).
466    /// * `sd_start` — starting variational sds (natural scale), length `dim()`.
467    ///   If `None`, `exp(-0.5)` for every coordinate.
468    pub fn fit_vb(
469        &self,
470        mean_start: Option<Array1<f64>>,
471        sd_start: Option<Array1<f64>>,
472        maxiter: usize,
473        gtol: f64,
474    ) -> Result<BayesMixedGlmResults> {
475        let dim = self.dim();
476        let mut m = mean_start.unwrap_or_else(|| Array1::zeros(dim));
477        if m.len() != dim {
478            return Err(Error::Shape("mean_start has wrong length".into()));
479        }
480        // Floor the vcp starting means at -1, mirroring the reference.
481        let (i1, i2) = (self.k_fep, self.k_fep + self.k_vcp);
482        for k in i1..i2 {
483            if m[k] < -1.0 {
484                m[k] = -1.0;
485            }
486        }
487        // s is the log of the sd; floor at -1.
488        let sd0 = sd_start.unwrap_or_else(|| Array1::from_elem(dim, (-0.5f64).exp()));
489        if sd0.len() != dim {
490            return Err(Error::Shape("sd_start has wrong length".into()));
491        }
492        let mut s = sd0.mapv(|v| v.ln());
493        for v in s.iter_mut() {
494            if *v < -1.0 {
495                *v = -1.0;
496            }
497        }
498
499        // Pack [mean; log sd].
500        let mut start = Array1::<f64>::zeros(2 * dim);
501        for k in 0..dim {
502            start[k] = m[k];
503            start[dim + k] = s[k];
504        }
505
506        let f = |x: &Array1<f64>| -> f64 {
507            let mean = x.slice(ndarray::s![..dim]).to_vec();
508            let sd: Vec<f64> = x
509                .slice(ndarray::s![dim..])
510                .iter()
511                .map(|&v| v.exp())
512                .collect();
513            -self.vb_elbo(&mean, &sd)
514        };
515        let grad = |x: &Array1<f64>| -> Array1<f64> {
516            let mean = x.slice(ndarray::s![..dim]).to_vec();
517            let logsd = x.slice(ndarray::s![dim..]).to_vec();
518            let sd: Vec<f64> = logsd.iter().map(|&v| v.exp()).collect();
519            let (gm, mut gs) = self.vb_elbo_grad(&mean, &sd);
520            // chain rule for sd = exp(log sd): multiply by exp(log sd) = sd
521            for k in 0..dim {
522                gs[k] *= sd[k];
523            }
524            let mut g = Array1::<f64>::zeros(2 * dim);
525            for k in 0..dim {
526                g[k] = -gm[k];
527                g[dim + k] = -gs[k];
528            }
529            g
530        };
531
532        // Restart BFGS in bursts and accept a scale-aware function-value stall
533        // as convergence: the finite-difference gradient has a platform-
534        // dependent roundoff floor it cannot drop below, so `|g| <= gtol` alone
535        // is not reachable on every platform. The optimum (and every reported
536        // quantity) is identical either way — this only makes the `converged`
537        // flag robust across platforms and stops the fit as soon as the ELBO
538        // stalls instead of grinding to `maxiter`.
539        let burst = 25usize;
540        let bursts = maxiter.div_ceil(burst).max(1);
541        let mut xk = start.clone();
542        let mut f_prev = f(&xk);
543        let mut converged = false;
544        let mut iters = 0usize;
545        let mut grad_norm = f64::INFINITY;
546        for _ in 0..bursts {
547            let res = minimize_bfgs(&xk, f, grad, burst, gtol)?;
548            xk = res.x;
549            iters += res.iters;
550            grad_norm = res.grad_norm;
551            let f_now = res.fval;
552            if res.converged || (f_prev - f_now).abs() <= 1e-12 * (1.0 + f_now.abs()) {
553                converged = true;
554                break;
555            }
556            f_prev = f_now;
557        }
558        let x = xk;
559        let mean = x.slice(ndarray::s![..dim]).to_owned();
560        let sd = x.slice(ndarray::s![dim..]).mapv(|v| v.exp());
561
562        let mean_s = mean
563            .as_slice()
564            .ok_or_else(|| Error::Value("mean must be contiguous".into()))?;
565        let sd_s = sd
566            .as_slice()
567            .ok_or_else(|| Error::Value("sd must be contiguous".into()))?;
568        let (fep, vcp, vc) = self.unpack(mean_s);
569        let fe_mean = Array1::from_vec(fep.to_vec());
570        let vcp_mean = Array1::from_vec(vcp.to_vec());
571        let vc_mean = Array1::from_vec(vc.to_vec());
572        let (fep_sd, vcp_sd, vc_sd) = self.unpack(sd_s);
573        let fe_sd = Array1::from_vec(fep_sd.to_vec());
574        let vcp_sd_a = Array1::from_vec(vcp_sd.to_vec());
575        let vc_sd_a = Array1::from_vec(vc_sd.to_vec());
576
577        let elbo = self.vb_elbo(mean_s, sd_s);
578
579        Ok(BayesMixedGlmResults {
580            fe_mean,
581            vcp_mean,
582            vc_mean,
583            fe_sd,
584            vcp_sd: vcp_sd_a,
585            vc_sd: vc_sd_a,
586            elbo,
587            converged,
588            iters,
589            grad_norm,
590        })
591    }
592}
593
594/// A binomial (logit-link) Bayesian mixed GLM. Thin constructor over
595/// [`BayesMixedGlm`].
596pub struct BinomialBayesMixedGLM;
597
598impl BinomialBayesMixedGLM {
599    /// Build a binomial model. See [`BayesMixedGlm::new`]. This is a named
600    /// constructor mirroring the reference API; it returns the family-agnostic
601    /// [`BayesMixedGlm`] rather than `Self` (a zero-sized marker).
602    #[allow(clippy::new_ret_no_self, clippy::too_many_arguments)]
603    pub fn new(
604        endog: Array1<f64>,
605        exog: Array2<f64>,
606        exog_vc: Array2<f64>,
607        ident: Vec<usize>,
608        vcp_p: f64,
609        fe_p: f64,
610    ) -> Result<BayesMixedGlm> {
611        BayesMixedGlm::new(Family::Binomial, endog, exog, exog_vc, ident, vcp_p, fe_p)
612    }
613}
614
615/// A Poisson (log-link) Bayesian mixed GLM. Thin constructor over
616/// [`BayesMixedGlm`].
617pub struct PoissonBayesMixedGLM;
618
619impl PoissonBayesMixedGLM {
620    /// Build a Poisson model. See [`BayesMixedGlm::new`]. This is a named
621    /// constructor mirroring the reference API; it returns the family-agnostic
622    /// [`BayesMixedGlm`] rather than `Self` (a zero-sized marker).
623    #[allow(clippy::new_ret_no_self, clippy::too_many_arguments)]
624    pub fn new(
625        endog: Array1<f64>,
626        exog: Array2<f64>,
627        exog_vc: Array2<f64>,
628        ident: Vec<usize>,
629        vcp_p: f64,
630        fe_p: f64,
631    ) -> Result<BayesMixedGlm> {
632        BayesMixedGlm::new(Family::Poisson, endog, exog, exog_vc, ident, vcp_p, fe_p)
633    }
634}
635
636/// Posterior summary returned by [`BayesMixedGlm::fit_vb`].
637#[derive(Clone, Debug)]
638pub struct BayesMixedGlmResults {
639    /// Posterior mean of the fixed-effects coefficients.
640    pub fe_mean: Array1<f64>,
641    /// Posterior mean of the variance-component (log-sd) parameters.
642    pub vcp_mean: Array1<f64>,
643    /// Posterior mean of the random-effect realizations.
644    pub vc_mean: Array1<f64>,
645    /// Posterior sd of the fixed-effects coefficients.
646    pub fe_sd: Array1<f64>,
647    /// Posterior sd of the variance-component parameters.
648    pub vcp_sd: Array1<f64>,
649    /// Posterior sd of the random-effect realizations.
650    pub vc_sd: Array1<f64>,
651    /// The maximized evidence lower bound.
652    pub elbo: f64,
653    /// Whether the optimizer met its convergence test.
654    pub converged: bool,
655    /// Optimizer iterations performed.
656    pub iters: usize,
657    /// Final gradient norm reported by the optimizer.
658    pub grad_norm: f64,
659}
660
661impl BayesMixedGlmResults {
662    /// The ELBO, which serves as the (variational) log-likelihood. Alias for
663    /// [`BayesMixedGlmResults::elbo`].
664    pub fn llf(&self) -> f64 {
665        self.elbo
666    }
667}
668
669/// Numerically stable `log(1 + exp(x))`.
670fn log1pexp(x: f64) -> f64 {
671    if x > 0.0 {
672        x + (-x).exp().ln_1p()
673    } else {
674        x.exp().ln_1p()
675    }
676}
677
678/// Numerically stable logistic sigmoid `1 / (1 + exp(-x))`.
679fn sigmoid(x: f64) -> f64 {
680    if x >= 0.0 {
681        1.0 / (1.0 + (-x).exp())
682    } else {
683        let e = x.exp();
684        e / (1.0 + e)
685    }
686}
687
688#[cfg(test)]
689mod tests {
690    use super::*;
691    use approx::assert_abs_diff_eq;
692    use ndarray::{array, Array1, Array2};
693    use solow_optimize::approx_fprime;
694
695    /// The 6-group balanced random-intercept design used in the fixtures.
696    fn binom_model() -> BayesMixedGlm {
697        let n_groups = 6usize;
698        let per = 4usize;
699        let n = n_groups * per;
700        let x1: Vec<f64> = (0..n)
701            .map(|i| -1.5 + 3.0 * i as f64 / (n as f64 - 1.0))
702            .collect();
703        let mut exog = Array2::<f64>::zeros((n, 2));
704        let mut exog_vc = Array2::<f64>::zeros((n, n_groups));
705        for i in 0..n {
706            exog[[i, 0]] = 1.0;
707            exog[[i, 1]] = x1[i];
708            exog_vc[[i, i / per]] = 1.0;
709        }
710        // Endog from the binomial fixture case.
711        let endog = array![
712            0., 0., 0., 1., 1., 0., 0., 0., 1., 0., 0., 1., 1., 1., 1., 1., 1., 0., 0., 1., 0., 0.,
713            1., 1.
714        ];
715        let ident = vec![0usize; n_groups];
716        BayesMixedGlm::new(Family::Binomial, endog, exog, exog_vc, ident, 0.5, 2.0).unwrap()
717    }
718
719    /// ELBO matches the reference value at the fixed start (mean=0, sd=exp(-0.5)).
720    /// Endog is irrelevant to the ELBO *base* integral, but the `endog·tm` term
721    /// is zero at mean=0 so this is robust to the exact endog draw.
722    #[test]
723    fn elbo_base_matches_reference_at_start() {
724        let m = binom_model();
725        let dim = m.dim();
726        let mean = vec![0.0; dim];
727        let sd = vec![(-0.5f64).exp(); dim];
728        // Reference value computed independently from the same model.
729        assert_abs_diff_eq!(m.vb_elbo(&mean, &sd), -27.081695786098585, epsilon = 1e-9);
730    }
731
732    /// Analytic gradient agrees with a finite-difference gradient of the ELBO
733    /// (wrt the `[mean; log sd]` reparameterization the optimizer uses).
734    #[test]
735    fn analytic_grad_matches_finite_difference() {
736        let m = binom_model();
737        let dim = m.dim();
738        // Pack [mean; log sd] and define the negative-ELBO objective.
739        let mut x = Array1::<f64>::zeros(2 * dim);
740        for k in 0..dim {
741            x[k] = 0.1 * (k as f64 - 3.0);
742            x[dim + k] = -0.4;
743        }
744        let obj = |x: &Array1<f64>| -> f64 {
745            let mean = x.slice(ndarray::s![..dim]).to_vec();
746            let sd: Vec<f64> = x
747                .slice(ndarray::s![dim..])
748                .iter()
749                .map(|&v| v.exp())
750                .collect();
751            -m.vb_elbo(&mean, &sd)
752        };
753        let fd = approx_fprime(&x, obj);
754
755        let mean = x.slice(ndarray::s![..dim]).to_vec();
756        let logsd = x.slice(ndarray::s![dim..]).to_vec();
757        let sd: Vec<f64> = logsd.iter().map(|&v| v.exp()).collect();
758        let (gm, mut gs) = m.vb_elbo_grad(&mean, &sd);
759        for k in 0..dim {
760            gs[k] *= sd[k];
761        }
762        for k in 0..dim {
763            assert_abs_diff_eq!(-gm[k], fd[k], epsilon = 1e-5);
764            assert_abs_diff_eq!(-gs[k], fd[dim + k], epsilon = 1e-5);
765        }
766    }
767
768    /// A small Poisson model fits and the ELBO gradient vanishes at the optimum.
769    #[test]
770    fn poisson_fit_reaches_stationary_point() {
771        let n_groups = 4usize;
772        let per = 3usize;
773        let n = n_groups * per;
774        let mut exog = Array2::<f64>::zeros((n, 2));
775        let mut exog_vc = Array2::<f64>::zeros((n, n_groups));
776        for i in 0..n {
777            exog[[i, 0]] = 1.0;
778            exog[[i, 1]] = -1.0 + 2.0 * i as f64 / (n as f64 - 1.0);
779            exog_vc[[i, i / per]] = 1.0;
780        }
781        let endog = array![1., 2., 1., 0., 1., 3., 2., 1., 4., 2., 1., 0.];
782        let ident = vec![0usize; n_groups];
783        let m = BayesMixedGlm::new(Family::Poisson, endog, exog, exog_vc, ident, 0.5, 2.0).unwrap();
784        let res = m.fit_vb(None, None, 10_000, 1e-8).unwrap();
785        assert!(res.converged, "did not converge, |g|={}", res.grad_norm);
786        assert!(res.grad_norm < 1e-7);
787    }
788}