From 861833ab56831409fd5e4e9b467159246105fdab Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Thu, 21 Aug 2025 22:12:59 -0400 Subject: [PATCH 1/4] Ready for release --- CITATION.cff | 43 ++++++++----------------------------------- DESCRIPTION | 2 +- NEWS.md | 2 +- R/sps_iterator.R | 2 +- man/sps_iterator.Rd | 2 +- vignettes/sps.qmd | 2 +- 6 files changed, 13 insertions(+), 40 deletions(-) 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..4929d67 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"), diff --git a/NEWS.md b/NEWS.md index b9299ff..899e839 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -## sps (development version) +## sps 0.6.2 - Added `divisor_method()` to more easily generate divisor functions for `prop_allocation()` by name. diff --git a/R/sps_iterator.R b/R/sps_iterator.R index 1274a41..7723872 100644 --- a/R/sps_iterator.R +++ b/R/sps_iterator.R @@ -4,7 +4,7 @@ #' 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 diff --git a/man/sps_iterator.Rd b/man/sps_iterator.Rd index 1d21d4f..a4ff349 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.} 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) From ea0a1444987fd166529542914d1c11f1a1f73779 Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Fri, 22 Aug 2025 22:43:13 -0400 Subject: [PATCH 2/4] Added sentinel value for sps_ierator() --- R/sps_iterator.R | 8 +++++--- man/sps_iterator.Rd | 4 +++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/R/sps_iterator.R b/R/sps_iterator.R index 7723872..83dd95c 100644 --- a/R/sps_iterator.R +++ b/R/sps_iterator.R @@ -8,7 +8,9 @@ #' @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/man/sps_iterator.Rd b/man/sps_iterator.Rd index a4ff349..41ed251 100644 --- a/man/sps_iterator.Rd +++ b/man/sps_iterator.Rd @@ -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 From 64296af3ca6e56098a428c29ef3f3453f36152c7 Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Sat, 23 Aug 2025 23:30:33 -0400 Subject: [PATCH 3/4] Version 0.6.2 --- DESCRIPTION | 2 +- NEWS.md | 2 +- README.Rmd | 2 +- README.md | 26 +++++++++++++------------- man/sps-package.Rd | 2 +- vignettes/take-all.qmd | 23 ++++++++++++++++++++++- 6 files changed, 39 insertions(+), 18 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4929d67..6bbd74a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -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 899e839..3c69234 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,7 +5,7 @@ - `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/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/vignettes/take-all.qmd b/vignettes/take-all.qmd index 8df6496..140ee1c 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")) +``` \ No newline at end of file From c7bc33e08d6b96d3c03979082f39ee30c2421a37 Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Sun, 24 Aug 2025 00:00:38 -0400 Subject: [PATCH 4/4] Fix lint --- vignettes/take-all.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/take-all.qmd b/vignettes/take-all.qmd index 140ee1c..bfac110 100644 --- a/vignettes/take-all.qmd +++ b/vignettes/take-all.qmd @@ -167,4 +167,4 @@ 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")) -``` \ No newline at end of file +```