From 311d55dd736c70c64070af046fa41a78ce5ca437 Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Fri, 17 Jul 2026 22:09:51 -0400 Subject: [PATCH 1/2] Updated citations --- CITATION.cff | 74 ++++++++++++++++++++++----------------------------- DESCRIPTION | 2 +- inst/CITATION | 2 +- 3 files changed, 34 insertions(+), 44 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index 98f4b33..8b5769f 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,14 +1,14 @@ -# -------------------------------------------- -# CITATION file created with {cffr} R package +# ------------------------------------------------ +# CITATION.cff file created with {cffr} R package # See also: https://docs.ropensci.org/cffr/ -# -------------------------------------------- +# ------------------------------------------------ cff-version: 1.2.0 message: 'To cite package "sps" in publications use:' type: software license: MIT title: 'sps: Sequential Poisson Sampling' -version: 0.6.3 +version: 0.6.4 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.3 + notes: R package version 0.6.4 repository: https://CRAN.R-project.org/package=sps repository-code: https://github.com/marberts/sps url: https://marberts.github.io/sps/ @@ -61,10 +61,13 @@ references: url: https://www.R-project.org/ authors: - name: R Core Team + website: https://ror.org/02zz1nj61 institution: name: R Foundation for Statistical Computing + website: https://ror.org/05qewa988 address: Vienna, Austria - year: '2025' + year: '2026' + doi: 10.32614/R.manuals version: '>= 4.2' - type: software title: stats @@ -72,64 +75,51 @@ references: notes: Imports authors: - name: R Core Team + website: https://ror.org/02zz1nj61 institution: name: R Foundation for Statistical Computing + website: https://ror.org/05qewa988 address: Vienna, Austria - year: '2025' + year: '2026' + doi: 10.32614/R.manuals - type: software title: kit abstract: 'kit: Data Manipulation Functions Implemented in C' notes: Suggests - url: https://github.com/2005m/kit + url: https://fastverse.org/kit/ repository: https://CRAN.R-project.org/package=kit authors: - family-names: Jacob given-names: Morgan email: morgan.emailbox@gmail.com - year: '2025' + year: '2026' doi: 10.32614/CRAN.package.kit version: '>= 0.0.10' - type: software - title: knitr - abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R' + title: litedown + abstract: 'litedown: A Lightweight Version of R Markdown' notes: Suggests - url: https://yihui.org/knitr/ - repository: https://CRAN.R-project.org/package=knitr + url: https://github.com/yihui/litedown + repository: https://CRAN.R-project.org/package=litedown authors: - family-names: Xie given-names: Yihui email: xie@yihui.name orcid: https://orcid.org/0000-0003-0645-5666 - year: '2025' - doi: 10.32614/CRAN.package.knitr + year: '2026' + doi: 10.32614/CRAN.package.litedown - type: software - title: quarto - abstract: 'quarto: R Interface to ''Quarto'' Markdown Publishing System' + title: tinytest + abstract: 'tinytest: Lightweight and Feature Complete Unit Testing Framework' notes: Suggests - url: https://quarto-dev.github.io/quarto-r/ - repository: https://CRAN.R-project.org/package=quarto + url: https://github.com/markvanderloo/tinytest + repository: https://CRAN.R-project.org/package=tinytest authors: - - family-names: Allaire - given-names: JJ - email: jj@posit.co - 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 - year: '2025' - doi: 10.32614/CRAN.package.quarto -- type: software - title: testthat - abstract: 'testthat: Unit Testing for R' - notes: Suggests - url: https://testthat.r-lib.org - repository: https://CRAN.R-project.org/package=testthat - authors: - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - year: '2025' - doi: 10.32614/CRAN.package.testthat - version: '>= 3.0.0' + - family-names: Loo + given-names: Mark + name-particle: van der + email: mark.vanderloo@gmail.com + orcid: https://orcid.org/0000-0002-9807-4686 + year: '2026' + doi: 10.32614/CRAN.package.tinytest diff --git a/DESCRIPTION b/DESCRIPTION index b00798e..b14572d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: sps Title: Sequential Poisson Sampling -Version: 0.6.3.9004 +Version: 0.6.4 Authors@R: c( person("Steve", "Martin", role = c("aut", "cre", "cph"), diff --git a/inst/CITATION b/inst/CITATION index 6f44c32..7784216 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -5,7 +5,7 @@ bibentry( title = "{sps}: Sequential Poisson Sampling", author = person("Steve", "Martin", role = c("aut", "cre", "cph"), comment = c(ORCID = "0000-0003-2544-9480")), - year = "2025", + year = "2026", doi = "10.5281/zenodo.10109857", url = "https://cran.r-project.org/package=sps", note = sprintf("R package version %s", meta$Version) From df9c233ba89741f96986b139f609586adfee947f Mon Sep 17 00:00:00 2001 From: Steve Martin Date: Sat, 18 Jul 2026 21:58:10 -0400 Subject: [PATCH 2/2] Updated docs --- NEWS.md | 2 +- R/prop_allocation.R | 6 +++--- R/sps.R | 18 ++++++++++-------- R/sps_iterator.R | 18 +++++++----------- cran-comments.md | 6 ++---- man/expected_coverage.Rd | 6 +++--- man/inclusion_prob.Rd | 6 +++--- man/prop_allocation.Rd | 6 +++--- man/sps.Rd | 8 +++++--- man/sps_iterator.Rd | 9 ++++++--- 10 files changed, 43 insertions(+), 42 deletions(-) diff --git a/NEWS.md b/NEWS.md index c826f71..0628b59 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -## sps (development version) +## sps 0.6.4 - Small improvements to the documentation. diff --git a/R/prop_allocation.R b/R/prop_allocation.R index 423d7fe..67f0b5a 100644 --- a/R/prop_allocation.R +++ b/R/prop_allocation.R @@ -21,7 +21,7 @@ #' Note that a divisor function with \eqn{d(0) = 0} (i.e., Huntington-Hill, #' Adams, Dean) should have an initial allocation of at least 1 for all strata. #' In all cases, ties are broken according to the sum of `x` if -#' `ties = 'largest'`; otherwise, if `ties = 'first'`, then ties are broken +#' `ties = "largest"`; otherwise, if `ties = "first"`, then ties are broken #' according to the levels of `strata`. #' #' In cases where the number of units with non-zero size in a stratum is @@ -50,9 +50,9 @@ #' @param divisor `[function]` A function for the divisor (highest-averages) #' apportionment method. The default uses the Jefferson/D'Hondt method. See #' details for other possible functions. -#' @param ties `[character(1)]` Either 'largest' to break ties in favor of the +#' @param ties `[character(1)]` Either `"largest"` to break ties in favor of the #' stratum with the -#' largest size (the default), or 'first' to break ties in favor of the +#' largest size (the default), or `"first"` to break ties in favor of the #' ordering of `strata`. #' @param name `[character(1)]` Name of the divisor function. See details. #' diff --git a/R/sps.R b/R/sps.R index 6e9b177..7ea98ce 100644 --- a/R/sps.R +++ b/R/sps.R @@ -1,6 +1,6 @@ #' Order sampling (internal) #' @noRd -order_sampling_ <- function(f) { +.order_sampling <- function(f) { f <- match.fun(f) function(p, n, u) { @@ -19,7 +19,7 @@ order_sampling_ <- function(f) { #' Ordinary Poisson sampling (internal) #' @noRd -ps_ <- function(p, n, u) { +.ps <- function(p, n, u) { which(u < p) } @@ -152,13 +152,13 @@ stratify <- function(f) { #' population, distributed uniform between 0 and 1. The default does not use #' permanent random numbers, instead generating a random vector when the #' function is called. -#' @param alpha `[0 <= numeric < 1]` A numeric vector with values between 0 and +#' @param alpha `[0 <= numeric <= 1]` A numeric vector with values between 0 and #' 1 for each stratum, #' ordered according to the levels of `strata`. Units with inclusion -#' probabilities greater than or equal to 1 - `alpha` are set to 1 for +#' probabilities greater than or equal to `1 - alpha` are set to 1 for #' each stratum. A single value is recycled for all strata. The default is #' slightly larger than 0. -#' @param cutoff `[numeric >= 0]` A positive numeric vector of cutoffs for each +#' @param cutoff `[numeric > 0]` A positive numeric vector of cutoffs for each #' stratum, ordered #' according to the levels of `strata`. Units with `x >= cutoff` get #' an inclusion probability of 1 for each stratum. A single value is recycled @@ -192,6 +192,8 @@ stratify <- function(f) { #' #' [sps_repweights()] for generating bootstrap replicate weights. #' +#' [sps_iterator()] for a drawing a sample one unit at a time. +#' #' The `UPpoisson()` and `UPopips()` functions in the \pkg{sampling} #' package for ordinary and sequential Poisson sampling, respectively. Note #' that the algorithm for order sampling in the `UPopips()` function is @@ -283,16 +285,16 @@ stratify <- function(f) { #' order_sampling2(0)(x, 6, prn = u) # successive #' order_sampling2(-1)(x, 6, prn = u) # Pareto #' @export -sps <- stratify(order_sampling_(identity)) +sps <- stratify(.order_sampling(identity)) #' Ordinary Poisson sampling #' @rdname sps #' @export -ps <- stratify(ps_) +ps <- stratify(.ps) #' Factory to make order sampling schemes #' @rdname sps #' @export order_sampling <- function(dist) { - stratify(order_sampling_(dist)) + stratify(.order_sampling(dist)) } diff --git a/R/sps_iterator.R b/R/sps_iterator.R index e9ca2fe..26e1bac 100644 --- a/R/sps_iterator.R +++ b/R/sps_iterator.R @@ -6,10 +6,10 @@ #' @inheritParams sps #' @param n `[integer(1) >= 0]` A positive integer giving the initial sample #' size for the iterator. The default is 0. -#' @param alpha `[0 <= numeric(1) < 1]` A number between 0 and 1. Units with -#' inclusion probabilities greater than or equal to 1 - `alpha` are set to 1. +#' @param alpha `[0 <= numeric(1) <= 1]` A number between 0 and 1. Units with +#' inclusion probabilities greater than or equal to `1 - alpha` are set to 1. #' The default is slightly larger than 0. -#' @param cutoff `[numeric(1) >= 0]` A numeric cutoff. Units with `x >= cutoff` +#' @param cutoff `[numeric(1) > 0]` A numeric cutoff. Units with `x >= cutoff` #' get an inclusion probability of 1. The default does not apply a cutoff. #' #' @returns @@ -17,6 +17,9 @@ #' argument giving the sentinel value to indicate that there are no units #' left to sample (default `NULL`). #' +#' @seealso +#' [sps()] for drawing a sequential Poisson sample. +#' #' @examples #' prn <- runif(5) #' s <- sps_iterator(1:5, prn = prn) @@ -32,14 +35,7 @@ sps_iterator <- function(x, n = 0L, prn = NULL, alpha = 0.001, cutoff = Inf) { if (any(x <= 0)) { stop("sizes must be strictly greater than 0") } - if (is.null(prn)) { - prn <- stats::runif(length(x)) - } else { - prn <- as.numeric(prn) - } - if (length(x) != length(prn)) { - stop("`x` and `prn` must be the same length") - } + prn <- random_deviates(prn, x) s <- order(prn / x) pop <- seq_along(s) diff --git a/cran-comments.md b/cran-comments.md index c2dd031..6648edb 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,15 +1,13 @@ ## Test environments -- local Ubuntu 24.04 installation, R 4.5.2 +- local Ubuntu 24.04 installation, R 4.6.1 - win-builder (devel, release, oldrelease) - github actions: Ubuntu (devel, release, oldrelease), Mac (release), Windows (release) ## R CMD check results -There were no ERRORs or WARNINGs. - -win-builder (oldrelease) gave two spurious NOTEs. +There were no ERRORs or WARNINGs or NOTEs. ## Downstream dependencies diff --git a/man/expected_coverage.Rd b/man/expected_coverage.Rd index 7131e5c..655d0ec 100644 --- a/man/expected_coverage.Rd +++ b/man/expected_coverage.Rd @@ -17,14 +17,14 @@ giving the strata associated with units in the population. The default is to place all units into a single stratum.} -\item{alpha}{\verb{[0 <= numeric < 1]} A numeric vector with values between 0 and +\item{alpha}{\verb{[0 <= numeric <= 1]} A numeric vector with values between 0 and 1 for each stratum, ordered according to the levels of \code{strata}. Units with inclusion -probabilities greater than or equal to 1 - \code{alpha} are set to 1 for +probabilities greater than or equal to \code{1 - alpha} are set to 1 for each stratum. A single value is recycled for all strata. The default is slightly larger than 0.} -\item{cutoff}{\verb{[numeric >= 0]} A positive numeric vector of cutoffs for each +\item{cutoff}{\verb{[numeric > 0]} A positive numeric vector of cutoffs for each stratum, ordered according to the levels of \code{strata}. Units with \code{x >= cutoff} get an inclusion probability of 1 for each stratum. A single value is recycled diff --git a/man/inclusion_prob.Rd b/man/inclusion_prob.Rd index a742b84..33e5a56 100644 --- a/man/inclusion_prob.Rd +++ b/man/inclusion_prob.Rd @@ -23,14 +23,14 @@ giving the strata associated with units in the population. The default is to place all units into a single stratum.} -\item{alpha}{\verb{[0 <= numeric < 1]} A numeric vector with values between 0 and +\item{alpha}{\verb{[0 <= numeric <= 1]} A numeric vector with values between 0 and 1 for each stratum, ordered according to the levels of \code{strata}. Units with inclusion -probabilities greater than or equal to 1 - \code{alpha} are set to 1 for +probabilities greater than or equal to \code{1 - alpha} are set to 1 for each stratum. A single value is recycled for all strata. The default is slightly larger than 0.} -\item{cutoff}{\verb{[numeric >= 0]} A positive numeric vector of cutoffs for each +\item{cutoff}{\verb{[numeric > 0]} A positive numeric vector of cutoffs for each stratum, ordered according to the levels of \code{strata}. Units with \code{x >= cutoff} get an inclusion probability of 1 for each stratum. A single value is recycled diff --git a/man/prop_allocation.Rd b/man/prop_allocation.Rd index 0ab9529..b608bd2 100644 --- a/man/prop_allocation.Rd +++ b/man/prop_allocation.Rd @@ -49,9 +49,9 @@ stratum.} apportionment method. The default uses the Jefferson/D'Hondt method. See details for other possible functions.} -\item{ties}{\verb{[character(1)]} Either 'largest' to break ties in favor of the +\item{ties}{\verb{[character(1)]} Either \code{"largest"} to break ties in favor of the stratum with the -largest size (the default), or 'first' to break ties in favor of the +largest size (the default), or \code{"first"} to break ties in favor of the ordering of \code{strata}.} \item{name}{\verb{[character(1)]} Name of the divisor function. See details.} @@ -85,7 +85,7 @@ are a number of different divisor functions: Note that a divisor function with \eqn{d(0) = 0} (i.e., Huntington-Hill, Adams, Dean) should have an initial allocation of at least 1 for all strata. In all cases, ties are broken according to the sum of \code{x} if -\code{ties = 'largest'}; otherwise, if \code{ties = 'first'}, then ties are broken +\code{ties = "largest"}; otherwise, if \code{ties = "first"}, then ties are broken according to the levels of \code{strata}. In cases where the number of units with non-zero size in a stratum is diff --git a/man/sps.Rd b/man/sps.Rd index 4bfb0a1..c4e6301 100644 --- a/man/sps.Rd +++ b/man/sps.Rd @@ -32,14 +32,14 @@ population, distributed uniform between 0 and 1. The default does not use permanent random numbers, instead generating a random vector when the function is called.} -\item{alpha}{\verb{[0 <= numeric < 1]} A numeric vector with values between 0 and +\item{alpha}{\verb{[0 <= numeric <= 1]} A numeric vector with values between 0 and 1 for each stratum, ordered according to the levels of \code{strata}. Units with inclusion -probabilities greater than or equal to 1 - \code{alpha} are set to 1 for +probabilities greater than or equal to \code{1 - alpha} are set to 1 for each stratum. A single value is recycled for all strata. The default is slightly larger than 0.} -\item{cutoff}{\verb{[numeric >= 0]} A positive numeric vector of cutoffs for each +\item{cutoff}{\verb{[numeric > 0]} A positive numeric vector of cutoffs for each stratum, ordered according to the levels of \code{strata}. Units with \code{x >= cutoff} get an inclusion probability of 1 for each stratum. A single value is recycled @@ -215,6 +215,8 @@ https://doi.org/10.1016/S0378-3758(00)00104-X. \code{\link[=sps_repweights]{sps_repweights()}} for generating bootstrap replicate weights. +\code{\link[=sps_iterator]{sps_iterator()}} for a drawing a sample one unit at a time. + The \code{UPpoisson()} and \code{UPopips()} functions in the \pkg{sampling} package for ordinary and sequential Poisson sampling, respectively. Note that the algorithm for order sampling in the \code{UPopips()} function is diff --git a/man/sps_iterator.Rd b/man/sps_iterator.Rd index fbb443d..e55cde5 100644 --- a/man/sps_iterator.Rd +++ b/man/sps_iterator.Rd @@ -19,11 +19,11 @@ population, distributed uniform between 0 and 1. The default does not use permanent random numbers, instead generating a random vector when the function is called.} -\item{alpha}{\verb{[0 <= numeric(1) < 1]} A number between 0 and 1. Units with -inclusion probabilities greater than or equal to 1 - \code{alpha} are set to 1. +\item{alpha}{\verb{[0 <= numeric(1) <= 1]} A number between 0 and 1. Units with +inclusion probabilities greater than or equal to \code{1 - alpha} are set to 1. The default is slightly larger than 0.} -\item{cutoff}{\verb{[numeric(1) >= 0]} A numeric cutoff. Units with \code{x >= cutoff} +\item{cutoff}{\verb{[numeric(1) > 0]} A numeric cutoff. Units with \code{x >= cutoff} get an inclusion probability of 1. The default does not apply a cutoff.} } \value{ @@ -45,3 +45,6 @@ s() # Same as drawing the sample with 3 units. sps(1:5, 3, prn = prn) } +\seealso{ +\code{\link[=sps]{sps()}} for drawing a sequential Poisson sample. +}