mode = "NCHS"

NAMESPACE

@@ -5,6 +5,7 @@ S3method(print,surveytable_table)
 export(codebook)
 export(set_count_1k)
 export(set_count_int)
+export(set_mode)
 export(set_output)
 export(set_survey)
 export(show_options)

NEWS.md

@@ -1,6 +1,7 @@
 # surveytable (development version)
 
 * `rccsu2018`
+* `set_mode()`
 
 # surveytable 0.9.4
 

R/set_mode.R

@@ -0,0 +1,31 @@
+#' @rdname set_survey
+#' @order 2
+#' @export
+set_mode = function(mode = "default") {
+  opts.table = c("nchs", "default", "general")
+  idx = mode %>% tolower %>% pmatch(opts.table)
+  assert_that(noNA(idx), msg = paste("Unknown mode:", mode))
+  opts = opts.table[idx]
+
+  if (opts == "nchs") {
+    message("* Mode: NCHS.")
+    options(
+      surveytable.tx_count = ".tx_count_1k"
+      , surveytable.names_count = c("n", "Number (000)", "SE (000)", "LL (000)", "UL (000)")
+      , surveytable.find_lpe = TRUE
+      , surveytable.adjust_svyciprop = TRUE
+    )
+  } else if (opts %in% c("general", "default")) {
+    message("* Mode: General.")
+    options(
+      surveytable.tx_count = ".tx_count_int"
+      , surveytable.names_count = c("n", "Number", "SE", "LL", "UL")
+      , surveytable.find_lpe = FALSE
+      , surveytable.adjust_svyciprop = FALSE
+    )
+  } else {
+    stop("!!")
+  }
+
+  invisible(NULL)
+}

R/set_survey.R

@@ -1,67 +1,47 @@
 #' Specify the survey to analyze
 #'
-#' You need to specify a survey before the other functions, such as [tab()],
-#' will work.
-#'
-#' `opts`:
-#' * `"nchs"`:
-#'    * Round counts to the nearest 1,000 -- see [set_count_1k()].
-#'    * Identify low-precision estimates (`surveytable.find_lpe` option is `TRUE`).
-#'    * Percentage CI's: adjust Korn-Graubard CI's for the number of degrees of freedom, matching the SUDAAN calculation (`surveytable.adjust_svyciprop` option is `TRUE`).
-#' * `"general":`
-#'    * Round counts to the nearest integer -- see [set_count_int()].
-#'    * Do not look for low-precision estimates (`surveytable.find_lpe` option is `FALSE`).
-#'    * Percentage CI's: use standard Korn-Graubard CI's (`surveytable.adjust_svyciprop` option is `FALSE`).
+#' You must specify a survey before the other functions, such as [tab()],
+#' will work. To convert a `data.frame` to a survey object, see [survey::svydesign()]
+#' or [survey::svrepdesign()].
 #'
 #' Optionally, the survey can have an attribute called `label`, which is the
-#' long name of the survey.
+#' long name of the survey. Optionally, each variable in the survey can have an
+#' attribute called `label`, which is the variable's long name.
 #'
-#' Optionally, each variable in the survey can have an attribute called `label`,
-#' which is the variable's long name.
+#' If you are not sure what the `mode` should be, leave it as `"default"`. Here is
+#' what `mode` does:
 #'
-#' @param design either a survey object (`survey.design` or `svyrep.design`) or a
-#' `data.frame` for an unweighted survey.
-#' @param opts set certain options. See below.
+#' * `"general"` or `"default"`:
+#'    * Round counts to the nearest integer -- see [set_count_int()].
+#'    * Do not look for low-precision estimates.
+#'    * Percentage CI's: use standard Korn-Graubard CI's.
+#'
+#' * `"nchs"`:
+#'    * Round counts to the nearest 1,000 -- see [set_count_1k()].
+#'    * Identify low-precision estimates.
+#'    * Percentage CI's: adjust Korn-Graubard CI's for the number of degrees of freedom, matching the SUDAAN calculation.
+#'
+#' @param design either a survey object (created with [survey::svydesign()] or
+#' [survey::svrepdesign()]); or, for an unweighted survey, a `data.frame`.
+#' @param mode set certain options. See below.
 #' @param csv name of a CSV file
 #'
 #' @family options
