diff --git a/CITATION.cff b/CITATION.cff index 7ac7b92..3acb2b4 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -8,7 +8,7 @@ message: 'To cite package "sps" in publications use:' type: software license: MIT title: 'sps: Sequential Poisson Sampling' -version: 0.6.1 +version: 0.6.2 doi: 10.5281/zenodo.10109857 identifiers: - type: doi @@ -36,7 +36,7 @@ preferred-citation: year: '2025' doi: 10.5281/zenodo.10109857 url: https://cran.r-project.org/package=sps - notes: R package version 0.6.1 + notes: R package version 0.6.2 repository: https://CRAN.R-project.org/package=sps repository-code: https://github.com/marberts/sps url: https://marberts.github.io/sps/ @@ -103,49 +103,22 @@ references: year: '2025' doi: 10.32614/CRAN.package.knitr - type: software - title: rmarkdown - abstract: 'rmarkdown: Dynamic Documents for R' + title: quarto + abstract: 'quarto: R Interface to ''Quarto'' Markdown Publishing System' notes: Suggests - url: https://pkgs.rstudio.com/rmarkdown/ - repository: https://CRAN.R-project.org/package=rmarkdown + url: https://quarto-dev.github.io/quarto-r/ + repository: https://CRAN.R-project.org/package=quarto authors: - family-names: Allaire given-names: JJ email: jj@posit.co - - family-names: Xie - given-names: Yihui - email: xie@yihui.name - orcid: https://orcid.org/0000-0003-0645-5666 + orcid: https://orcid.org/0000-0003-0174-9868 - family-names: Dervieux given-names: Christophe email: cderv@posit.co orcid: https://orcid.org/0000-0003-4474-2498 - - family-names: McPherson - given-names: Jonathan - email: jonathan@posit.co - - family-names: Luraschi - given-names: Javier - - family-names: Ushey - given-names: Kevin - email: kevin@posit.co - - family-names: Atkins - given-names: Aron - email: aron@posit.co - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - - family-names: Cheng - given-names: Joe - email: joe@posit.co - - family-names: Chang - given-names: Winston - email: winston@posit.co - - family-names: Iannone - given-names: Richard - email: rich@posit.co - orcid: https://orcid.org/0000-0003-3925-190X year: '2025' - doi: 10.32614/CRAN.package.rmarkdown + doi: 10.32614/CRAN.package.quarto - type: software title: testthat abstract: 'testthat: Unit Testing for R' diff --git a/DESCRIPTION b/DESCRIPTION index 270c4a9..6bbd74a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: sps Title: Sequential Poisson Sampling -Version: 0.6.1.9007 +Version: 0.6.2 Authors@R: c( person("Steve", "Martin", role = c("aut", "cre", "cph"), @@ -14,7 +14,7 @@ Description: Sequential Poisson sampling is a variation of Poisson sampling for functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998, ISSN:0282-423X), as well as other order sample designs by Rosén (1997, ), and generate - appropriate bootstrap replicate weights according to the generalized + approximate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012, ). Depends: R (>= 4.2) diff --git a/NEWS.md b/NEWS.md index b9299ff..3c69234 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,11 +1,11 @@ -## sps (development version) +## sps 0.6.2 - Added `divisor_method()` to more easily generate divisor functions for `prop_allocation()` by name. - `prop_allocation()` is now faster. -- Added `sps_iterator()` to make an iterator that draws an SPS sample one unit at a time. +- Added `sps_iterator()` to make an iterator that draws a SPS one unit at a time. ## sps 0.6.1 diff --git a/R/sps_iterator.R b/R/sps_iterator.R index 1274a41..83dd95c 100644 --- a/R/sps_iterator.R +++ b/R/sps_iterator.R @@ -4,11 +4,13 @@ #' sequential Poisson method without replacing previously sampled units. #' #' @inheritParams sps -#' @param ... Additional arugments to [`becomes_ta()`]. +#' @param ... Additional arguments to [`becomes_ta()`]. #' @param n A positive integer giving the initial sample size for the iterator. #' #' @returns -#' A function that returns the next unit in the sample. +#' A function that returns the next unit in the sample. It take a single +#' argument giving the sentinel value to indicate that there are no units +#' left to sample (default `NULL`). #' #' @examples #' prn <- runif(5) @@ -43,9 +45,9 @@ sps_iterator <- function(x, ..., n = 0L, prn = NULL) { } else { sampled <- integer(0L) } - function() { + function(done = NULL) { if (length(s) == 0L) { - return(NULL) + return(done) } tas <- bta[[n + 1L]][!bta[[n + 1L]] %in% sampled] if (length(tas) > 0L) { diff --git a/README.Rmd b/README.Rmd index 5f7a16b..48c56a0 100644 --- a/README.Rmd +++ b/README.Rmd @@ -24,7 +24,7 @@ knitr::opts_chunk$set( [![Mentioned in Awesome Official Statistics ](https://awesome.re/mentioned-badge.svg)](https://github.com/SNStatComp/awesome-official-statistics-software) -Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units, and is commonly used for price-index surveys. This package gives functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998), as well as other order sample designs by Rosén (1997), and generate appropriate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012). +Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units, and is commonly used for price-index surveys. This package gives functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998), as well as other order sample designs by Rosén (1997), and generate approximate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012). ## Installation diff --git a/README.md b/README.md index 26b9c22..f7a03da 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ drawing probability-proportional-to-size samples with a given number of units, and is commonly used for price-index surveys. This package gives functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998), as well as other order sample designs by Rosén -(1997), and generate appropriate bootstrap replicate weights according +(1997), and generate approximate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012). ## Installation @@ -64,11 +64,11 @@ revenue <- c(1:10, 100, 150) # Draw a sample of 6 businesses (samp <- sps(revenue, 6)) -#> [1] 4 5 9 10 11 12 +#> [1] 6 7 9 10 11 12 # Design weights and sampling strata are stored with the sample weights(samp) -#> [1] 3.437500 2.750000 1.527778 1.375000 1.000000 1.000000 +#> [1] 2.291667 1.964286 1.527778 1.375000 1.000000 1.000000 levels(samp) #> [1] "TS" "TS" "TS" "TS" "TA" "TA" ``` @@ -88,10 +88,10 @@ stratum <- rep(c("a", "b"), c(9, 3)) # Draw a stratified sample (samp <- sps(revenue, allocation, stratum)) -#> [1] 1 5 7 10 11 12 +#> [1] 4 6 8 10 11 12 weights(samp) -#> [1] 15.000000 3.000000 2.142857 1.000000 1.000000 1.000000 +#> [1] 3.750 2.500 1.875 1.000 1.000 1.000 levels(samp) #> [1] "TS" "TS" "TS" "TA" "TA" "TA" ``` @@ -101,15 +101,15 @@ replicate weights with the `sps_repweights()` function. ``` r sps_repweights(weights(samp), 5) -#> [,1] [,2] [,3] [,4] [,5] -#> [1,] 29.9985000 0.0015000 15.0000 0.0015 15.000000 -#> [2,] 3.0000000 3.0000000 0.0003 3.0000 5.999700 -#> [3,] 0.1430571 0.1430571 2.2857 2.2857 4.428343 -#> [4,] 1.0000000 1.0000000 1.0000 1.0000 1.000000 -#> [5,] 1.0000000 1.0000000 1.0000 1.0000 1.000000 -#> [6,] 1.0000000 1.0000000 1.0000 1.0000 1.000000 +#> [,1] [,2] [,3] [,4] [,5] +#> [1,] 0.0003750 3.515648 3.5156484 7.9683281 3.5156484 +#> [2,] 0.6251875 6.718328 5.3122187 0.6251875 2.0312969 +#> [3,] 1.7578242 1.757824 0.0001875 0.0001875 0.0001875 +#> [4,] 1.0000000 1.000000 1.0000000 1.0000000 1.0000000 +#> [5,] 1.0000000 1.000000 1.0000000 1.0000000 1.0000000 +#> [6,] 1.0000000 1.000000 1.0000000 1.0000000 1.0000000 #> attr(,"tau") -#> [1] 1.0001 +#> [1] 1.066773 ``` The vignette gives more detail about how to use these functions to draw diff --git a/man/sps-package.Rd b/man/sps-package.Rd index 09acfd2..d2cfe62 100644 --- a/man/sps-package.Rd +++ b/man/sps-package.Rd @@ -7,7 +7,7 @@ \description{ \if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} -Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units, and is commonly used for price-index surveys. This package gives functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998, ISSN:0282-423X), as well as other order sample designs by Rosén (1997, \doi{10.1016/S0378-3758(96)00186-3}), and generate appropriate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012, \doi{10.1111/j.1751-5823.2011.00166.x}). +Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units, and is commonly used for price-index surveys. This package gives functions to draw stratified sequential Poisson samples according to the method by Ohlsson (1998, ISSN:0282-423X), as well as other order sample designs by Rosén (1997, \doi{10.1016/S0378-3758(96)00186-3}), and generate approximate bootstrap replicate weights according to the generalized bootstrap method by Beaumont and Patak (2012, \doi{10.1111/j.1751-5823.2011.00166.x}). } \seealso{ Useful links: diff --git a/man/sps_iterator.Rd b/man/sps_iterator.Rd index 1d21d4f..41ed251 100644 --- a/man/sps_iterator.Rd +++ b/man/sps_iterator.Rd @@ -10,7 +10,7 @@ sps_iterator(x, ..., n = 0L, prn = NULL) \item{x}{A positive and finite numeric vector of sizes for units in the population (e.g., revenue for drawing a sample of businesses).} -\item{...}{Additional arugments to \code{\link[=becomes_ta]{becomes_ta()}}.} +\item{...}{Additional arguments to \code{\link[=becomes_ta]{becomes_ta()}}.} \item{n}{A positive integer giving the initial sample size for the iterator.} @@ -20,7 +20,9 @@ permanent random numbers, instead generating a random vector when the function is called.} } \value{ -A function that returns the next unit in the sample. +A function that returns the next unit in the sample. It take a single +argument giving the sentinel value to indicate that there are no units +left to sample (default \code{NULL}). } \description{ Create a function that draws new units, one at a time, according to the diff --git a/vignettes/sps.qmd b/vignettes/sps.qmd index db74d62..7672745 100644 --- a/vignettes/sps.qmd +++ b/vignettes/sps.qmd @@ -172,7 +172,7 @@ The solution to this problem is to simply increase the size of the sample until sample %in% sps(x, 6, prn = u) ``` -It's possible to go one step further and make an interator that draws the next unit in the sample without replacing the old ones, and gives the same result as directly drawing that many units. +It's possible to go one step further and make an iterator that draws the next unit in the sample without replacing the old ones, and gives the same result as directly drawing that many units. ```{r} s <- sps_iterator(x, prn = u) diff --git a/vignettes/take-all.qmd b/vignettes/take-all.qmd index 8df6496..bfac110 100644 --- a/vignettes/take-all.qmd +++ b/vignettes/take-all.qmd @@ -63,7 +63,7 @@ which(pi(x[1:10], 5) >= 1 - alpha) any(pi(x[1:8], 3) >= 1 - alpha) ``` -Although all inclusion probabilities are less than $1 - \alpha$ after two round +Although all inclusion probabilities are less than $1 - \alpha$ after two rounds of placing units into a take-all stratum, the inclusion probability for unit 9 would also be less than $1 - \alpha$ despite it being in the take-all stratum. @@ -147,3 +147,24 @@ abline(1 - alpha, 0, lty = 2) legend(1, 2, c("take-some", "take-all"), pch = c(20, 19)) ``` +As each element $p_{i}$ in the sequence is a strictly increasing function of $i$, we can also identify the unique value for $n$ when a unit enters the take-all stratum. + +```{r, fig.width=8, fig.height=5.33} +#| fig.alt: > +#| Diagram showing when units first enter the take-all stratum. +plot( + 2:5, + p(x, 8)[1:4], + xlab = "", + ylab = "p", + xlim = c(1, 9), + ylim = c(0, 2.5), + pch = 20 +) +points(6:9, p(x, 8)[5:8], pch = 19) +points(1:3, p(x, 9)[1:3], pch = 20, col = "red") +points(4:9, p(x, 9)[4:9], pch = 19, col = "red") +abline(1 - alpha, 0, lty = 2) +legend(1, 2.5, c("take-some", "take-all"), pch = c(20, 19)) +legend(1, 2, c("n = 8", "n = 9"), pch = 20, col = c("black", "red")) +```