Add Claude skills tooling, prepare for CRAN, and clean up repo

.Rbuildignore

@@ -2,10 +2,12 @@
 ^\.Rproj\.user$
 ^README\.Rmd$
 ^\.github$
+^\.githooks$
 ^LICENSE\.md$
 ^data-raw$
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
 ^\.positai$
 ^\.claude$
+^cran-comments\.md$

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "r-lib@posit-dev-skills": true
+  }
+}

.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

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) <doi:10.4135/9781412984683> and Chromy
+    (1979) <http://www.asasrms.org/Proceedings/papers/1979_081.pdf>.
 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

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)

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.

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.

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

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) {

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)

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).