-#' @return Info about the survey.
+#' @return `set_survey`: info about the survey. `set_mode`: nothing.
+#' @order 1
 #' @export
 #'
 #' @examples
 #' set_survey(namcs2019sv)
-set_survey = function(design, opts = "NCHS"
-  , csv = getOption("surveytable.csv")) {
-
-  ##
-  opts.table = c("nchs", "general")
-  idx = opts %>% tolower %>% pmatch(opts.table)
-  assert_that(noNA(idx), msg = paste("Unknown value of opts:", opts))
-  opts = opts.table[idx]
-
-  if (opts == "nchs") {
-    options(
-      surveytable.tx_count = ".tx_count_1k"
-      , surveytable.names_count = c("n", "Number (000)", "SE (000)", "LL (000)", "UL (000)")
-      , surveytable.find_lpe = TRUE
-      , surveytable.adjust_svyciprop = TRUE
-    )
-  } else if (opts == "general") {
-    options(
-      surveytable.tx_count = ".tx_count_int"
-      , surveytable.names_count = c("n", "Number", "SE", "LL", "UL")
-      , surveytable.find_lpe = FALSE
-      , surveytable.adjust_svyciprop = FALSE
-    )
-  } else {
-    stop("!!")
-  }
-
+#' set_mode("general")
+set_survey = function(design, mode = "default", csv = getOption("surveytable.csv")) {
   # In case there's an error below and we don't set a new survey,
   # don't retain the previous survey either.
   env$survey = NULL
   options(surveytable.survey_label = "")
 
+  set_mode(mode = mode)
+
   if (is.string(design)) {
     label_default = design
     design %<>% get0

R/surveytable.R

@@ -19,9 +19,20 @@ NULL
 #'
 #' ## Low-precision estimates.
 #'
+#' Optionally, all of the tabulation functions can identify low-precision estimates.
+#' To turn on this functionality, either set the `surveytable.find_lpe` option to `TRUE`,
+#' or call [set_survey()] or [set_mode()] with the argument `mode = "NCHS"`.
+#'
+#' By default, low-precision estimates are identified using National Center for
+#' Health Statistics (NCHS) algorithms. However, this can be changed, as described
+#' below.
+#'
+#' Here is a description of the options related to the identification of low-precision
+#' estimates.
+#'
 #' * `surveytable.find_lpe`: should the tabulation functions look for low-precision
-#' estimates? You can change this directly with `options()` or with the `opts` argument
-#' to `set_survey()`.
+#' estimates? You can change this directly with `options()` or with the `mode` argument
+#' to [set_survey()] or [set_mode()].
 #' * `surveytable.lpe_n`, `surveytable.lpe_counts`, `surveytable.lpe_percents`: names
 #' of 3 functions.
 #'
@@ -61,7 +72,6 @@ NULL
 #' level, two different things were found, indicated by short codes `A1` and `A2`. In
 #' this case, `has.flag = c("A1", "A2")`, `descriptions = c(A1 = "A1: something", A2 = "A2: something else")`.
 #'
-#'
 #' @name surveytable-options
 #' @family options
 "_PACKAGE"

R/svyciprop_adjusted.R

@@ -1,13 +1,14 @@
 #' Confidence intervals for proportions, adjusted for degrees of freedom
 #'
-#' A version of `survey::svyciprop()` that adjusts for the degrees of freedom when `method = "beta"`.
+#' A version of `survey::svyciprop()` that adjusts for the degrees of freedom
+#' when `method = "beta"`.
 #'
 #' Written by Makram Talih in 2019.
 #'
 #' `df_method`: for `"default"`, `df = degf(design)`; for `"NHIS"`, `df = nrow(design) - 1`.
 #'
-#' To use this function in tabulations, call [set_survey()] with the `opts = "NCHS"` argument,
-#' or type: `options(surveytable.adjust_svyciprop = TRUE)`.
+#' To use this function in tabulations, call [set_survey()] or [set_mode()] with the
+#' `mode = "NCHS"` argument, or type: `options(surveytable.adjust_svyciprop = TRUE)`.
 #'
 #' @param formula see `survey::svyciprop()`.
 #' @param design see `survey::svyciprop()`.
@@ -16,13 +17,14 @@
 #' @param df_method how `df` should be calculated: `"default"` or `"NHIS"`.
 #' @param ... see `survey::svyciprop()`.
 #'
-#'
 #' @return The point estimate of the proportion, with the confidence interval as an attribute.
 #' @export
 #'
 #' @examples
-#' set_survey(namcs2019sv, opts = "NCHS")
+#' set_survey(namcs2019sv)
+#' set_mode("NCHS")
 #' tab("AGER")
+#' set_mode("general")
 svyciprop_adjusted = function(formula
                     , design
                     , method = c("logit", "likelihood", "asin", "beta"

R/zzz.R

@@ -1,21 +1,21 @@
-.onAttach = function(libname, pkgname) {
-  txt = paste0(
-    "Before you can tabulate estimates, you have to specify which survey object"
-    , " you would like to analyze. You can do this in a couple of ways:"
-    , "\n\na) This package comes with a survey object for use in examples called"
-    , " 'namcs2019sv'. This object has selected variables from the NAMCS 2019 PUF survey."
-    , " To use this survey object:"
-    , "\n\nset_survey(namcs2019sv)"
-    , "\n\nb) If you have a survey object stored in a file:"
-    , "\n\nmysurvey = readRDS('file_name.rds')"
-    , "\n\nset_survey(mysurvey)"
-    , "\n\nFor info on how to create a survey object from a data frame, see"
-    , " ?survey::svydesign or ?survey::svrepdesign ."
-  )
-
-  txt = paste(strwrap(txt), collapse = "\n")
-  packageStartupMessage(txt)
-}
+# .onAttach = function(libname, pkgname) {
+#   txt = paste0(
+#     "Before you can tabulate estimates, you have to specify which survey object"
+#     , " you would like to analyze. You can do this in a couple of ways:"
+#     , "\n\na) This package comes with a survey object for use in examples called"
+#     , " 'namcs2019sv'. This object has selected variables from the NAMCS 2019 PUF survey."
+#     , " To use this survey object:"
+#     , "\n\nset_survey(namcs2019sv)"
+#     , "\n\nb) If you have a survey object stored in a file:"
+#     , "\n\nmysurvey = readRDS('file_name.rds')"
+#     , "\n\nset_survey(mysurvey)"
+#     , "\n\nFor info on how to create a survey object from a data frame, see"
+#     , " ?survey::svydesign or ?survey::svrepdesign ."
+#   )
+#
+#   txt = paste(strwrap(txt), collapse = "\n")
+#   packageStartupMessage(txt)
+# }
 
 env = new.env()
 

README.Rmd

@@ -35,7 +35,7 @@ knitr::opts_chunk$set(
   * modify survey variables, and 
   * save the output. 
 
-* All of the tabulation functions identify low-precision estimates using National Center for Health Statistics (NCHS) algorithms. 
+* Optionally, all of the tabulation functions can identify low-precision estimates using the National Center for Health Statistics (NCHS) algorithms (or other algorithms). 
 * If the `surveytable` code is called from an R Markdown notebook or a Quarto document, it automatically generates HTML or LaTeX tables, as appropriate. 
 * The package reduces the number of commands that users need to execute, which is especially helpful for users new to R or to programming.
 
@@ -89,7 +89,7 @@ The table shows:
   * Estimated count with its SE and 95% CI
   * Estimated percentage with its SE and 95% CI
 * Sample size
-* Whether any low-precision estimates were found
+* Optionally, the table can show whether any low-precision estimates were found
 
 <!-- CDC standard text -->
 ## Public Domain Standard Notice