Litedown

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: sps
 Title: Sequential Poisson Sampling
-Version: 0.6.3.9003
+Version: 0.6.3.9004
 Authors@R: c(
     person("Steve", "Martin",
             role = c("aut", "cre", "cph"),
@@ -22,7 +22,6 @@ Imports: stats
 Suggests: 
     kit (>= 0.0.10),
     litedown,
-    rbibutils,
     tinytest
 License: MIT + file LICENSE
 Encoding: UTF-8

R/sps.R

@@ -90,9 +90,10 @@ stratify <- function(f) {
 #' For each stratum, the sequential Poisson procedure starts by stratifying
 #' units in the population based on their (target) inclusion probabilities
 #' \eqn{\pi}. Units with \eqn{\pi = 0} are placed into a take-none stratum,
-#' units with \eqn{0 < \pi < 1} are placed into a take-some stratum, and units
-#' with \eqn{\pi = 1} are placed into a take-all stratum. As noted by
-#' Ohlsson (1998), it can be useful to set \eqn{\alpha} to a small positive
+#' units with \eqn{0 < \pi < 1 - \alpha} are placed into a take-some stratum,
+#' and units
+#' with \eqn{\pi \geq 1 - \alpha} are placed into a take-all stratum. As noted
+#' by Ohlsson (1998), it can be useful to set \eqn{\alpha} to a small positive
 #' value when calculating inclusion probabilities, and this is the default
 #' behavior.
 #'
@@ -208,15 +209,18 @@ stratify <- function(f) {
 #' Matei, A., and Tillé, Y. (2007). Computational aspects of order
 #' \eqn{\pi}ps sampling schemes. *Computational Statistics & Data Analysis*,
 #' 51: 3703-3717.
+#' https://doi.org/10.1016/j.csda.2006.12.026.
 #'
 #' Ohlsson, E. (1998). Sequential Poisson Sampling.
 #' *Journal of Official Statistics*, 14(2): 149-162.
 #'
 #' Rosén, B. (1997). On sampling with probability proportional to size.
 #' *Journal of Statistical Planning and Inference*, 62(2): 159-191.
+#' https://doi.org/10.1016/S0378-3758(96)00186-3.
 #'
 #' Rosén, B. (2000). On inclusion probabilities for order \eqn{\pi}ps sampling.
 #' *Journal of Statistical Planning and Inference*, 90(1): 117-143.
+#' https://doi.org/10.1016/S0378-3758(00)00104-X.
 #'
 #' @examples
 #' # Make a population with units of different size

R/sps_iterator.R

@@ -13,7 +13,7 @@
 #'   get an inclusion probability of 1. The default does not apply a cutoff.
 #'
 #' @returns
-#' A function that returns the next unit in the sample. It take a single
+#' A function that returns the next unit in the sample. It takes a single
 #' argument giving the sentinel value to indicate that there are no units
 #' left to sample (default `NULL`).
 #'

R/sps_repweights.R

@@ -73,12 +73,14 @@
 #' Beaumont, J.-F. and Patak, Z. (2012). On the Generalized
 #' Bootstrap for Sample Surveys with Special Attention to Poisson Sampling.
 #' *International Statistical Review*, 80(1): 127-148.
+#' https://doi.org/10.1111/j.1751-5823.2011.00166.x.
 #'
 #' Ohlsson, E. (1998). Sequential Poisson Sampling.
 #' *Journal of Official Statistics*, 14(2): 149-162.
 #'
 #' Rosén, B. (1997). On sampling with probability proportional to size.
 #' *Journal of Statistical Planning and Inference*, 62(2): 159-191.
+#' https://doi.org/10.1016/S0378-3758(96)00186-3.
 #'
 #' @examples
 #' # Make a population with units of different size

README.Rmd

@@ -102,8 +102,8 @@ All contributions are welcome. Please start by opening an issue on GitHub to rep
 
 ## References
 
-Beaumont, J.-F. and Patak, Z. (2012). On the Generalized Bootstrap for Sample Surveys with Special Attention to Poisson Sampling. *International Statistical Review*, 80(1): 127-148.
+Beaumont, J.-F. and Patak, Z. (2012). On the Generalized Bootstrap for Sample Surveys with Special Attention to Poisson Sampling. *International Statistical Review*, 80(1): 127-148. https://doi.org/10.1111/j.1751-5823.2011.00166.x.
 
 Ohlsson, E. (1998). Sequential Poisson Sampling. *Journal of Official Statistics*, 14(2): 149-162.
 
-Rosén, B. (1997). On sampling with probability proportional to size. *Journal of Statistical Planning and Inference*, 62(2): 159-191.
+Rosén, B. (1997). On sampling with probability proportional to size. *Journal of Statistical Planning and Inference*, 62(2): 159-191. https://doi.org/10.1016/S0378-3758(96)00186-3.

README.md

@@ -64,11 +64,11 @@ revenue <- c(1:10, 100, 150)
 
 # Draw a sample of 6 businesses
 (samp <- sps(revenue, 6))
-#> [1]  6  7  9 10 11 12
+#> [1]  4  5  6  8 11 12
 
 # Design weights and sampling strata are stored with the sample
 weights(samp)
-#> [1] 2.291667 1.964286 1.527778 1.375000 1.000000 1.000000
+#> [1] 3.437500 2.750000 2.291667 1.718750 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]  4  6  8 10 11 12
+#> [1]  6  7  8 10 11 12
 
 weights(samp)
-#> [1] 3.750 2.500 1.875 1.000 1.000 1.000
+#> [1] 2.500000 2.142857 1.875000 1.000000 1.000000 1.000000
 levels(samp)
 #> [1] "TS" "TS" "TS" "TA" "TA" "TA"
 ```
@@ -101,13 +101,13 @@ replicate weights with the `sps_repweights()` function.
 
 ``` r
 sps_repweights(weights(samp), 5)
-#>           [,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
+#>           [,1]      [,2]     [,3]     [,4]      [,5]
+#> [1,] 0.6251875 0.6251875 2.031297 5.312219 0.6251875
+#> [2,] 4.2855000 0.2680446 2.276772 2.276772 0.2680446
+#> [3,] 0.0001875 0.0001875 1.757824 3.515461 3.5154609
+#> [4,] 1.0000000 1.0000000 1.000000 1.000000 1.0000000
+#> [5,] 1.0000000 1.0000000 1.000000 1.000000 1.0000000
+#> [6,] 1.0000000 1.0000000 1.000000 1.000000 1.0000000
 #> attr(,"tau")
 #> [1] 1.066773
 ```
@@ -137,9 +137,11 @@ the contribution guidelines for this project for more information.
 Beaumont, J.-F. and Patak, Z. (2012). On the Generalized Bootstrap for
 Sample Surveys with Special Attention to Poisson Sampling.
 *International Statistical Review*, 80(1): 127-148.
+<https://doi.org/10.1111/j.1751-5823.2011.00166.x>.
 
 Ohlsson, E. (1998). Sequential Poisson Sampling. *Journal of Official
 Statistics*, 14(2): 149-162.
 
 Rosén, B. (1997). On sampling with probability proportional to size.
 *Journal of Statistical Planning and Inference*, 62(2): 159-191.
+<https://doi.org/10.1016/S0378-3758(96)00186-3>.

vignettes/sps.Rmd

@@ -1,13 +1,12 @@
 ---
 title: "Drawing a Sequential Poisson Sample"
-bibliography: ref.bib
 vignette: >
   %\VignetteIndexEntry{Drawing a Sequential Poisson Sample}
   %\VignetteEngine{litedown::vignette}
   %\VignetteEncoding{UTF-8}
 ---
 
-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.
+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. Tillé (2020, 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
 
@@ -208,7 +207,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 [@tille2023].
+is usually close to what is expected if sequential Poisson sampling was exactly proportional to size (Tillé, 2023).
 
 ```{r tille, fig.width=8, fig.height=5.33}
 #| fig.alt: >
@@ -238,3 +237,9 @@ plot(
 lines(seq(-4, 4, 0.1), dnorm(seq(-4, 4, 0.1)), lty = "dashed")
 legend("topright", c("empirical", "theoretical"), lty = c("solid", "dashed"))
 ```
+
+## References {-}
+
+Tillé, Y. (2020). _Sampling and Estimation from Finite Populations_. Wiley. https://doi.org/10.1002/9781119071259.
+
+Tillé, Y. (2023). Remarks on some misconceptions about unequal probability sampling without replacement. _Computer Science Review_, 47: 100533. https://doi.org/10.1016/j.cosrev.2022.100533.

vignettes/take-all.Rmd

@@ -3,7 +3,6 @@ title: "Take-all units"
 format: 
   html:
     html-math-method: mathjax
-bibliography: ref.bib
 vignette: >
   %\VignetteIndexEntry{Take-all units}
   %\VignetteEngine{litedown::vignette}
@@ -24,20 +23,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; see, e.g., @ohlsson1998
-or @tille2020 (Chapter 5). The
+remaining units (the take-some units) drawn at random. 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.[^1]
+until all inclusion probabilities are less than 1.[^1] See, e.g., Ohlsson (1998)
+or Tillé (2020, Chapter 5).
 
 [^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.
 
 Sequential poisson sampling is a bit more complicated because, as noted by
-@ohlsson1998, it can be useful
+Ohlsson (1998), 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
@@ -54,8 +53,8 @@ x <- c(1:8, 9.5, 10, 20, 20, 30)
 
 alpha <- 0.15
 
-# Units 11, 12, and 13 have an inclusion probability
-# greater than 1 - alpha.
+# With a sample size of 8, units 11, 12, and 13
+# have an inclusion probability greater than 1 - alpha.
 which(pi(x, 8) >= 1 - alpha)
 
 # Now units 9 and 10 have an inclusion probability
@@ -174,7 +173,7 @@ 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.
+And this can be calculated for each unit in the population.
 
 ```{r}
 sps::becomes_ta(x, alpha = alpha)
@@ -183,3 +182,9 @@ 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.
+
+## References {-}
+
+Ohlsson, E. (1998). Sequential Poisson sampling. _Journal of Official Statistics_, 14(2): 149--162.
+
+Tillé, Y. (2020). _Sampling and Estimation from Finite Populations_. Wiley. https://doi.org/10.1002/9781119071259.