M3: Weighted Regression — Design Spec

Date: 2026-04-04 Milestone: 3 (Core Econometrics) — Important tier Scope: WLS support for all four estimators (OLS, FE-OLS, GLM, 2SLS) with robust and clustered SEs

Motivation

Weighted regression (lm(..., weights=pop), feols(..., weights=~pop)) is common in applied econ, especially in DiD papers where observations represent different population sizes. We already parse these functions but silently ignore the weights argument. This spec adds full WLS execution across every estimator we support.

R Syntax Patterns

# Base R OLS
lm(y ~ x1 + x2, data = df, weights = pop)

# fixest FE-OLS (formula-style ~col or bare col)
feols(y ~ x1 + x2 | state + year, data = df, weights = ~pop)
feols(y ~ x1 + x2 | state + year, data = df, weights = pop)

# fixest IV with weights
feols(y ~ x1 | state | x_endog ~ z_inst, data = df, weights = ~pop)

# lfe
felm(y ~ x1 | fe | 0 | cluster, data = df, weights = pop)

# Base R GLM
glm(y ~ x1 + x2, data = df, family = binomial, weights = n_trials)

# IV
ivreg(y ~ x1 + x2 | z1 + z2, data = df, weights = pop)

All forms produce call.args['weights'] = 'columnName' in the AnalysisCall.

Math

WLS Normal Equations

