Skip to content

Estimate variance from replicate weights - #320

Merged
juaristi22 merged 7 commits into
mainfrom
replicate-weight-variance
Sep 17, 2026
Merged

juaristi22 merged 7 commits into
mainfrom
replicate-weight-variance

Conversation

@vahid-ahmadi

@vahid-ahmadi vahid-ahmadi commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Adds variance and standard error estimation from replicate weights for scalar statistics, including weighted means, counts, Gini coefficients and quantiles. The API recomputes the statistic with each replicate's weights and preserves the source values' dtype, index and name, including categorical, Boolean, nullable and exact large-integer data.

replicate_variance, replicate_standard_error and MicroSeries.replicate_standard_error accept the keyword-only centering argument. "full-sample" remains the default and uses the full-sample estimate; "replicate-mean" uses the mean of the replicate estimates. Both choices retain the same method factors, where R counts replicate columns:

Method Factor
Unstratified JK1 / common-factor delete-group jackknife (R - 1) / R
Balanced repeated replication (BRR) 1 / R
Fay's BRR 1 / (R * (1 - fay_k)**2)
Bootstrap 1 / R
Successive-difference replication 4 / R

The survey's replication design determines the appropriate factor and centering convention. Statistical validity also depends on the statistic: nonsmooth quantiles can require an appropriate replication method or smoothing of replicate estimates. This API applies the supplied statistic directly and supports common-factor schemes; arbitrary stratified jackknife and averaged-bootstrap schemes that require additional or replicate-specific factors remain outside its scope. Replicate-weight rows must follow the source series' row order; DataFrame index labels do not realign them.

Changing main weights without corresponding design-consistent adjustments to replicate weights invalidates the original replicates. Calibration can remain valid when the required calibration is repeated appropriately for every replicate.

Reference-relative centering and scaled accumulation preserve representable variances at extreme magnitudes without depending on platform-specific extended precision. BRR replicates alternating between 0 and 2e154 now return variance 1e308 and standard error 1e154; identical replicate estimates of 1e308 return zero. Replicate-mean centering retains a variance of 1 for estimates alternating between 2**53 and 2**53 + 2. Full-sample centering continues to use the callback's returned estimate, and nonfinite callback results retain their existing propagation.

Regression tests cover dtype preservation, metadata and input integrity, both centering conventions through all public entry points, each method's factor, default compatibility, invalid centering and positional weight rows. Exact nonlinear examples distinguish the two centers without relying on stochastic agreement. The 118 added numerical cases cover finite extreme results, small common-offset differences, representable subnormal variances, Fay amplification of tiny deviations, true overflow and nonfinite behavior.

The full-sample callback receives an independent copy of the source. A statistic that normalizes values or changes weights in place cannot contaminate subsequent replicate inputs or the caller's data, including when it raises an exception. The reported in-place normalization case now returns variance 3,600 and standard error 60, matching the functional callback.

Validation: 566 full-suite tests passed on each of pandas 2.3.1 and 3.0.5, including 24 callback-isolation regressions. Independent verification passed 63 diagnostics per environment across all three entry points and both centering modes, including mutation and exception cases.

Combined with #321 and #323, 817 full-suite tests, 35 repair acceptance cases and 180 exact-arithmetic interaction cases pass on each pandas version. Formatting, lint and changelog drafts pass.

Closes #319.

vahid-ahmadi added a commit that referenced this pull request Sep 16, 2026
The package now estimates standard errors from replicate weights (#320), so
the comparison table and the scope paragraph say what it does and does not
do: replicate weights yes, variance from a design specification no.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@vahid-ahmadi vahid-ahmadi mentioned this pull request Sep 16, 2026
30 of 31 tasks
@vahid-ahmadi

Copy link
Copy Markdown
Contributor Author

Paper side updated in #315: the State of the Field table now reads "Replicate weights" rather than "No" under design-based variance, and the scope paragraph says what this does and does not do — replicate weights yes, variance from a stratum/PSU design specification no, and not valid on calibrated weights.

Worth merging this before the paper, so the table describes what ships.

@vahid-ahmadi

Copy link
Copy Markdown
Contributor Author

Lint is clean on the files this PR adds. The remaining failures in that job are pre-existing on main — 141 errors there before this branch, which is #305 / #307.

vahid-ahmadi and others added 5 commits September 16, 2026 14:44
Recomputing a statistic once per replicate weight vector and scaling the
spread by the factor for the replication scheme gives a variance estimate
that needs no analytic formula. That makes it work for every estimator here,
including the Gini coefficient and quantiles, where the analytic variance is
awkward enough that users leave for R.

Supports jackknife, BRR, Fay's BRR, bootstrap and the successive-difference
scheme used for the ACS and CPS.

Valid only for replicate weights as published with a survey: weights
calibrated to external targets no longer correspond to the original
replication scheme, and the docstrings say so.

Closes #319

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@juaristi22
juaristi22 merged commit f95eb1b into main Sep 17, 2026
8 checks passed
vahid-ahmadi added a commit that referenced this pull request Sep 18, 2026
The landing page said function documentation would arrive 'in the
future', which #324 has since added, so the first page of the docs told
a reader the API reference does not exist. It now describes what the
package does, installs it, and links to both pages.

examples.md opened with 'See these rendered Jupyter notebooks' followed
by no links. It now links the one notebook there is.

The roadmap claimed graphs and Tax-Calculator helpers, neither of which
is in the package - grep finds no taxcalc reference and no plotting
code - and listed replicate-weight standard errors as future work, which
shipped in #320 and is the paper's headline feature. Replaced with what
the package does and three things it does not do yet.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add replicate-weight variance estimation

2 participants