Version 0.5.3

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: sps
 Title: Sequential Poisson Sampling
-Version: 0.5.2.9001
+Version: 0.5.3
 Authors@R: c(
     person("Steve", "Martin", role = c("aut", "cre", "cph"), email = "stevemartin041@gmail.com", comment = c(ORCID = "0000-0003-2544-9480")),
     person("Justin", "Francis", role = "ctb")

NEWS.md

@@ -1,3 +1,7 @@
+## Changes in version 0.5.3
+
+- Documentation only; no changes to any functions.
+
 ## Changes in version 0.5.2
 
 - Added a vignette.

R/expected_coverage.R

@@ -1,21 +1,23 @@
 #' Expected coverage
-#' 
+#'
 #' @description
-#' Find the average number of strata covered by ordinary Poisson sampling
+#' Find the expected number of strata covered by ordinary Poisson sampling
 #' without stratification. As sequential and ordinary Poisson sampling have the
 #' same sample size on average, this gives an approximation for the coverage
 #' under sequential Poisson sampling.
-#' 
-#' This function can also be used to
-#' calculate, e.g., the expected number of enterprises covered within a stratum
-#' when sampling business establishments.
-#' 
+#'
+#' This function can also be used to calculate, e.g., the expected number of
+#' enterprises covered within a stratum when sampling business establishments.
+#'
 #' @inheritParams sps
 #' @param n A positive integer giving the sample size.
-#' 
+#'
 #' @returns
 #' The expected number of strata covered by the sample design.
-#' 
+#'
+#' @seealso
+#' [prop_allocation()] for generating proportional-to-size allocations.
+#'
 #' @examples
 #' # Make a population with units of different size
 #' x <- c(rep(1:9, each = 3), 100, 100, 100)
@@ -25,7 +27,7 @@
 #'
 #' # Should get about 7 to 8 strata in a sample on average
 #' expected_coverage(x, 15, s)
-#' 
+#'
 #' @export
 expected_coverage <- function(x, n, strata, alpha = 1e-3, cutoff = Inf) {
   x <- as.numeric(x)

R/inclusion_prob.R

@@ -11,7 +11,7 @@ as_stratum <- function(strata) {
   strata
 }
 
-#' Calculate unconstrained inclusion probabilities 
+#' Calculate unconstrained inclusion probabilities
 #' @noRd
 unbounded_pi <- function(x, n) {
   # n == 0 should be a strong zero
@@ -109,3 +109,46 @@ inclusion_prob_ <- function(x, n, strata, alpha, cutoff) {
   }
   Map(pi, split(x, strata), n, alpha, cutoff)
 }
+
+#' Calculate inclusion probabilities
+#'
+#' Calculate stratified (first-order) inclusion probabilities.
+#'
+#' Within a stratum, the inclusion probability for a unit is given by
+#' \eqn{\pi = nx / \sum x}{\pi = n * x / \sum x}. These values can be greater
+#' than 1 in practice, and so they are constructed iteratively by taking units
+#' with \eqn{\pi \geq 1 - \alpha}{\pi >= 1 - \alpha} (from largest to smallest)
+#' and assigning these units an inclusion probability of 1, with the remaining
+#' inclusion probabilities recalculated at each step. If \eqn{\alpha > 0}, then
+#' any ties among units with the same size are broken by their position.
+#'
+#' @inheritParams sps
+#'
+#' @returns
+#' A numeric vector of inclusion probabilities for each unit in the population.
+#'
+#' @seealso
+#' [sps()] for drawing a sequential Poisson sample.
+#'
+#' @examples
+#' # Make a population with units of different size
+#' x <- c(1:10, 100)
+#'
+#' # Use the inclusion probabilities to calculate the variance of the
+#' # sample size for Poisson sampling
+#' pi <- inclusion_prob(x, 5)
+#' sum(pi * (1 - pi))
+#'
+#' @export
+inclusion_prob <- function(x,
+                           n,
+                           strata = gl(1, length(x)),
+                           alpha = 1e-3,
+                           cutoff = Inf) {
+  x <- as.numeric(x)
+  n <- as.integer(n)
+  strata <- as_stratum(strata)
+  alpha <- as.numeric(alpha)
+  cutoff <- as.numeric(cutoff)
+  unsplit(inclusion_prob_(x, n, strata, alpha, cutoff), strata)
+}

R/prop_allocation.R

@@ -52,7 +52,7 @@ highest_averages <- function(p, n, initial, available, ties, dist) {
   res[order(ord)]
 }
 
-#' Proportional allocation
+#' Construct a proportional allocation
 #'
 #' Generate a proportional-to-size allocation for stratified sampling.
 #'
@@ -64,9 +64,11 @@ highest_averages <- function(p, n, initial, available, ties, dist) {
 #'
 #' \describe{
 #' \item{Jefferson/D'Hondt}{`\(a) a + 1`}
-#' \item{Webster/Sainte-Laguë}{`\(a) a + 0.5`} \item{Imperiali}{`\(a)
-#' a + 2`} \item{Huntington-Hill}{`\(a) sqrt(a * (a + 1))`}
-#' \item{Danish}{`\(a) a + 1 / 3`} \item{Adams}{`\(a) a`}
+#' \item{Webster/Sainte-Laguë}{`\(a) a + 0.5`}
+#' \item{Imperiali}{`\(a) a + 2`}
+#' \item{Huntington-Hill}{`\(a) sqrt(a * (a + 1))`}
+#' \item{Danish}{`\(a) a + 1 / 3`}
+#' \item{Adams}{`\(a) a`}
 #' \item{Dean}{`\(a) a * (a + 1) / (a + 0.5)`}
 #' }
 #'
@@ -104,34 +106,31 @@ highest_averages <- function(p, n, initial, available, ties, dist) {
 #' @param ties Either 'largest' to break ties in favor of the stratum with the
 #' largest size, or 'first' to break ties in favor of the ordering of
 #' `strata`.
-#' 
+#'
 #' @returns
 #' A named integer vector of sample sizes for each stratum in `strata`.
 #
 #' @seealso
 #' [sps()] for stratified sequential Poisson sampling.
-#' 
+#'
 #' [expected_coverage()] to calculate the expected number of strata in a sample
 #' without stratification.
 #'
-#' `strAlloc` in the \pkg{PracTools} package for other allocation methods.
-#' 
-#' @references 
+#' `strAlloc()` in the \pkg{PracTools} package for other allocation methods.
+#'
+#' @references
 #' Balinksi, M. L. and Young, H. P. (1982).
 #' *Fair Representation: Meeting the Ideal of One Man, One Vote*.
 #' Yale University Press.
-#' 
+#'
 #' @examples
 #' # Make a population with units of different size
 #' x <- c(rep(1:9, each = 3), 100, 100, 100)
 #'
 #' # ... and 10 strata
 #' s <- rep(letters[1:10], each = 3)
 #'
-#' # Should get about 7 to 8 strata in a sample on average
-#' expected_coverage(x, 15, s)
-#'
-#' # Generate an allocation with all 10
+#' # Generate an allocation
 #' prop_allocation(x, 15, s, initial = 1)
 #'
 #' @export

R/sps-package.R

@@ -1,3 +1,3 @@
-#' @keywords internal 
+#' @keywords internal
 #' @aliases sps-package
-"_PACKAGE"
+"_PACKAGE"