Unweighted OLS: beta = (X'X)^-1 X'y Weighted (WLS): beta = (X'WX)^-1 X'Wy where W = diag(w_1, ..., w_n)

The existing wlsStep(X, Xt, w, z, n, p) in glm.ts computes exactly (X'WX)^-1 X'Wz. This function is extracted to a shared module and reused by all WLS paths.

Weighted SS Decomposition

ssRes = sum( w_i * e_i^2 )
ssTot = sum( w_i * (y_i - ybar_w)^2 )    when hasIntercept
ssTot = sum( w_i * y_i^2 )                when no intercept

where ybar_w = sum(w_i * y_i) / sum(w_i) is the weighted mean.

R-squared: 1 - ssRes / ssTot (same form, weighted components). sigma-squared: ssRes / dfResidual (same form, weighted ssRes).

Weighted FE Demeaning (FWL)

Alternating projections with weighted group means:

group_mean_g = sum_{i in g}(w_i * x_i) / sum_{i in g}(w_i)

Replaces the current arithmetic mean (sum / count) in demean(). The computeAbsorbedDf() union-find is purely structural and does not change.

Weighted Sandwich SEs

HC robust: The “bread” (X'WX)^-1 is already the WLS inverse (computed during estimation and passed to the sandwich functions as XtXinv). The meat residual weights change:

• HC0: meat_weight_i = w_i * e_i^2
• HC1: meat_weight_i = w_i * e_i^2 * n/(n-k)
• HC2: meat_weight_i = w_i * e_i^2 / (1 - h_i)
• HC3: meat_weight_i = w_i * e_i^2 / (1 - h_i)^2

Leverage under WLS: h_i = w_i * X_i (X'WX)^-1 X_i'

Clustered: Score vectors incorporate weights:

s_g[j] = sum_{i in g}( w_i * X[i][j] * e[i] )

The small-sample correction formula G/(G-1) * (n-1)/(n-k) remains the same (n = number of observations with w > 0).

Weighted 2SLS

• Stage 1: WLS of each endogenous variable on instruments Z: gamma = (Z'WZ)^-1 Z'Wy_endog
• Stage 2: WLS of y on X_hat (with fitted values from Stage 1): beta = (X_hat'WX_hat)^-1 X_hat'Wy
• SE correction: Uses original X (not X_hat) in sandwich: V = (X_proj'WX_proj)^-1
• Wu-Hausman test: Weighted OLS of augmented regression internally
• Sargan J test: Weighted regression of residuals on instruments

Weighted GLM (Prior Weights)

The IRLS loop already computes per-iteration working weights irls_w[i]. Prior (user-supplied) weights multiply in:

w_total[i] = prior_w[i] * irls_w[i]

Deviance contributions: prior_w[i] * devResid(y[i], mu[i]) Null deviance: uses weighted mean ybar_w = sum(prior_w[i] * y[i]) / sum(prior_w[i])

Weight Validation

• Weights must be non-negative (>= 0). Negative weights produce an error.
• Observations with zero weight are excluded from estimation (filtered out in validRows). This matches R’s lm() behavior — zero-weight rows are effectively dropped.
• Missing (NA/null) weight values are filtered out alongside other missing data in buildDesignMatrix.

Layer-by-Layer Changes

1. Recognizer (parsers/r/recognizer.ts)

Extract weights named argument from all recognized functions:

All produce call.args['weights'] = 'columnName'.

2. Pipeline Types (pipeline/types.ts)

Add to existing param types:

// LinearModelParams — add:
weights?: string;  // column name

// IVModelParams — add:
weights?: string;  // column name

// GLMParams — add:
weights?: string;  // column name

3. Mapper (pipeline/mapper.ts)

Forward call.args['weights'] into node params for linear-model, iv-model, and glm node creation.

4. Executor (pipeline/executor.ts)

Pass params.weights to computeRegression(), compute2SLS(), and computeGLM().

5. Shared WLS Step

Extract wlsStep from glm.ts into matrix.ts (linear algebra routine, no new file). Signature:

export function wlsStep(
  X: number[][], Xt: number[][], w: number[], z: number[], n: number, p: number
): { beta: number[]; XtWXinv: number[][] }

GLM imports it back. OLS and 2SLS call it when weights are present.

6. Design Matrix (stats/regression.ts)

buildDesignMatrix gains optional weightsCol?: string parameter. When provided:

1. Extract weight column from dataset
2. Filter zero-weight and NA-weight rows out of validRows
3. Return weights?: number[] (aligned with validRows) in DesignMatrixResult

export interface DesignMatrixResult {
  X: number[][];
  y: number[];
  columnNames: string[];
  validRows: number[];
  weights?: number[];  // new — present when weightsCol provided
}

7. OLS Computation (stats/regression.ts)

computeRegression gains optional weightsCol?: string.

When weights present: - Call wlsStep(X, Xt, w, y, n, p) instead of solveAndInverse(XtX, Xty) - Compute weighted residuals: e[i] = y[i] - fitted[i] (same formula, but beta differs) - Weighted SS: ssRes = sum(w[i] * e[i]^2), ssTot = sum(w[i] * (y[i] - ybar_w)^2) - Pass weights to computeRobustVcov and computeClusteredVcov - Include weights: colName in result

8. FE Demeaning (stats/demean.ts)

demean gains optional weights?: number[].

When weights present, replace arithmetic group means with weighted group means: - Pre-allocated counts: Float64Array becomes weightSums: Float64Array - Inner loop: sums[g] += w[i] * col[i], weightSums[g] += w[i] - Subtraction: col[i] -= sums[g] / weightSums[g]

Unweighted path (no weights argument) remains unchanged.

9. 2SLS (stats/regression-2sls.ts)

compute2SLS gains optional weightsCol?: string.

When weights present: - Stage 1: wlsStep(Z, Zt, w, y_endog, ...) for each endogenous variable - Stage 2: wlsStep(X_hat, X_hat_t, w, y, ...) - SE correction: (X_proj' W X_proj)^-1 where X_proj uses original X columns - Wu-Hausman: weighted OLS of augmented regression - Sargan J: weighted regression of residuals on instruments

10. GLM (stats/glm.ts)

computeGLM gains optional weightsCol?: string.

When prior weights present: - IRLS working weights: w[i] = prior_w[i] * (dmu^2 / variance) - Null deviance: ybar = sum(prior_w[i] * y[i]) / sum(prior_w[i]) - Deviance: sum(prior_w[i] * devResid(y[i], mu[i])) - AIC adjustment: uses sum of prior weights

11. Sandwich SEs (stats/sandwich.ts)

computeLeverage gains optional weights?: number[]:

h_i = w_i * X_i (X'WX)^-1 X_i'

computeRobustVcov gains optional weights?: number[]: - HC meat weights: w_i * e_i^2 (times HC-type adjustment) - Delegates to updated computeLeverage for HC2/HC3

computeClusteredVcov gains optional weights?: number[]: - Score accumulation: scores[g][j] += w_i * X[i][j] * e[i]

12. Result Types (stats/types.ts)

Add to RegressionResult and GLMResult:

weights?: string;  // column name used, for display

13. Param Schema (pipeline/param-schema.ts)

Already has a weights ParamDef for linear-model. Extend to iv-model and glm node types.

14. UI

No new components needed. The results panel displays the existing coefficient table — we add a “Weights: colname” line to the result metadata section (alongside “Robust SEs: HC1”, “Fixed Effects: state”, etc.). The param-schema weights entry already enables spec explorer grid display.

Testing Strategy

Unit Tests (R-validated)

Tolerances: <0.00005 for statistics, <0.00001 for p-values.

Integration Tests

Parse-to-result pipeline tests with realistic R code:

# Weighted DiD pattern
mod <- feols(earnings ~ treatment | state + year, data = df, weights = ~pop)

# Weighted logit
mod <- glm(enrolled ~ income + age, data = df, family = binomial, weights = n)

Recognizer Tests

Verify weights extraction from all supported function forms (6 patterns).

Files Changed

Out of Scope

• Frequency weights vs analytic weights: R’s weights argument in lm() is analytic (inverse-variance) weights. glm() uses prior weights. We follow R’s semantics per function — no additional weight-type parameter.
• survey package: svyglm(), svydesign() — complex survey weights with design effects. Separate feature.
• Per-observation weight editing in UI: Users can’t modify weights via the property sheet (only the column name). Editing individual weights would require a data editor.