Skip to main content

rdrobust_core/
rdplot.rs

1//! RD plot port -- `rdplot` (R rdplot.R): the binned scatter (per-bin means),
2//! the IMSE/MV bin-count selection, and the global polynomial curve coefficients.
3//!
4//! Implemented: the ES family of binselect (`es`, `esmv` (default),
5//! `espr`, `esmvpr`) with no covariates, no CI bands. QS spacing, covariate
6//! adjustment, and CI/sd are later increments. Parity: exact bin counts
7//! `J_l`/`J_r`, poly coefficients and per-bin means ~1e-8 vs R.
8
9use nalgebra::{DMatrix, DVector};
10
11use crate::kernel::eff_weight;
12use crate::linalg::{qr_xx_inv, vander};
13use crate::Kernel;
14
15/// Numeric outputs behind an RD plot: selected bin counts, global polynomial curve
16/// coefficients, and per-bin scatter means for each side.
17///
18/// Ports the subset of the R `rdplot` return object the numeric core needs (R
19/// rdplot.R:557-607): the selected counts `J`, the curve coefficients `coef`, and
20/// the per-bin x/y means that place each scatter dot. Plotting, CI bands, per-bin
21/// N/sd/SE, bin midpoints, and the QS/covariate paths are not part of this slice.
22/// Bin counts match R exactly; coefficients and per-bin means match R to ~1e-8.
23#[derive(Debug, Clone)]
24pub struct RdPlot {
25    /// Selected number of bins on the left side (`x < c`), post scale/nbins, clamped
26    /// to at least 1. R `J[1]` (rdplot.R:449-466).
27    pub j_l: usize,
28    /// Selected number of bins on the right side (`x >= c`), post scale/nbins, clamped
29    /// to at least 1. R `J[2]`.
30    pub j_r: usize,
31    /// Left-side global polynomial coefficients, length `p + 1` (orders 0..=p in `x - c`).
32    /// R `gamma_p1_l` / `coef[,"Left"]` (rdplot.R:206-225).
33    pub coef_l: Vec<f64>,
34    /// Right-side global polynomial coefficients, length `p + 1`. R `gamma_p1_r` /
35    /// `coef[,"Right"]`.
36    pub coef_r: Vec<f64>,
37    /// Sorted unique non-empty left bin ids (negative: `-j_l` leftmost, `-1` just below
38    /// `c`). R `sort(unique(bin_x_l))` (rdplot.R:484).
39    pub bin_l: Vec<i64>,
40    /// Sorted unique non-empty right bin ids (`1..=j_r`, ascending in x). R
41    /// `sort(unique(bin_x_r))`.
42    pub bin_r: Vec<i64>,
43    /// Per-bin mean of `x` on the left, ordered by sorted bin id (the scatter dot's
44    /// x-coordinate). One entry per non-empty bin. R `tapply(x_l, bin_x_l, mean)`
45    /// (rdplot.R:488-490).
46    pub mean_x_l: Vec<f64>,
47    /// Per-bin mean of `y` on the left, ordered by sorted bin id (the scatter dot's
48    /// y-coordinate). R `tapply(y_l, bin_x_l, mean)`.
49    pub mean_y_l: Vec<f64>,
50    /// Per-bin mean of `x` on the right, ordered by sorted bin id. R
51    /// `tapply(x_r, bin_x_r, mean)`.
52    pub mean_x_r: Vec<f64>,
53    /// Per-bin mean of `y` on the right, ordered by sorted bin id. R
54    /// `tapply(y_r, bin_x_r, mean)`.
55    pub mean_y_r: Vec<f64>,
56}
57
58/// Row-scale a matrix by a per-row vector (`diag(w) * m`).
59fn row_scale(m: &DMatrix<f64>, w: &[f64]) -> DMatrix<f64> {
60    let mut out = m.clone();
61    for i in 0..m.nrows() {
62        for j in 0..m.ncols() {
63            out[(i, j)] *= w[i];
64        }
65    }
66    out
67}
68
69/// Sample variance (ddof=1), R `var`.
70fn var_y(y: &[f64]) -> f64 {
71    let n = y.len() as f64;
72    let mean = y.iter().sum::<f64>() / n;
73    y.iter().map(|&v| (v - mean) * (v - mean)).sum::<f64>() / (n - 1.0)
74}
75
76/// Global weighted local-polynomial fit of order `p` over a side (kernel weights
77/// at bandwidth `h`, times user weights `wt`; points outside the window get weight
78/// 0). Returns the (p+1) coefficients (R rdplot.R:206-225,212-214).
79fn poly_fit(
80    x: &[f64],
81    y: &[f64],
82    c: f64,
83    p: usize,
84    h: f64,
85    kernel: Kernel,
86    wt: Option<&[f64]>,
87) -> Vec<f64> {
88    let w = eff_weight(x, c, h, kernel, wt);
89    let u: Vec<f64> = x.iter().map(|&xi| xi - c).collect();
90    let r_p = vander(&u, p);
91    let wsqrt: Vec<f64> = w.iter().map(|v| v.sqrt()).collect();
92    let inv_g = qr_xx_inv(&row_scale(&r_p, &wsqrt));
93    let rw = row_scale(&r_p, &w);
94    let yv = DVector::from_column_slice(y);
95    let gamma = &inv_g * (rw.transpose() * &yv);
96    gamma.iter().copied().collect()
97}
98
99/// The four ES bin-count quantities for one side (rdplot.R:276-388, ES half).
100struct EsPilot {
101    hat_dw: f64, // J_es_hat_dw (IMSE, spacings sigma2)
102    chk_dw: f64, // J_es_chk_dw (IMSE, poly-reg sigma2)
103    hat_mv: f64, // J_es_hat_mv (mimicking-variance, spacings)
104    chk_mv: f64, // J_es_chk_mv (mimicking-variance, poly-reg)
105}
106
107/// Vandermonde derivative design: col j = j * x^(j-1) (col 0 = 0), n x (k+1).
108fn dvander(x: &[f64], k: usize) -> DMatrix<f64> {
109    let n = x.len();
110    let mut d = DMatrix::zeros(n, k + 1);
111    for i in 0..n {
112        for j in 1..=k {
113            d[(i, j)] = j as f64 * x[i].powi((j - 1) as i32);
114        }
115    }
116    d
117}
118
119/// ES pilot for one side (R rdplot.R:276-388). `x`/`y` are the side's points,
120/// `range = |c - x_endpoint|` (support half-range), `n` is the TOTAL sample size.
121fn es_pilot(x: &[f64], y: &[f64], range: f64, n: usize, vy: f64) -> EsPilot {
122    // pilot order k (4 -> 3 -> 2 on singular Gram), UNWEIGHTED, RAW x
123    let mut k = 4usize;
124    let (rk, inv_gk) = loop {
125        let rk = vander(x, k);
126        let g = rk.transpose() * &rk;
127        match g.cholesky() {
128            Some(_) => break (rk.clone(), qr_xx_inv(&rk)),
129            None if k > 2 => k -= 1,
130            None => break (rk.clone(), qr_xx_inv(&rk)),
131        }
132    };
133    let yv = DVector::from_column_slice(y);
134    let y2: Vec<f64> = y.iter().map(|&v| v * v).collect();
135    let y2v = DVector::from_column_slice(&y2);
136    let gamma_k1 = &inv_gk * (rk.transpose() * &yv);
137    let gamma_k2 = &inv_gk * (rk.transpose() * &y2v);
138
139    // mu's at raw points
140    let drk = dvander(x, k);
141    let mu1_hat = &drk * &gamma_k1; // fitted first derivative
142
143    // sort (x, y) ascending by x for the spacings estimators
144    let mut order: Vec<usize> = (0..x.len()).collect();
145    order.sort_by(|&a, &b| x[a].total_cmp(&x[b]));
146    let xs: Vec<f64> = order.iter().map(|&i| x[i]).collect();
147    let ys: Vec<f64> = order.iter().map(|&i| y[i]).collect();
148    let m = xs.len();
149    let dxi: Vec<f64> = (1..m).map(|i| xs[i] - xs[i - 1]).collect();
150    let dyi: Vec<f64> = (1..m).map(|i| ys[i] - ys[i - 1]).collect();
151    let x_bar: Vec<f64> = (1..m).map(|i| 0.5 * (xs[i] + xs[i - 1])).collect();
152
153    // sigma2 at midpoints (poly-reg estimator), negatives -> var_y
154    let rk_bar = vander(&x_bar, k);
155    let mu0_i = &rk_bar * &gamma_k1;
156    let mu2_i = &rk_bar * &gamma_k2;
157    let sigma2_bar: Vec<f64> = (0..x_bar.len())
158        .map(|i| {
159            let s = mu2_i[i] - mu0_i[i] * mu0_i[i];
160            if s < 0.0 {
161                vy
162            } else {
163                s
164            }
165        })
166        .collect();
167
168    let nf = n as f64;
169    let sum_mu1_sq: f64 = mu1_hat.iter().map(|v| v * v).sum();
170    let b_es = (range * range / (12.0 * nf)) * sum_mu1_sq;
171    let v_hat = (0.5 / range)
172        * dxi
173            .iter()
174            .zip(&dyi)
175            .map(|(&dx, &dy)| dx * dy * dy)
176            .sum::<f64>();
177    let v_chk = (1.0 / range)
178        * dxi
179            .iter()
180            .zip(&sigma2_bar)
181            .map(|(&dx, &s)| dx * s)
182            .sum::<f64>();
183
184    let j_fun = |b: f64, v: f64| (((2.0 * b) / v) * nf).powf(1.0 / 3.0).ceil();
185    let nlogn = nf / (nf.ln() * nf.ln());
186    EsPilot {
187        hat_dw: j_fun(b_es, v_hat),
188        chk_dw: j_fun(b_es, v_chk),
189        hat_mv: ((vy / v_hat) * nlogn).ceil(),
190        chk_mv: ((vy / v_chk) * nlogn).ceil(),
191    }
192}
193
194/// R `findInterval(v, knots, rightmost.closed=TRUE)`: count of knots <= v, with the
195/// top knot folded into the last interval. knots ascending, length J+1.
196fn find_interval(v: f64, knots: &[f64]) -> usize {
197    let j = knots.len() - 1;
198    if v < knots[0] {
199        return 0;
200    }
201    if v >= knots[j] {
202        return j;
203    }
204    knots.iter().filter(|&&k| k <= v).count()
205}
206
207/// Per-bin means grouped by bin id (ascending), dropping empty bins (R `tapply`).
208///
209/// Single forward pass over `bins` in increasing index order, accumulating
210/// `(sum_x, sum_y, count)` per id in a `BTreeMap` (keys iterate ascending, matching
211/// the sorted-unique-id order). Accumulating in index order keeps each bin's
212/// floating-point sum bit-identical to the per-id-scan form.
213fn bin_means(x: &[f64], y: &[f64], bins: &[i64]) -> (Vec<i64>, Vec<f64>, Vec<f64>) {
214    use std::collections::BTreeMap;
215    let mut acc: BTreeMap<i64, (f64, f64, usize)> = BTreeMap::new();
216    for k in 0..bins.len() {
217        let e = acc.entry(bins[k]).or_insert((0.0, 0.0, 0));
218        e.0 += x[k];
219        e.1 += y[k];
220        e.2 += 1;
221    }
222    let mut ids = Vec::with_capacity(acc.len());
223    let mut mx = Vec::with_capacity(acc.len());
224    let mut my = Vec::with_capacity(acc.len());
225    for (&id, &(sx, sy, cnt)) in &acc {
226        ids.push(id);
227        mx.push(sx / cnt as f64);
228        my.push(sy / cnt as f64);
229    }
230    (ids, mx, my)
231}
232
233/// Computes the data behind an RD plot for the evenly-spaced (ES) binselect family:
234/// the global polynomial curve coefficients, the IMSE/MV bin counts, and the per-bin
235/// scatter means. Ports R `rdplot` (rdplot.R), ES half only, no covariates and no CI.
236///
237/// Splits the sample at `c` (`x < c` left, `x >= c` right), fits one weighted
238/// order-`p` polynomial per side over the full side range, selects `J_l`/`J_r` via the
239/// order-4 ES pilot regressions, lays evenly-spaced breakpoints, assigns each point
240/// with R's `findInterval` convention, and returns per-bin x/y means (empty bins
241/// dropped). Bin counts are exact vs R; coefficients and means match to ~1e-8.
242///
243/// # Arguments
244/// - `y`: outcome values.
245/// - `x`: running variable, parallel to `y`, need not be sorted.
246/// - `c`: cutoff; the point `x == c` falls on the right side.
247/// - `p`: global polynomial order for the curve (R default 4).
248/// - `kernel`: kernel for the polynomial-fit weights (uniform/triangular/Epanechnikov).
249/// - `binselect`: ES variant string, one of `es`, `espr`, `esmv` (also matched by `""`),
250///   or `esmvpr`. Any other value, including the QS variants, triggers `unimplemented!`.
251/// - `scale_l`, `scale_r`: multipliers on the selected per-side bin count (R default 1).
252/// - `nbins_l`, `nbins_r`: optional manual bin counts that override binselect per side.
253/// - `wt`: optional unit weights that multiply the kernel weights in the curve fit only;
254///   they do not enter the pilot regressions or bin construction.
255///
256/// # Panics
257/// Panics via `unimplemented!` when `binselect` is not one of the four supported ES
258/// strings (the QS family is a later increment).
259#[allow(clippy::too_many_arguments)]
260pub fn rdplot(
261    y: &[f64],
262    x: &[f64],
263    c: f64,
264    p: usize,
265    kernel: Kernel,
266    binselect: &str,
267    scale_l: f64,
268    scale_r: f64,
269    nbins_l: Option<usize>,
270    nbins_r: Option<usize>,
271    wt: Option<&[f64]>,
272) -> RdPlot {
273    let x_min = x.iter().cloned().fold(f64::INFINITY, f64::min);
274    let x_max = x.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
275    let range_l = c - x_min;
276    let range_r = x_max - c;
277
278    // side split: x<c left, x>=c right (carry user weights for the poly fit only)
279    let (mut xl, mut yl, mut wl, mut xr, mut yr, mut wr) = (
280        Vec::new(),
281        Vec::new(),
282        Vec::new(),
283        Vec::new(),
284        Vec::new(),
285        Vec::new(),
286    );
287    for i in 0..x.len() {
288        if x[i] < c {
289            xl.push(x[i]);
290            yl.push(y[i]);
291            if let Some(ww) = wt {
292                wl.push(ww[i]);
293            }
294        } else {
295            xr.push(x[i]);
296            yr.push(y[i]);
297            if let Some(ww) = wt {
298                wr.push(ww[i]);
299            }
300        }
301    }
302    let wl_opt = wt.map(|_| wl.as_slice());
303    let wr_opt = wt.map(|_| wr.as_slice());
304    let n = x.len();
305
306    // global poly curve coefficients (h = full side range, default; weighted)
307    let coef_l = poly_fit(&xl, &yl, c, p, range_l, kernel, wl_opt);
308    let coef_r = poly_fit(&xr, &yr, c, p, range_r, kernel, wr_opt);
309
310    // ES pilot + binselect dispatch
311    let vy_l = var_y(&yl);
312    let vy_r = var_y(&yr);
313    let pl = es_pilot(&xl, &yl, range_l, n, vy_l);
314    let pr = es_pilot(&xr, &yr, range_r, n, vy_r);
315    let pick = |pe: &EsPilot| -> f64 {
316        match binselect {
317            "es" => pe.hat_dw,
318            "espr" => pe.chk_dw,
319            "esmv" | "" => pe.hat_mv,
320            "esmvpr" => pe.chk_mv,
321            other => unimplemented!("binselect {other} not yet ported (ES family only)"),
322        }
323    };
324    let j_l = nbins_l
325        .unwrap_or_else(|| (scale_l * pick(&pl)).ceil() as usize)
326        .max(1);
327    let j_r = nbins_r
328        .unwrap_or_else(|| (scale_r * pick(&pr)).ceil() as usize)
329        .max(1);
330
331    // ES breakpoints: x_min + i*jump  (J+1 knots), last = endpoint
332    let jump_l = range_l / j_l as f64;
333    let jump_r = range_r / j_r as f64;
334    let knots_l: Vec<f64> = (0..=j_l).map(|i| x_min + i as f64 * jump_l).collect();
335    let knots_r: Vec<f64> = (0..=j_r).map(|i| c + i as f64 * jump_r).collect();
336
337    // bin assignment (R findInterval; left ids negative)
338    let bins_l: Vec<i64> = xl
339        .iter()
340        .map(|&v| find_interval(v, &knots_l) as i64 - j_l as i64 - 1)
341        .collect();
342    let bins_r: Vec<i64> = xr
343        .iter()
344        .map(|&v| find_interval(v, &knots_r) as i64)
345        .collect();
346
347    let (bin_l, mean_x_l, mean_y_l) = bin_means(&xl, &yl, &bins_l);
348    let (bin_r, mean_x_r, mean_y_r) = bin_means(&xr, &yr, &bins_r);
349
350    RdPlot {
351        j_l,
352        j_r,
353        coef_l,
354        coef_r,
355        bin_l,
356        bin_r,
357        mean_x_l,
358        mean_y_l,
359        mean_x_r,
360        mean_y_r,
361    }
362}