Skip to main content

solow_discrete/
conditional.rs

1//! Conditional (fixed-effects) maximum-likelihood count / choice models.
2//!
3//! These estimators condition the group-specific intercept out of the
4//! likelihood, so the within-group fixed effects never have to be estimated.
5//! What remains is a *conditional* likelihood that depends only on the slope
6//! coefficients `β` — there is **no intercept** in the design.
7//!
8//! * [`ConditionalLogit`] — conditional logistic regression. Within each group
9//!   the conditional likelihood is the Cox/Chamberlain form: given that the
10//!   group has `n₁` successes, the probability of the observed success pattern
11//!   is `exp(Σ_{i:yᵢ=1} xᵢ·β) / Σ_{S} exp(Σ_{i∈S} xᵢ·β)`, where `S` ranges over
12//!   all size-`n₁` subsets of the group. The denominator is evaluated by the
13//!   standard `O(n·n₁)` Howard recursion.
14//! * [`ConditionalPoisson`] — conditional Poisson regression. Conditioning on
15//!   the group total `Σ yᵢ` turns the group contribution into a multinomial,
16//!   giving the group log-likelihood
17//!   `Σ yᵢ (xᵢ·β) − (Σ yᵢ) log Σ exp(xᵢ·β)`.
18//!
19//! ## Grouping (matches the reference exactly)
20//!
21//! Observations are bucketed by group code **in first-appearance order**. A
22//! group with no within-group variation in the response (`std(y) == 0`) carries
23//! no information about `β` and is dropped, exactly as the reference does; the
24//! reported `nobs` counts only the retained observations.
25//!
26//! ## Estimation
27//!
28//! The conditional log-likelihood is concave, so a full Newton iteration on the
29//! analytic score and a finite-difference Hessian of that score converges to the
30//! same optimum as the reference's BFGS fit. The covariance is `(−H)⁻¹` with the
31//! Hessian formed as the (central-difference) Jacobian of the analytic score —
32//! the same object the reference inverts for its standard errors.
33
34use ndarray::{Array1, Array2};
35use solow_core::error::{Error, Result};
36use solow_core::tools::{ensure_all_finite, ensure_all_finite_2d};
37use solow_distributions::{norm_ppf, norm_sf};
38use solow_linalg::inv;
39use solow_optimize::newton_stationary;
40
41/// The conditional family selected for estimation.
42#[derive(Clone, Copy, Debug, PartialEq, Eq)]
43enum Kind {
44    Logit,
45    Poisson,
46}
47
48/// A single retained group: its response, design rows, and sufficient stats.
49#[derive(Clone, Debug)]
50struct Group {
51    /// Response values for the group's rows.
52    y: Array1<f64>,
53    /// Design rows for the group, `gᵢ × k`.
54    x: Array2<f64>,
55    /// `xᵀy` for the group (length `k`) — a sufficient statistic.
56    xy: Array1<f64>,
57    /// Number of successes / total count `Σ yᵢ`.
58    n1: f64,
59}
60
61/// A conditional fixed-effects model awaiting estimation.
62#[derive(Clone, Debug)]
63pub struct ConditionalModel {
64    groups: Vec<Group>,
65    kind: Kind,
66    k_params: usize,
67    nobs: usize,
68    n_groups: usize,
69    maxiter: usize,
70    gtol: f64,
71}
72
73/// Conditional logistic regression for grouped binary data.
74#[derive(Clone, Debug)]
75pub struct ConditionalLogit(ConditionalModel);
76
77/// Conditional Poisson regression for grouped count data.
78#[derive(Clone, Debug)]
79pub struct ConditionalPoisson(ConditionalModel);
80
81macro_rules! wrapper {
82    ($name:ident, $kind:expr, $doc:literal) => {
83        impl $name {
84            #[doc = $doc]
85            ///
86            /// `exog` must **not** contain an intercept column (group effects are
87            /// conditioned out). `groups` assigns each row to a group code.
88            /// Returns an error on shape mismatch or if a constant column is
89            /// present.
90            pub fn new(endog: Array1<f64>, exog: Array2<f64>, groups: &[i64]) -> Result<Self> {
91                Ok($name(ConditionalModel::new(endog, exog, groups, $kind)?))
92            }
93
94            /// Estimate by Newton's method and return the fitted results.
95            pub fn fit(&self) -> Result<ConditionalResults> {
96                self.0.fit()
97            }
98
99            /// The underlying generic conditional model.
100            pub fn model(&self) -> &ConditionalModel {
101                &self.0
102            }
103        }
104    };
105}
106
107wrapper!(
108    ConditionalLogit,
109    Kind::Logit,
110    "Build a conditional logistic regression model from grouped binary data."
111);
112wrapper!(
113    ConditionalPoisson,
114    Kind::Poisson,
115    "Build a conditional Poisson regression model from grouped count data."
116);
117
118impl ConditionalModel {
119    fn new(endog: Array1<f64>, exog: Array2<f64>, groups: &[i64], kind: Kind) -> Result<Self> {
120        let n = endog.len();
121        if exog.nrows() != n {
122            return Err(Error::Shape("endog length != exog rows".into()));
123        }
124        if groups.len() != n {
125            return Err(Error::Shape("endog length != groups length".into()));
126        }
127        ensure_all_finite(&endog.view(), "endog")?;
128        ensure_all_finite_2d(&exog.view(), "exog")?;
129        let k = exog.ncols();
130        // Reject an intercept column — conditional models must not have one.
131        for j in 0..k {
132            let col = exog.column(j);
133            let Some(&first) = col.iter().next() else {
134                continue;
135            };
136            if first != 0.0 && col.iter().all(|&v| v == first) {
137                return Err(Error::Shape(
138                    "conditional models should not have an intercept in exog".into(),
139                ));
140            }
141        }
142
143        // Bucket rows by group code in first-appearance order.
144        let mut order: Vec<i64> = Vec::new();
145        let mut row_ix: std::collections::HashMap<i64, Vec<usize>> =
146            std::collections::HashMap::new();
147        for (i, &g) in groups.iter().enumerate() {
148            row_ix.entry(g).or_insert_with(|| {
149                order.push(g);
150                Vec::new()
151            });
152            row_ix.get_mut(&g).unwrap().push(i);
153        }
154
155        let mut grps: Vec<Group> = Vec::new();
156        let mut nobs = 0usize;
157        for g in order {
158            let ix = &row_ix[&g];
159            // Drop groups with no within-group variance in the response.
160            let y0 = endog[ix[0]];
161            if ix.iter().all(|&i| endog[i] == y0) {
162                continue;
163            }
164            let gi = ix.len();
165            let mut y = Array1::<f64>::zeros(gi);
166            let mut x = Array2::<f64>::zeros((gi, k));
167            for (r, &i) in ix.iter().enumerate() {
168                y[r] = endog[i];
169                for c in 0..k {
170                    x[[r, c]] = exog[[i, c]];
171                }
172            }
173            let xy = x.t().dot(&y);
174            let n1 = y.sum();
175            nobs += gi;
176            grps.push(Group { y, x, xy, n1 });
177        }
178
179        if grps.is_empty() {
180            return Err(Error::Shape(
181                "no groups with within-group variation remain".into(),
182            ));
183        }
184
185        let n_groups = grps.len();
186        Ok(ConditionalModel {
187            groups: grps,
188            kind,
189            k_params: k,
190            nobs,
191            n_groups,
192            maxiter: 100,
193            gtol: 1e-12,
194        })
195    }
196
197    /// Number of observations retained after dropping invariant groups.
198    pub fn nobs(&self) -> usize {
199        self.nobs
200    }
201
202    /// Number of groups retained.
203    pub fn n_groups(&self) -> usize {
204        self.n_groups
205    }
206
207    /// Conditional log-likelihood at `params`.
208    fn loglike(&self, params: &Array1<f64>) -> f64 {
209        match self.kind {
210            Kind::Logit => self.groups.iter().map(|g| logit_grp_ll(g, params)).sum(),
211            Kind::Poisson => self.groups.iter().map(|g| poisson_grp_ll(g, params)).sum(),
212        }
213    }
214
215    /// Analytic conditional score (gradient) at `params`.
216    fn score(&self, params: &Array1<f64>) -> Array1<f64> {
217        let mut s = Array1::<f64>::zeros(self.k_params);
218        match self.kind {
219            Kind::Logit => {
220                for g in &self.groups {
221                    s += &logit_grp_score(g, params);
222                }
223            }
224            Kind::Poisson => {
225                for g in &self.groups {
226                    s += &poisson_grp_score(g, params);
227                }
228            }
229        }
230        s
231    }
232
233    /// Hessian as the central-difference Jacobian of the analytic score.
234    ///
235    /// This is exactly the object the reference inverts to form standard errors
236    /// (it differentiates the same analytic score). Because the score is exact
237    /// the finite-difference Jacobian agrees with the true Hessian to ~1e-9.
238    fn hessian(&self, params: &Array1<f64>) -> Array2<f64> {
239        let k = self.k_params;
240        // Central-difference Jacobian of the (vector) score.
241        let mut h = Array2::<f64>::zeros((k, k));
242        for j in 0..k {
243            let step = 1e-6 * (1.0 + params[j].abs());
244            let mut pp = params.clone();
245            let mut pm = params.clone();
246            pp[j] += step;
247            pm[j] -= step;
248            let sp = self.score(&pp);
249            let sm = self.score(&pm);
250            for i in 0..k {
251                h[[i, j]] = (sp[i] - sm[i]) / (2.0 * step);
252            }
253        }
254        // Symmetrize (the true Hessian is symmetric).
255        for i in 0..k {
256            for j in (i + 1)..k {
257                let v = 0.5 * (h[[i, j]] + h[[j, i]]);
258                h[[i, j]] = v;
259                h[[j, i]] = v;
260            }
261        }
262        h
263    }
264
265    fn start(&self) -> Array1<f64> {
266        Array1::<f64>::zeros(self.k_params)
267    }
268
269    /// Estimate by full Newton steps and assemble [`ConditionalResults`].
270    pub fn fit(&self) -> Result<ConditionalResults> {
271        let fgh = |p: &Array1<f64>| {
272            let f = -self.loglike(p);
273            let g = self.score(p).mapv(|v| -v);
274            let h = self.hessian(p).mapv(|v| -v);
275            (f, g, h)
276        };
277        let opt = newton_stationary(&self.start(), fgh, self.maxiter, self.gtol)?;
278        let params = opt.x;
279        let h = self.hessian(&params);
280        let neg_h = h.mapv(|v| -v);
281        let cov = inv(&neg_h)?;
282        Ok(ConditionalResults::new(self, params, cov, opt.converged))
283    }
284}
285
286// --------------------------------------------------------------------------- //
287//  Per-group conditional-logit pieces (Howard recursion)                      //
288// --------------------------------------------------------------------------- //
289
290/// Denominator `Σ_{|S|=n₁} Π_{i∈S} exp(xᵢ·β)` for a group, via the recursion
291/// `f(t,k) = f(t−1,k) + f(t−1,k−1)·e_{t}` with `f(t,0)=1`, `f(t,k)=0` for `t<k`.
292fn logit_denom(exb: &[f64], n1: usize) -> f64 {
293    let t = exb.len();
294    // dp[k] holds f(·, k); iterate t from 1..=t.
295    let mut dp = vec![0.0f64; n1 + 1];
296    dp[0] = 1.0;
297    for (i, &e) in exb.iter().enumerate().take(t) {
298        // Update in decreasing k to reuse f(t-1, k-1).
299        let kmax = (i + 1).min(n1);
300        for k in (1..=kmax).rev() {
301            dp[k] += dp[k - 1] * e;
302        }
303    }
304    dp[n1]
305}
306
307/// Group log-likelihood for conditional logit: `xy·β − log(denom)`.
308fn logit_grp_ll(g: &Group, params: &Array1<f64>) -> f64 {
309    let exb: Vec<f64> = g.x.dot(params).iter().map(|v| v.exp()).collect();
310    let n1 = g.n1.round() as usize;
311    let denom = logit_denom(&exb, n1);
312    g.xy.dot(params) - denom.ln()
313}
314
315/// Group score for conditional logit: `xy − (∇denom)/denom`.
316///
317/// `∇denom` is accumulated by the value/gradient recursion: with
318/// `s(t,k) = (value, grad)`, `s(t,k) = s(t−1,k) + e_t · (s(t−1,k−1) shifted)`,
319/// where the gradient also gains `value(t−1,k−1) · e_t · x_t`.
320fn logit_grp_score(g: &Group, params: &Array1<f64>) -> Array1<f64> {
321    let k = params.len();
322    let xb = g.x.dot(params);
323    let exb: Vec<f64> = xb.iter().map(|v| v.exp()).collect();
324    let n1 = g.n1.round() as usize;
325    let t = exb.len();
326
327    // val[kk] = f(·, kk); grad[kk] = ∇ f(·, kk).
328    let mut val = vec![0.0f64; n1 + 1];
329    let mut grad: Vec<Array1<f64>> = (0..=n1).map(|_| Array1::<f64>::zeros(k)).collect();
330    val[0] = 1.0;
331    for (i, &e) in exb.iter().enumerate().take(t) {
332        let xi = g.x.row(i);
333        let kmax = (i + 1).min(n1);
334        for kk in (1..=kmax).rev() {
335            // new grad[kk] += e * grad[kk-1] + (val[kk-1] * e) * x_i
336            let prev_val = val[kk - 1];
337            // grad[kk] += e * grad[kk-1]
338            let add = &grad[kk - 1] * e;
339            grad[kk] = &grad[kk] + &add;
340            // grad[kk] += val[kk-1] * e * x_i
341            for c in 0..k {
342                grad[kk][c] += prev_val * e * xi[c];
343            }
344            // val[kk] += e * val[kk-1]
345            val[kk] += e * prev_val;
346        }
347    }
348    let denom = val[n1];
349    let gdenom = &grad[n1];
350    &g.xy - &(gdenom / denom)
351}
352
353// --------------------------------------------------------------------------- //
354//  Per-group conditional-Poisson pieces                                       //
355// --------------------------------------------------------------------------- //
356
357/// Group log-likelihood for conditional Poisson: `Σ yᵢ xᵢβ − (Σy) log Σ e^{xᵢβ}`.
358fn poisson_grp_ll(g: &Group, params: &Array1<f64>) -> f64 {
359    let xb = g.x.dot(params);
360    let mut ll = g.y.dot(&xb);
361    let s: f64 = xb.iter().map(|v| v.exp()).sum();
362    ll -= g.n1 * s.ln();
363    ll
364}
365
366/// Group score for conditional Poisson: `xᵀy − (Σy) (Σ e^{xᵢβ} xᵢ)/(Σ e^{xᵢβ})`.
367fn poisson_grp_score(g: &Group, params: &Array1<f64>) -> Array1<f64> {
368    let xb = g.x.dot(params);
369    let exb = xb.mapv(f64::exp);
370    let s: f64 = exb.sum();
371    // weighted = Σ e^{xᵢβ} xᵢ
372    let weighted = g.x.t().dot(&exb);
373    &g.xy - &(&weighted * (g.n1 / s))
374}
375
376/// The fitted result of a conditional fixed-effects model.
377#[derive(Clone, Debug)]
378pub struct ConditionalResults {
379    /// Estimated slope coefficients `β̂` (no intercept).
380    pub params: Array1<f64>,
381    /// Standard errors `√diag((−H)⁻¹)`.
382    pub bse: Array1<f64>,
383    /// z-statistics `params / bse`.
384    pub tvalues: Array1<f64>,
385    /// Two-sided p-values `2·Φ̄(|z|)`.
386    pub pvalues: Array1<f64>,
387
388    /// Number of observations retained.
389    pub nobs: f64,
390    /// Number of groups retained.
391    pub n_groups: usize,
392
393    /// Maximized conditional log-likelihood.
394    pub llf: f64,
395
396    /// Coefficient covariance `(−H)⁻¹`.
397    pub cov_params: Array2<f64>,
398
399    /// Whether Newton converged.
400    pub converged: bool,
401}
402
403impl ConditionalResults {
404    fn new(
405        model: &ConditionalModel,
406        params: Array1<f64>,
407        cov_params: Array2<f64>,
408        converged: bool,
409    ) -> ConditionalResults {
410        let k = params.len();
411        let mut bse = Array1::<f64>::zeros(k);
412        for i in 0..k {
413            bse[i] = cov_params[[i, i]].sqrt();
414        }
415        let tvalues = &params / &bse;
416        let pvalues = tvalues.mapv(|z| 2.0 * norm_sf(z.abs()));
417        let llf = model.loglike(&params);
418
419        ConditionalResults {
420            params,
421            bse,
422            tvalues,
423            pvalues,
424            nobs: model.nobs as f64,
425            n_groups: model.n_groups,
426            llf,
427            cov_params,
428            converged,
429        }
430    }
431
432    /// Confidence interval for each coefficient at level `1 − alpha` (normal).
433    pub fn conf_int(&self, alpha: f64) -> Array2<f64> {
434        let q = norm_ppf(1.0 - alpha / 2.0);
435        let k = self.params.len();
436        let mut out = Array2::<f64>::zeros((k, 2));
437        for i in 0..k {
438            out[[i, 0]] = self.params[i] - q * self.bse[i];
439            out[[i, 1]] = self.params[i] + q * self.bse[i];
440        }
441        out
442    }
443}
444
445#[cfg(test)]
446mod tests {
447    use super::*;
448    use approx::assert_abs_diff_eq;
449    use ndarray::array;
450    use solow_optimize::approx_fprime;
451
452    fn data() -> (Array1<f64>, Array2<f64>, Vec<i64>) {
453        // 6 groups of 3; binary-ish response with within-group variation.
454        let y = array![
455            0.0, 1.0, 1.0, // g0
456            1.0, 0.0, 1.0, // g1
457            0.0, 0.0, 1.0, // g2
458            1.0, 1.0, 0.0, // g3
459            0.0, 1.0, 0.0, // g4
460            1.0, 0.0, 0.0, // g5
461        ];
462        let xcol1 = array![
463            0.5, -1.2, 0.3, 2.1, -0.7, 1.4, -0.2, 0.9, -1.5, 0.6, 0.1, -0.4, 1.1, -0.9, 0.8, -0.3,
464            0.2, -0.6
465        ];
466        let xcol2 = array![
467            -0.3, 0.7, -1.1, 0.4, 1.2, -0.5, 0.8, -0.2, 0.6, -1.3, 0.9, 0.1, -0.7, 0.5, -0.4, 1.0,
468            -0.8, 0.3
469        ];
470        let mut x = Array2::<f64>::zeros((18, 2));
471        x.column_mut(0).assign(&xcol1);
472        x.column_mut(1).assign(&xcol2);
473        let groups: Vec<i64> = (0..6).flat_map(|g| [g, g, g]).collect();
474        (y, x, groups)
475    }
476
477    #[test]
478    fn logit_score_zero_at_optimum() {
479        let (y, x, g) = data();
480        let m = ConditionalLogit::new(y, x, &g).unwrap();
481        let res = m.fit().unwrap();
482        assert!(res.converged);
483        let s = m.0.score(&res.params);
484        assert!(s.dot(&s).sqrt() < 1e-8, "score {}", s.dot(&s).sqrt());
485    }
486
487    #[test]
488    fn logit_analytic_score_matches_fd() {
489        let (y, x, g) = data();
490        let m = ConditionalLogit::new(y, x, &g).unwrap();
491        let p = array![0.2, -0.3];
492        let s = m.0.score(&p);
493        let fd = approx_fprime(&p, |q| m.0.loglike(q));
494        for i in 0..p.len() {
495            assert_abs_diff_eq!(s[i], fd[i], epsilon = 1e-6);
496        }
497    }
498
499    #[test]
500    fn poisson_score_zero_at_optimum() {
501        let y = array![
502            2.0, 0.0, 3.0, // g0
503            1.0, 4.0, 0.0, // g1
504            5.0, 1.0, 2.0, // g2
505            0.0, 3.0, 1.0, // g3
506            2.0, 6.0, 1.0, // g4
507            1.0, 0.0, 4.0, // g5
508        ];
509        let xcol1 = array![
510            0.5, -1.2, 0.3, 2.1, -0.7, 1.4, -0.2, 0.9, -1.5, 0.6, 0.1, -0.4, 1.1, -0.9, 0.8, -0.3,
511            0.2, -0.6
512        ];
513        let xcol2 = array![
514            -0.3, 0.7, -1.1, 0.4, 1.2, -0.5, 0.8, -0.2, 0.6, -1.3, 0.9, 0.1, -0.7, 0.5, -0.4, 1.0,
515            -0.8, 0.3
516        ];
517        let mut x = Array2::<f64>::zeros((18, 2));
518        x.column_mut(0).assign(&xcol1);
519        x.column_mut(1).assign(&xcol2);
520        let groups: Vec<i64> = (0..6).flat_map(|g| [g, g, g]).collect();
521        let m = ConditionalPoisson::new(y, x, &groups).unwrap();
522        let res = m.fit().unwrap();
523        assert!(res.converged);
524        let s = m.0.score(&res.params);
525        assert!(s.dot(&s).sqrt() < 1e-8, "score {}", s.dot(&s).sqrt());
526    }
527
528    #[test]
529    fn poisson_analytic_score_matches_fd() {
530        let y = array![
531            2.0, 0.0, 3.0, 1.0, 4.0, 0.0, 5.0, 1.0, 2.0, 0.0, 3.0, 1.0, 2.0, 6.0, 1.0, 1.0, 0.0,
532            4.0
533        ];
534        let xcol1 = array![
535            0.5, -1.2, 0.3, 2.1, -0.7, 1.4, -0.2, 0.9, -1.5, 0.6, 0.1, -0.4, 1.1, -0.9, 0.8, -0.3,
536            0.2, -0.6
537        ];
538        let mut x = Array2::<f64>::zeros((18, 1));
539        x.column_mut(0).assign(&xcol1);
540        let groups: Vec<i64> = (0..6).flat_map(|g| [g, g, g]).collect();
541        let m = ConditionalPoisson::new(y, x, &groups).unwrap();
542        let p = array![0.25];
543        let s = m.0.score(&p);
544        let fd = approx_fprime(&p, |q| m.0.loglike(q));
545        assert_abs_diff_eq!(s[0], fd[0], epsilon = 1e-6);
546    }
547
548    #[test]
549    fn rejects_intercept() {
550        let (y, _x, g) = data();
551        let xc = Array2::<f64>::ones((18, 1));
552        assert!(ConditionalLogit::new(y, xc, &g).is_err());
553    }
554}