Skip to content

Fix silent estimation errors; add design-matched variance, domains an… - #1

Merged
elkronos merged 3 commits into
mainfrom
claude/brave-hopper-9r1zll
Sep 28, 2026
Merged

elkronos merged 3 commits into
mainfrom
claude/brave-hopper-9r1zll

Conversation

@elkronos

Copy link
Copy Markdown
Owner

…d spatially balanced sampling

Wrong answers fixed (each verified by simulation before and after):

  • One sampled row per stratum or interval reported a variance of exactly 0 and a zero-width interval. The analytic estimator now declines with a reason, as survey does by default.
  • A stratum allocated no rows made its frame rows unreachable and biased a total by their whole contribution (84% in one example) without a word. draw() now warns, naming the strata.
  • The jackknife deleted rows across strata, counting between-stratum gaps as sampling variance (64x overstated). It is now the stratified JKn and matches the analytic form exactly for stratified and temporal designs.
  • One row per cluster understated the multistage variance by ~30%; it now falls back to the ultimate-cluster jackknife.
  • Neyman allocation dealt over-allocation surplus round-robin; capped strata are now taken whole and the rest re-split by the rule (Cochran 5.9).
  • ht_mean(estimator = "ht") printed as a Hajek mean.
  • design_systematic(order_by) returned rows in sorted rather than frame order, contrary to the documented contract.

Research-based methods:

  • Confidence intervals use t on the design's degrees of freedom (PSUs minus strata), matching survey::degf(); coverage at four clusters rises from ~87% to nominal. df = Inf restores the normal interval.
  • Systematic PPS uses Deville's (1999) variance approximation, identical to sampling::varest() and within 0.2% of survey's Brewer option.
  • Systematic samples get the successive-difference approximation (Wolter) instead of no variance at all, with its limits stated.
  • ht_total()/ht_mean() gain by for domain estimates from the full sample; standard errors match survey::svyby() exactly.
  • design_spread(): spatially or covariate-balanced sampling by the local pivotal method (Grafstrom, Lundstrom and Schelin 2012) with exact first-order probabilities and a local-mean variance estimator.
  • plot(type = "map") shows how evenly a sample covers two dimensions.

survey handoff:

  • Multistage designs are stated as two stages, so survey's standard error now agrees exactly rather than differing by 5-10%.
  • A capped reservoir uses the rows the stream reached as its population.
  • Systematic PPS and certainty-over-PPS map to pps = "brewer".

Housekeeping: graphics and utils declared in Imports; variance.R split so joint probabilities live in joint.R; multistage error messages no longer embed source-line breaks or repeat the simulate hint.

…d spatially balanced sampling

Wrong answers fixed (each verified by simulation before and after):
* One sampled row per stratum or interval reported a variance of exactly 0
  and a zero-width interval. The analytic estimator now declines with a
  reason, as survey does by default.
* A stratum allocated no rows made its frame rows unreachable and biased a
  total by their whole contribution (84% in one example) without a word.
  draw() now warns, naming the strata.
* The jackknife deleted rows across strata, counting between-stratum gaps
  as sampling variance (64x overstated). It is now the stratified JKn and
  matches the analytic form exactly for stratified and temporal designs.
* One row per cluster understated the multistage variance by ~30%; it now
  falls back to the ultimate-cluster jackknife.
* Neyman allocation dealt over-allocation surplus round-robin; capped strata
  are now taken whole and the rest re-split by the rule (Cochran 5.9).
* ht_mean(estimator = "ht") printed as a Hajek mean.
* design_systematic(order_by) returned rows in sorted rather than frame
  order, contrary to the documented contract.

Research-based methods:
* Confidence intervals use t on the design's degrees of freedom (PSUs minus
  strata), matching survey::degf(); coverage at four clusters rises from
  ~87% to nominal. df = Inf restores the normal interval.
* Systematic PPS uses Deville's (1999) variance approximation, identical to
  sampling::varest() and within 0.2% of survey's Brewer option.
* Systematic samples get the successive-difference approximation (Wolter)
  instead of no variance at all, with its limits stated.
* ht_total()/ht_mean() gain `by` for domain estimates from the full sample;
  standard errors match survey::svyby() exactly.
* design_spread(): spatially or covariate-balanced sampling by the local
  pivotal method (Grafstrom, Lundstrom and Schelin 2012) with exact
  first-order probabilities and a local-mean variance estimator.
* plot(type = "map") shows how evenly a sample covers two dimensions.

survey handoff:
* Multistage designs are stated as two stages, so survey's standard error
  now agrees exactly rather than differing by 5-10%.
* A capped reservoir uses the rows the stream reached as its population.
* Systematic PPS and certainty-over-PPS map to pps = "brewer".

Housekeeping: graphics and utils declared in Imports; variance.R split so
joint probabilities live in joint.R; multistage error messages no longer
embed source-line breaks or repeat the simulate hint.
…e methods

Behaviour:
* A 0/1 or logical y gets its interval on the logit scale, so a small
  proportion's interval no longer runs below zero. Matches
  survey::svyciprop(method = "xlogit") exactly.
* deff() methods are registered for survey's generic, so attaching survey
  after drawn no longer breaks deff() with "non-numeric argument".
* An empty sample (Poisson, or a systematic start past the end) is refused
  with a reason instead of failing inside the interval code.
* A nested design prints as a readable call rather than its raw fields.
* Lonely-stratum and successive-sampling messages reworded; notes print
  after one blank line instead of two; plan_size() rounds deff.

Documentation corrected:
* min_per_stratum: a floor does not bias a design-weighted estimate; an
  empty stratum does. Stated both ways round previously.
* design_weighted(method = "systematic"): every pair can co-occur because
  the frame is shuffled first; the UPsystematicpi2() pointer answered a
  different design and is removed.
* as_svydesign(): the mapping table now reflects two-stage multistage,
  Brewer PPS, the reservoir cap, spread designs, and lonely strata.
* design_spatial() is described as what it is, a simple random sample
  within a region, and points to design_spread() for even coverage.
* @references added for Horvitz-Thompson, Sen-Yates-Grundy, Hajek,
  Deville, Matei-Tille, Hartley-Rao, Madow, Neyman, Cochran, Kish, Wolter,
  Korn-Graubard, Grafstrom et al., Stevens-Olsen, Vitter, Li, Efron and
  Kunsch.
* README is now generated from README.Rmd, so every printed result is real.
  It leads with what the package offers beyond sampling, survey, spsurvey
  and BalancedSampling, and shows the plan-draw-check-estimate workflow.
* New vignette "Get started": one retail audit from sizing to hand-off,
  showing why stratifying on size beats stratifying on region.
* New articles (pkgdown only): how every variance estimator works, with
  formulas, references and a simulation check of variance and coverage run
  at build time; an audit walkthrough that reports honestly where the
  upper bound falls short for rare misstatements; and a spatially balanced
  field survey comparing spread, simple random and region-restricted
  designs.
* choosing-a-design corrected on floors, systematic PPS and intervals, and
  extended with domain estimates and spreading on a size measure.
* _pkgdown.yml: navbar with Get started, Guides and Walkthroughs; reference
  regrouped, with a Space and time section; MathJax enabled.
* NEWS for 0.2.0 and cran-comments updated to match.
@elkronos
elkronos merged commit a0b9945 into main Sep 28, 2026
5 checks passed
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.

1 participant