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}