diff --git a/.Rbuildignore b/.Rbuildignore index a799dca..4183c88 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -2,6 +2,7 @@ ^\.Rproj\.user$ ^README\.Rmd$ ^\.github$ +^\.githooks$ ^LICENSE\.md$ ^data-raw$ ^_pkgdown\.yml$ @@ -9,3 +10,4 @@ ^pkgdown$ ^\.positai$ ^\.claude$ +^cran-comments\.md$ diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..d642f20 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "r-lib@posit-dev-skills": true + } +} diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100644 index 0000000..d244a2a --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,19 @@ +#!/bin/bash +README=($(git diff --cached --name-only | grep -Ei '^README\.[R]?md$')) +RMD_STAGED=$(git diff --cached --name-only | grep -Eic '^README\.Rmd$') +MSG="use 'git commit --no-verify' to override this check" + +if [[ ${#README[@]} == 0 ]]; then + exit 0 +fi + +if [[ README.Rmd -nt README.md ]]; then + echo -e "README.md is out of date; please re-knit README.Rmd\n$MSG" + exit 1 +elif [[ $RMD_STAGED -gt 0 && ${#README[@]} -lt 2 ]]; then + # Staging README.Rmd without README.md means the re-knit is missing. + # The reverse is fine: a change to R code can alter knitted output + # while README.Rmd itself is untouched. + echo -e "README.Rmd is staged without README.md; please stage the re-knit\n$MSG" + exit 1 +fi diff --git a/.github/install_package.R b/.github/install_package.R deleted file mode 100644 index 49616bc..0000000 --- a/.github/install_package.R +++ /dev/null @@ -1,3 +0,0 @@ -# Works with Github actions to install the built package. -# Could not get Rscript -e to work with Windows, necessitating this file. -install.packages("../SampleSelectR", repos=NULL, type="source", lib="./package_binary") diff --git a/DESCRIPTION b/DESCRIPTION index 76af138..ba65600 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -7,13 +7,21 @@ Authors@R: c( person("Thomas", "Burkett", role = "aut"), person("Philip", "Lee", role = "aut"), person("Haby", "Sow", role = "aut"), - person(, "RTI International", role = "fnd") + person(, "RTI International", role = c("cph", "fnd")) ) -Description: Randomly select samples with SRS, systematic, and various PPS methods. Also includes functionality to select within strata and allocate sample sizes. +Description: Randomly select samples using simple random sampling (SRS), + systematic sampling, and various probability proportional to size + (PPS) methods, including systematic PPS and sequential PPS (i.e., + Chromy's method). Also includes functionality to allocate sample + sizes across strata using proportional, power, Neyman, and optimal + allocation methods, and to select samples within strata. Designed to + make survey sample design and selection reproducible, efficient, and + transparent for survey statisticians and researchers. Sampling + methods follow Kalton (1983) and Chromy + (1979) . License: GPL (>= 3) Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.3 Depends: R (>= 4.1.0) Imports: @@ -27,3 +35,4 @@ BugReports: https://github.com/RTIInternational/SampleSelectR/issues Suggests: testthat (>= 3.0.0) Config/testthat/edition: 3 +Config/roxygen2/version: 8.1.0 diff --git a/NAMESPACE b/NAMESPACE index 37e108c..e567614 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -7,15 +7,19 @@ export(serp_sort) export(srs) export(sys) export(sys_pps) -importFrom(data.table,":=") -importFrom(data.table,.BY) -importFrom(data.table,.EACHI) -importFrom(data.table,.GRP) -importFrom(data.table,.I) -importFrom(data.table,.N) -importFrom(data.table,.NGRP) -importFrom(data.table,.SD) -importFrom(data.table,data.table) -importFrom(rlang,.data) -importFrom(rlang,.env) +importFrom(data.table, + ":=", + .BY, + .EACHI, + .GRP, + .I, + .N, + .NGRP, + .SD, + data.table +) +importFrom(rlang, + .data, + .env +) importFrom(stats,runif) diff --git a/R/allocate.R b/R/allocate.R index 786b5d5..e9aa694 100644 --- a/R/allocate.R +++ b/R/allocate.R @@ -65,7 +65,7 @@ #' \item the raw allocations before accounting for N.h, lbound, and n.samp if needed \[\code{"raw"}\], #' \item the continuous version after accounting for the above \[\code{"adjusted"}\], and/or #' \item the rounded version of the above \[\code{"rounded"}\] -#' } \cr +#' } #' Default is to only return the final rounded version \[\code{"rounded"}\]. \cr #' If one version is requested, the result will be a numeric vector. Otherwise, the result will be a named list matching the requested outputs. #' @return If one output type is requested, a numeric vector of allocations. diff --git a/R/chromy_pps.R b/R/chromy_pps.R index e70dc6a..dd62c7d 100644 --- a/R/chromy_pps.R +++ b/R/chromy_pps.R @@ -78,7 +78,7 @@ chromy_pps <- function(frame, n, mos, outall = FALSE, curstrat = NULL) { #' @param exphits A vector of non-negative values #' #' @return Returns a vector the same length of exphits with the number of random hits for each unit -#' @keywords internal +#' @noRd #' @references Chromy, J. R. (1979). “Sequential Sample Selection Methods.” #' In \emph{Proceedings of the Survey Research Methods Section}, 401–406. #' Washington, DC: American Statistical Association. diff --git a/R/create_group_variable.R b/R/create_group_variable.R index 9e5d3c8..6a27346 100644 --- a/R/create_group_variable.R +++ b/R/create_group_variable.R @@ -11,7 +11,7 @@ #' #' @return A copy of the input data with the addition of the grouping ID variable #' -#' @keywords internal +#' @noRd create_group_variable <- function(.data, groupvars, groupid) { # Check that groupid is not a column name in .data diff --git a/R/serp_sort.R b/R/serp_sort.R index 973c9a3..47092d3 100644 --- a/R/serp_sort.R +++ b/R/serp_sort.R @@ -15,6 +15,15 @@ #' #' @return A copy of .data that is hierarchically sorted and, if specified, includes the sort group variables created for sorting #' +#' @examples +#' # Sort counties by Region, then Division, in a serpentine pattern +#' county_2023 |> +#' serp_sort("Region", "Division") +#' +#' # Keep the intermediate sort-group columns (sortSerp1, sortSerp2) +#' county_2023 |> +#' serp_sort("Region", "Division", sortID = TRUE) +#' #' @export serp_sort <- function(.data, ..., naorder = TRUE, sortID = FALSE) { diff --git a/R/util.R b/R/util.R index 5c34668..b34d1bc 100644 --- a/R/util.R +++ b/R/util.R @@ -5,7 +5,7 @@ #' #' @param frame An object to be validated as a sampling frame. #' @return Stops execution if validation fails. Invisibly returns TRUE. -#' @keywords internal +#' @noRd check_frame_type <- function(frame) { if (!(inherits(frame, "data.frame")) && !(inherits(frame, "data.table")) && @@ -25,7 +25,7 @@ check_frame_type <- function(frame) { #' @param curstrat Optional character vector indicating the stratum. #' @param n_le_N Logical. Should `n` be forced to be less than or equal to `N`? #' @return Stops execution if validation fails or outputs a message if `n == N`. Invisibly returns TRUE. -#' @keywords internal +#' @noRd check_n <- function(n, frame, curstrat, n_le_N = FALSE) { N <- nrow(frame) @@ -65,7 +65,7 @@ check_n <- function(n, frame, curstrat, n_le_N = FALSE) { #' Checks that the outall argument is a single logical value. #' @param outall A logical value indicating whether to return the full frame or only selected rows. #' @return Stops execution if validation fails. Invisibly returns TRUE. -#' @keywords internal +#' @noRd check_outall <- function(outall) { if (length(outall) != 1 || !is.logical(outall)) { stop("Argument 'outall' must be a single logical value (TRUE or FALSE).") @@ -79,7 +79,7 @@ check_outall <- function(outall) { #' @param mos A string or symbol representing the column name of the measure of size. #' @param frame The sampling frame as a data.frame or similar object. #' @return Stops execution if validation fails. Invisibly returns TRUE. -#' @keywords internal +#' @noRd check_string_mos <- function(mos, frame) { if (!is.character(mos)) { stop("The `mos` parameter must be a character string.") @@ -111,30 +111,33 @@ check_string_mos <- function(mos, frame) { #' Output sampling summary to the console +#' #' Displays sample size, frame size, and optionally the sampling interval and random start. +#' #' @param n Sample size. #' @param N Frame size. #' @param k Optional sampling interval. #' @param r Optional random start. #' @param curstrat Optional stratum label. -#' @return Prints output to the console. Invisibly returns NULL -#' @keywords internal +#' @return Emits the summary as a message, so it can be silenced with +#' `suppressMessages()`. Invisibly returns NULL +#' @noRd Sampling_Output <- function(n, N, k = NULL, r = NULL, curstrat = NULL) { if (!is.null(curstrat)) { prefix <- "--" - cat("Stratum:", curstrat, "\n") + message("Stratum: ", curstrat) } else { prefix <- "" } - cat(prefix, "Frame size: ", N, "\n", sep = "") - cat(prefix, "Sample size: ", n, "\n", sep = "") + message(prefix, "Frame size: ", N) + message(prefix, "Sample size: ", n) if (!is.null(k)) { - cat(prefix, "Sampling interval (k): ", k, "\n", sep = "") + message(prefix, "Sampling interval (k): ", k) } if (!is.null(r)) { - cat(prefix, "Random start (r): ", r, "\n", sep = "") + message(prefix, "Random start (r): ", r) } invisible(NULL) diff --git a/README.Rmd b/README.Rmd index a2dfacf..f7b42d1 100644 --- a/README.Rmd +++ b/README.Rmd @@ -44,6 +44,14 @@ Allocation methods include: ## Installation +You can install SampleSelectR from CRAN: + +```{r} +#| eval: false + +install.packages("SampleSelectR") +``` + You can install the development version of SampleSelectR from [GitHub](https://github.com/RTIInternational/SampleSelectR) with either the `pak` or `devtools` package: @@ -144,6 +152,10 @@ sum(ipeds_pps$NumberHits) We’d love your help to make SampleSelectR better! Here’s the workflow we use: +- One-time setup: after cloning, run `git config core.hooksPath .githooks` + to enable the repo's git hooks (e.g., the check that keeps README.md in + sync with README.Rmd). + - Start from the dev branch - Always update your local copy first (git pull origin dev). diff --git a/README.md b/README.md index 6b54f11..9b3356e 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,12 @@ Allocation methods include: ## Installation +You can install SampleSelectR from CRAN: + +``` r +install.packages("SampleSelectR") +``` + You can install the development version of SampleSelectR from [GitHub](https://github.com/RTIInternational/SampleSelectR) with either the `pak` or `devtools` package: @@ -69,14 +75,14 @@ realistic sample frames including: ``` r summary(ipeds) -#> UNITID INSTNM STABBR FIPS -#> Min. :100654 Length:5914 Length:5914 Min. : 1.00 -#> 1st Qu.:169277 Class :character Class :character 1st Qu.:13.00 -#> Median :219493 Mode :character Mode :character Median :29.00 -#> Mean :284664 Mean :29.19 -#> 3rd Qu.:446954 3rd Qu.:42.00 -#> Max. :499723 Max. :78.00 -#> +#> UNITID INSTNM STABBR FIPS +#> Min. :100654 Length :5914 Length :5914 Min. : 1.00 +#> 1st Qu.:169277 N.unique :5819 N.unique : 59 1st Qu.:13.00 +#> Median :219493 N.blank : 0 N.blank : 0 Median :29.00 +#> Mean :284664 Min.nchar: 3 Min.nchar: 2 Mean :29.19 +#> 3rd Qu.:446954 Max.nchar: 91 Max.nchar: 2 3rd Qu.:42.00 +#> Max. :499723 Max. :78.00 +#> #> OBEREG #> Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV):1467 #> Mid East (DE, DC, MD, NJ, NY, PA) : 971 @@ -135,14 +141,14 @@ summary(ipeds) #> summary(county_2023) -#> GEOID Name State Region -#> Length:3144 Length:3144 Length:3144 Northeast: 218 -#> Class :character Class :character Class :character Midwest :1055 -#> Mode :character Mode :character Mode :character South :1422 -#> West : 449 -#> -#> -#> +#> GEOID Name State Region +#> Length :3144 Length :3144 Length :3144 Northeast: 218 +#> N.unique :3144 N.unique :3144 N.unique : 51 Midwest :1055 +#> N.blank : 0 N.blank : 0 N.blank : 0 South :1422 +#> Min.nchar: 5 Min.nchar: 16 Min.nchar: 2 West : 449 +#> Max.nchar: 5 Max.nchar: 59 Max.nchar: 2 +#> +#> #> Division Pop_Tot Pop_Pct_White_NH Pop_Pct_Black_NH #> West North Central:618 Min. : 43 Min. : 2.153 Min. : 0.0000 #> South Atlantic :588 1st Qu.: 10794 1st Qu.: 62.608 1st Qu.: 0.6574 @@ -193,14 +199,14 @@ summary(county_2023) #> summary(puma_2023) -#> GEOID Name State Region -#> Length:2462 Length:2462 Length:2462 Northeast:423 -#> Class :character Class :character Class :character Midwest :506 -#> Mode :character Mode :character Mode :character South :952 -#> West :581 -#> -#> -#> +#> GEOID Name State Region +#> Length :2462 Length :2462 Length :2462 Northeast:423 +#> N.unique :2462 N.unique :2462 N.unique : 51 Midwest :506 +#> N.blank : 0 N.blank : 0 N.blank : 0 South :952 +#> Min.nchar: 7 Min.nchar: 19 Min.nchar: 2 West :581 +#> Max.nchar: 7 Max.nchar: 106 Max.nchar: 2 +#> +#> #> Division Pop_Tot Pop_Pct_White_NH Pop_Pct_Black_NH #> South Atlantic :496 Min. : 94457 Min. : 0.6772 Min. : 0.06043 #> Pacific :392 1st Qu.:114269 1st Qu.:41.1324 1st Qu.: 2.25999 @@ -299,7 +305,7 @@ ipeds_alloc <- ipeds_summary |> #> N.h = 7, 299, 971, 851, 468, 1467, 633, 216, 870, 132 #> #> Output: -#> 2, 25, 82, 73, 39, 124, 53, 18, 73, 11 +#> rounded = 2, 25, 82, 72, 40, 124, 53, 18, 73, 11 ipeds_alloc #> # A tidytable: 10 × 3 @@ -308,8 +314,8 @@ ipeds_alloc #> 1 U.S. Service schools 7 2 #> 2 New England (CT, ME, MA, NH, RI, VT) 299 25 #> 3 Mid East (DE, DC, MD, NJ, NY, PA) 971 82 -#> 4 Great Lakes (IL, IN, MI, OH, WI) 851 73 -#> 5 Plains (IA, KS, MN, MO, NE, ND, SD) 468 39 +#> 4 Great Lakes (IL, IN, MI, OH, WI) 851 72 +#> 5 Plains (IA, KS, MN, MO, NE, ND, SD) 468 40 #> 6 Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV) 1467 124 #> 7 Southwest (AZ, NM, OK, TX) 633 53 #> 8 Rocky Mountains (CO, ID, MT, UT, WY) 216 18 @@ -332,34 +338,34 @@ ipeds_srs <- ipeds |> n = tidytable::select(ipeds_alloc, OBEREG, sample_size), strata = "OBEREG" ) -#> Stratum: OBEREG = Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV) +#> Stratum: OBEREG = Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV) #> --Frame size: 1467 #> --Sample size: 124 -#> Stratum: OBEREG = Far West (AK, CA, HI, NV, OR, WA) +#> Stratum: OBEREG = Far West (AK, CA, HI, NV, OR, WA) #> --Frame size: 870 #> --Sample size: 73 -#> Stratum: OBEREG = Southwest (AZ, NM, OK, TX) +#> Stratum: OBEREG = Southwest (AZ, NM, OK, TX) #> --Frame size: 633 #> --Sample size: 53 -#> Stratum: OBEREG = U.S. Service schools +#> Stratum: OBEREG = U.S. Service schools #> --Frame size: 7 #> --Sample size: 2 -#> Stratum: OBEREG = Plains (IA, KS, MN, MO, NE, ND, SD) +#> Stratum: OBEREG = Plains (IA, KS, MN, MO, NE, ND, SD) #> --Frame size: 468 -#> --Sample size: 39 -#> Stratum: OBEREG = Rocky Mountains (CO, ID, MT, UT, WY) +#> --Sample size: 40 +#> Stratum: OBEREG = Rocky Mountains (CO, ID, MT, UT, WY) #> --Frame size: 216 #> --Sample size: 18 -#> Stratum: OBEREG = New England (CT, ME, MA, NH, RI, VT) +#> Stratum: OBEREG = New England (CT, ME, MA, NH, RI, VT) #> --Frame size: 299 #> --Sample size: 25 -#> Stratum: OBEREG = Mid East (DE, DC, MD, NJ, NY, PA) +#> Stratum: OBEREG = Mid East (DE, DC, MD, NJ, NY, PA) #> --Frame size: 971 #> --Sample size: 82 -#> Stratum: OBEREG = Great Lakes (IL, IN, MI, OH, WI) +#> Stratum: OBEREG = Great Lakes (IL, IN, MI, OH, WI) #> --Frame size: 851 -#> --Sample size: 73 -#> Stratum: OBEREG = Other U.S. jurisdictions (AS, FM, GU, MH, MP, PR, PW, VI) +#> --Sample size: 72 +#> Stratum: OBEREG = Other U.S. jurisdictions (AS, FM, GU, MH, MP, PR, PW, VI) #> --Frame size: 132 #> --Sample size: 11 @@ -393,72 +399,72 @@ ipeds_pps <- ipeds |> sort_vars = "SECTOR", sort_method = "serpentine" ) -#> Stratum: OBEREG = Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV) +#> Stratum: OBEREG = Southeast (AL, AR, FL, GA, KY, LA, MS, NC, SC, TN, VA, WV) #> --Frame size: 1467 #> --Sample size: 124 -#> --Sampling interval (k): 37489.19 -#> --Random start (r): 17174.08 -#> Stratum: OBEREG = Far West (AK, CA, HI, NV, OR, WA) +#> --Sampling interval (k): 37489.185483871 +#> --Random start (r): 32553.0152071789 +#> Stratum: OBEREG = Far West (AK, CA, HI, NV, OR, WA) #> --Frame size: 870 #> --Sample size: 73 -#> --Sampling interval (k): 46640.48 -#> --Random start (r): 23535.96 -#> Stratum: OBEREG = Southwest (AZ, NM, OK, TX) +#> --Sampling interval (k): 46640.4794520548 +#> --Random start (r): 21366.3567358216 +#> Stratum: OBEREG = Southwest (AZ, NM, OK, TX) #> --Frame size: 633 #> --Sample size: 53 -#> --Sampling interval (k): 49474.49 -#> --Random start (r): 33072.34 -#> Stratum: OBEREG = U.S. Service schools +#> --Sampling interval (k): 49474.4905660377 +#> --Random start (r): 24966.0777293528 +#> Stratum: OBEREG = U.S. Service schools #> --Frame size: 7 #> --Sample size: 2 #> --Sampling interval (k): 9372 -#> --Random start (r): 2483.683 -#> Stratum: OBEREG = Plains (IA, KS, MN, MO, NE, ND, SD) +#> --Random start (r): 6264.92460871395 +#> Stratum: OBEREG = Plains (IA, KS, MN, MO, NE, ND, SD) #> --Frame size: 468 -#> --Sample size: 39 -#> --Sampling interval (k): 35210.1 -#> --Random start (r): 301.2639 -#> Stratum: OBEREG = Rocky Mountains (CO, ID, MT, UT, WY) +#> --Sample size: 40 +#> --Sampling interval (k): 34329.85 +#> --Random start (r): 9097.78782175722 +#> Stratum: OBEREG = Rocky Mountains (CO, ID, MT, UT, WY) #> --Frame size: 216 #> --Sample size: 18 #> --Sampling interval (k): 57314.5 -#> --Random start (r): 10947.04 -#> Stratum: OBEREG = New England (CT, ME, MA, NH, RI, VT) +#> --Random start (r): 490.393121512723 +#> Stratum: OBEREG = New England (CT, ME, MA, NH, RI, VT) #> --Frame size: 299 #> --Sample size: 25 #> --Sampling interval (k): 44218.08 -#> --Random start (r): 6258.501 -#> Stratum: OBEREG = Mid East (DE, DC, MD, NJ, NY, PA) +#> --Random start (r): 8445.63029531848 +#> Stratum: OBEREG = Mid East (DE, DC, MD, NJ, NY, PA) #> --Frame size: 971 #> --Sample size: 82 -#> --Sampling interval (k): 33082.89 -#> --Random start (r): 11354.24 -#> Stratum: OBEREG = Great Lakes (IL, IN, MI, OH, WI) +#> --Sampling interval (k): 33082.8902439024 +#> --Random start (r): 4682.45798795425 +#> Stratum: OBEREG = Great Lakes (IL, IN, MI, OH, WI) #> --Frame size: 851 -#> --Sample size: 73 -#> --Sampling interval (k): 35699.49 -#> --Random start (r): 3529.973 -#> Stratum: OBEREG = Other U.S. jurisdictions (AS, FM, GU, MH, MP, PR, PW, VI) +#> --Sample size: 72 +#> --Sampling interval (k): 36195.3194444444 +#> --Random start (r): 12422.441402056 +#> Stratum: OBEREG = Other U.S. jurisdictions (AS, FM, GU, MH, MP, PR, PW, VI) #> --Frame size: 132 #> --Sample size: 11 -#> --Sampling interval (k): 16320.64 -#> --Random start (r): 11469.85 +#> --Sampling interval (k): 16320.6363636364 +#> --Random start (r): 1613.78791611839 ipeds_pps -#> # A tidytable: 474 × 19 +#> # A tidytable: 473 × 19 #> OBEREG UNITID INSTNM STABBR FIPS ICLEVEL SECTOR LOCALE DEGGRANT HLOFFER #> -#> 1 Southeast … 100663 Unive… AL 1 Four o… Publi… City:… Degree-… Doctor… +#> 1 Southeast … 100706 Unive… AL 1 Four o… Publi… City:… Degree-… Doctor… #> 2 Southeast … 100751 The U… AL 1 Four o… Publi… City:… Degree-… Doctor… #> 3 Southeast … 100858 Aubur… AL 1 Four o… Publi… City:… Degree-… Doctor… -#> 4 Southeast … 101480 Jacks… AL 1 Four o… Publi… Subur… Degree-… Doctor… -#> 5 Southeast … 102368 Troy … AL 1 Four o… Publi… Town:… Degree-… Doctor… +#> 4 Southeast … 101879 Unive… AL 1 Four o… Publi… City:… Degree-… Doctor… +#> 5 Southeast … 106245 Unive… AR 5 Four o… Publi… City:… Degree-… Doctor… #> 6 Southeast … 106397 Unive… AR 5 Four o… Publi… City:… Degree-… Doctor… -#> 7 Southeast … 106467 Arkan… AR 5 Four o… Publi… Town:… Degree-… Doctor… -#> 8 Southeast … 132693 Easte… FL 12 Four o… Publi… City:… Degree-… Bachel… -#> 9 Southeast … 132851 Colle… FL 12 Four o… Publi… City:… Degree-… Bachel… -#> 10 Southeast … 132903 Unive… FL 12 Four o… Publi… Subur… Degree-… Doctor… -#> # ℹ 464 more rows +#> 7 Southeast … 106704 Unive… AR 5 Four o… Publi… City:… Degree-… Doctor… +#> 8 Southeast … 132709 Browa… FL 12 Four o… Publi… City:… Degree-… Bachel… +#> 9 Southeast … 132903 Unive… FL 12 Four o… Publi… Subur… Degree-… Doctor… +#> 10 Southeast … 133508 Flori… FL 12 Four o… Publi… Subur… Degree-… Bachel… +#> # ℹ 463 more rows #> # ℹ 9 more variables: ENRTOT , EFUG , EFUG1ST , EFUGFT , #> # EFGRAD , EFGRADFT , SamplingWeight , NumberHits , #> # ExpectedHits @@ -471,6 +477,10 @@ sum(ipeds_pps$NumberHits) We’d love your help to make SampleSelectR better! Here’s the workflow we use: +- One-time setup: after cloning, run + `git config core.hooksPath .githooks` to enable the repo’s git hooks + (e.g., the check that keeps README.md in sync with README.Rmd). + - Start from the dev branch - Always update your local copy first (git pull origin dev). diff --git a/cran-comments.md b/cran-comments.md new file mode 100644 index 0000000..f36f775 --- /dev/null +++ b/cran-comments.md @@ -0,0 +1,13 @@ +## R CMD check results + +0 errors | 0 warnings | 1 note + +* This is a new release, so R CMD check reports the expected "New submission" NOTE. + +## Method References + +References for the sampling methods are given in the Description field: Kalton (1983) for systematic sampling and Chromy (1979) for sequential PPS sampling. + +The Chromy (1979) reference is a 1979 American Statistical Association proceedings paper and has no DOI. Its URL uses http rather than https because www.asasrms.org does not present a valid TLS certificate; the http URL resolves without redirect. + +There are no published references describing the specific allocation adjustment/rounding algorithms implemented in this package. diff --git a/data-raw/IPEDS_2023/flags2023.xlsx b/data-raw/IPEDS_2023/flags2023.xlsx deleted file mode 100644 index a72557f..0000000 Binary files a/data-raw/IPEDS_2023/flags2023.xlsx and /dev/null differ diff --git a/man/SampleSelectR-package.Rd b/man/SampleSelectR-package.Rd index 38c2449..215b2fc 100644 --- a/man/SampleSelectR-package.Rd +++ b/man/SampleSelectR-package.Rd @@ -6,7 +6,7 @@ \alias{SampleSelectR-package} \title{SampleSelectR: Randomly Select Samples for Various Probability-Based Methods} \description{ -Randomly select samples with SRS, systematic, and various PPS methods. Also includes functionality to select within strata and allocate sample sizes. +Randomly select samples using simple random sampling (SRS), systematic sampling, and various probability proportional to size (PPS) methods, including systematic PPS and sequential PPS (i.e., Chromy's method). Also includes functionality to allocate sample sizes across strata using proportional, power, Neyman, and optimal allocation methods, and to select samples within strata. Designed to make survey sample design and selection reproducible, efficient, and transparent for survey statisticians and researchers. Sampling methods follow Kalton (1983) \doi{10.4135/9781412984683} and Chromy (1979) \url{http://www.asasrms.org/Proceedings/papers/1979_081.pdf}. } \seealso{ Useful links: @@ -22,6 +22,7 @@ Useful links: Authors: \itemize{ + \item Stephanie Zimmer \email{sazimmer@rti.org} \item John David Bunker, Jr. \item Thomas Burkett \item Philip Lee @@ -30,7 +31,7 @@ Authors: Other contributors: \itemize{ - \item RTI International [funder] + \item RTI International [copyright holder, funder] } } diff --git a/man/Sampling_Output.Rd b/man/Sampling_Output.Rd deleted file mode 100644 index be7c5cf..0000000 --- a/man/Sampling_Output.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/util.R -\name{Sampling_Output} -\alias{Sampling_Output} -\title{Output sampling summary to the console -Displays sample size, frame size, and optionally the sampling interval and random start.} -\usage{ -Sampling_Output(n, N, k = NULL, r = NULL, curstrat = NULL) -} -\arguments{ -\item{n}{Sample size.} - -\item{N}{Frame size.} - -\item{k}{Optional sampling interval.} - -\item{r}{Optional random start.} - -\item{curstrat}{Optional stratum label.} -} -\value{ -Prints output to the console. Invisibly returns NULL -} -\description{ -Output sampling summary to the console -Displays sample size, frame size, and optionally the sampling interval and random start. -} -\keyword{internal} diff --git a/man/allocate.Rd b/man/allocate.Rd index 036aa3f..6ceb64b 100644 --- a/man/allocate.Rd +++ b/man/allocate.Rd @@ -48,7 +48,7 @@ required for the power allocation only, and \code{NULL} otherwise.} \item the raw allocations before accounting for N.h, lbound, and n.samp if needed [\code{"raw"}], \item the continuous version after accounting for the above [\code{"adjusted"}], and/or \item the rounded version of the above [\code{"rounded"}] -} \cr +} Default is to only return the final rounded version [\code{"rounded"}]. \cr If one version is requested, the result will be a numeric vector. Otherwise, the result will be a named list matching the requested outputs.} } diff --git a/man/check_frame_type.Rd b/man/check_frame_type.Rd deleted file mode 100644 index 07747c6..0000000 --- a/man/check_frame_type.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/util.R -\name{check_frame_type} -\alias{check_frame_type} -\title{Check if the frame is a valid data structure} -\usage{ -check_frame_type(frame) -} -\arguments{ -\item{frame}{An object to be validated as a sampling frame.} -} -\value{ -Stops execution if validation fails. Invisibly returns TRUE. -} -\description{ -Ensures that the input frame is a data.frame, data.table, or tibble. -} -\keyword{internal} diff --git a/man/check_n.Rd b/man/check_n.Rd deleted file mode 100644 index a3353da..0000000 --- a/man/check_n.Rd +++ /dev/null @@ -1,24 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/util.R -\name{check_n} -\alias{check_n} -\title{Validate the sample size \code{n}} -\usage{ -check_n(n, frame, curstrat, n_le_N = FALSE) -} -\arguments{ -\item{n}{Desired sample size.} - -\item{frame}{Data frame or data table of the sampling frame.} - -\item{curstrat}{Optional character vector indicating the stratum.} - -\item{n_le_N}{Logical. Should \code{n} be forced to be less than or equal to \code{N}?} -} -\value{ -Stops execution if validation fails or outputs a message if \code{n == N}. Invisibly returns TRUE. -} -\description{ -Performs a set of checks on the sample size, including numeric type, bounds, and optional strata. -} -\keyword{internal} diff --git a/man/check_outall.Rd b/man/check_outall.Rd deleted file mode 100644 index 723a880..0000000 --- a/man/check_outall.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/util.R -\name{check_outall} -\alias{check_outall} -\title{Validate the 'outall' argument} -\usage{ -check_outall(outall) -} -\arguments{ -\item{outall}{A logical value indicating whether to return the full frame or only selected rows.} -} -\value{ -Stops execution if validation fails. Invisibly returns TRUE. -} -\description{ -Checks that the outall argument is a single logical value. -} -\keyword{internal} diff --git a/man/check_string_mos.Rd b/man/check_string_mos.Rd deleted file mode 100644 index 35e1359..0000000 --- a/man/check_string_mos.Rd +++ /dev/null @@ -1,20 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/util.R -\name{check_string_mos} -\alias{check_string_mos} -\title{Validate the measure of size (MOS) variable} -\usage{ -check_string_mos(mos, frame) -} -\arguments{ -\item{mos}{A string or symbol representing the column name of the measure of size.} - -\item{frame}{The sampling frame as a data.frame or similar object.} -} -\value{ -Stops execution if validation fails. Invisibly returns TRUE. -} -\description{ -Ensures that the MOS variable exists in the frame, is numeric, and contains no missing or negative values. -} -\keyword{internal} diff --git a/man/chromy_inner.Rd b/man/chromy_inner.Rd deleted file mode 100644 index 9b9bf8d..0000000 --- a/man/chromy_inner.Rd +++ /dev/null @@ -1,24 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/chromy_pps.R -\name{chromy_inner} -\alias{chromy_inner} -\title{Select a sequential PPS sample given expected number of hits} -\usage{ -chromy_inner(exphits) -} -\arguments{ -\item{exphits}{A vector of non-negative values} -} -\value{ -Returns a vector the same length of exphits with the number of random hits for each unit -} -\description{ -Select a sequential PPS sample given expected number of hits -} -\references{ -Chromy, J. R. (1979). “Sequential Sample Selection Methods.” -In \emph{Proceedings of the Survey Research Methods Section}, 401–406. -Washington, DC: American Statistical Association. -\url{http://www.asasrms.org/Proceedings/papers/1979_081.pdf} -} -\keyword{internal} diff --git a/man/create_group_variable.Rd b/man/create_group_variable.Rd deleted file mode 100644 index bc476a1..0000000 --- a/man/create_group_variable.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/create_group_variable.R -\name{create_group_variable} -\alias{create_group_variable} -\title{Create grouping variable} -\usage{ -create_group_variable(.data, groupvars, groupid) -} -\arguments{ -\item{.data}{A data frame, tibble, or data.table. No default.} - -\item{groupvars}{A vector of character variables which are the names of the columns to sort on. No default.} - -\item{groupid}{ID grouping variable name. No default.} -} -\value{ -A copy of the input data with the addition of the grouping ID variable -} -\description{ -Given a data frame and a vector of variables, creates a new variable that assigns a unique ID to each group of rows that have the same values -for the given variables. The function will return the data frame with the new id variable added. -} -\keyword{internal} diff --git a/man/figures/README-pressure-1.png b/man/figures/README-pressure-1.png deleted file mode 100644 index c092055..0000000 Binary files a/man/figures/README-pressure-1.png and /dev/null differ diff --git a/man/serp_sort.Rd b/man/serp_sort.Rd index 72f777c..78273f7 100644 --- a/man/serp_sort.Rd +++ b/man/serp_sort.Rd @@ -24,3 +24,13 @@ A copy of .data that is hierarchically sorted and, if specified, includes the so \description{ Sorts the rows in a given data frame in a hierarchical fashion given a list of variables (...) } +\examples{ +# Sort counties by Region, then Division, in a serpentine pattern +county_2023 |> + serp_sort("Region", "Division") + +# Keep the intermediate sort-group columns (sortSerp1, sortSerp2) +county_2023 |> + serp_sort("Region", "Division", sortID = TRUE) + +}