diff --git a/DESCRIPTION b/DESCRIPTION index e39e30e..c156402 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: sps Title: Sequential Poisson Sampling -Version: 0.6.3.9001 +Version: 0.6.3.9003 Authors@R: c( person("Steve", "Martin", role = c("aut", "cre", "cph"), @@ -21,13 +21,13 @@ Depends: R (>= 4.2) Imports: stats Suggests: kit (>= 0.0.10), - knitr, - quarto, + litedown, + rbibutils, tinytest License: MIT + file LICENSE Encoding: UTF-8 URL: https://marberts.github.io/sps/, https://github.com/marberts/sps BugReports: https://github.com/marberts/sps/issues -VignetteBuilder: quarto +VignetteBuilder: litedown Roxygen: list(markdown = TRUE) Config/roxygen2/version: 8.0.0 diff --git a/NEWS.md b/NEWS.md index e097823..c826f71 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ - Small improvements to the documentation. -- Now using `{tinytest}`. +- Now using `{tinytest}` and `{litedown}`. ## sps 0.6.3 diff --git a/inst/CITATION b/inst/CITATION index 463ceda..6f44c32 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -1,3 +1,5 @@ +citHeader("To cite sps in publications use:") + bibentry( bibtype = "Manual", title = "{sps}: Sequential Poisson Sampling", diff --git a/vignettes/ref.bib b/vignettes/ref.bib new file mode 100644 index 0000000..f6cb1d7 --- /dev/null +++ b/vignettes/ref.bib @@ -0,0 +1,27 @@ +@article{ohlsson1998, + title = {Sequential {P}oisson sampling}, + author = {Ohlsson, E.}, + year = {1998}, + journal = {Journal of Official Statistics}, + number = {2}, + volume = {14}, + pages = {149--162} +} + +@book{tille2020, + title = {Sampling and Estimation from Finite Populations}, + author = {Tillé, Y}, + year = {2020}, + publisher = {Wiley}, + doi = {10.1002/9781119071259} +} + +@article{tille2023, + title = {Remarks on some misconceptions about unequal probability sampling without replacement}, + author = {Tillé, Y}, + year = {2023}, + journal = {Computer Science Review}, + volume = {47}, + pages = {100533}, + doi = {10.1016/j.cosrev.2022.100533} +} diff --git a/vignettes/sps.qmd b/vignettes/sps.Rmd similarity index 96% rename from vignettes/sps.qmd rename to vignettes/sps.Rmd index ba698a8..f209fec 100644 --- a/vignettes/sps.qmd +++ b/vignettes/sps.Rmd @@ -1,16 +1,13 @@ --- title: "Drawing a Sequential Poisson Sample" +bibliography: ref.bib vignette: > %\VignetteIndexEntry{Drawing a Sequential Poisson Sample} - %\VignetteEngine{quarto::html} + %\VignetteEngine{litedown::vignette} %\VignetteEncoding{UTF-8} -knitr: - opts_chunk: - collapse: true - comment: '#>' --- -Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units. It's a fast, simple, and flexible method for sampling units proportional to their size, and is often used for drawing a sample of businesses. The purpose of this vignette is to give an example of how the functions in this package can be used to easily draw a sample using the sequential Poisson method. More details can be found on the help pages for the functions used in this vignette. +Sequential Poisson sampling is a variation of Poisson sampling for drawing probability-proportional-to-size samples with a given number of units. It's a fast, simple, and flexible method for sampling units proportional to their size, and is often used for drawing a sample of businesses. The purpose of this vignette is to give an example of how the functions in this package can be used to easily draw a sample using the sequential Poisson method. More details, including references to the literature, can be found on the help pages for the functions used in this vignette. @tille2020 (Chapter 5) gives a textbook treatment of this method and how it compares with other probability-proportional-to-size sampling methods. ## Drawing a sample of businesses @@ -211,7 +208,7 @@ summary(sampling_distribution / sum(sales) - 1) ``` More generally, the distribution of inclusion probabilities -is usually close to what is expected if sequential Poisson sampling was exactly proportional to size.^[See Tillé, Y. (2023). Remarks on some misconceptions about unequal probability sampling without replacement. *Computer Science Review*, 47, 100533.] +is usually close to what is expected if sequential Poisson sampling was exactly proportional to size [@tille2023]. ```{r tille, fig.width=8, fig.height=5.33} #| fig.alt: > @@ -241,4 +238,3 @@ plot( lines(seq(-4, 4, 0.1), dnorm(seq(-4, 4, 0.1)), lty = "dashed") legend("topright", c("empirical", "theoretical"), lty = c("solid", "dashed")) ``` - diff --git a/vignettes/take-all.qmd b/vignettes/take-all.Rmd similarity index 89% rename from vignettes/take-all.qmd rename to vignettes/take-all.Rmd index a6b1273..79526df 100644 --- a/vignettes/take-all.qmd +++ b/vignettes/take-all.Rmd @@ -3,14 +3,11 @@ title: "Take-all units" format: html: html-math-method: mathjax +bibliography: ref.bib vignette: > %\VignetteIndexEntry{Take-all units} - %\VignetteEngine{quarto::html} + %\VignetteEngine{litedown::vignette} %\VignetteEncoding{UTF-8} -knitr: - opts_chunk: - collapse: true - comment: '#>' --- When drawing a sample of size $n$ from a population of size $N$, @@ -27,16 +24,20 @@ probability greater than 1, especially when $n$ is large. The usual procedure to deal with these units is to put them in a special take-all stratum so that they are always included in the sample, essentially fixing their inclusion probabilities at 1, with the -remaining units (the take-some units) drawn at random. The +remaining units (the take-some units) drawn at random; see, e.g., @ohlsson1998 +or @tille2020 (Chapter 5). The usual algorithm used by, say, `sampling::inclusionprobabilities()` repeatedly moves units into the take-all stratum and recalculates the inclusion probabilities for the remaining units -until all inclusion probabilities are less than 1.^[To see why this needs +until all inclusion probabilities are less than 1.[^1] + +[^1]: To see why this needs to be done repeatedly, consider a population with three units with sizes 1, 2, and 3 and find which units have an inclusion probability greater than 1 when the sample -size is 3.] +size is 3. -Sequential poisson sampling is a bit more complicated because it can be useful +Sequential poisson sampling is a bit more complicated because, as noted by +@ohlsson1998, it can be useful to place units with an inclusion probability greater than $1 - \alpha$, for some small $\alpha$, into the take-all stratum. Unless $\alpha = 0$, the usual algorithm for finding take-all units can put units into the take-all stratum that have @@ -172,3 +173,13 @@ 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")) symbols(4.5, 0.85, circles = 1, inches = FALSE, add = TRUE, lty = 2) ``` + +This can be calculated for each unit in the population. + +```{r} +sps::becomes_ta(x, alpha = alpha) +``` + +Knowing when a unit enters the take-all stratum also makes it possible to draw +units one at a time with the sequential Poisson method, as with the `sps_iterator()` +function.