document the pseudofields

ref #477

R/redcap-read-oneshot.R

@@ -117,6 +117,32 @@
 #' API request is **not** in a data access group. If the user is in a group,
 #' then this flag will revert to its default value*.
 #'
+#' The REDCap project may contain "pseudofields", depending on its structure.
+#' Pseudofields are exported for certain project structures, but are not
+#' defined by users and do not appear in the codebook.
+#' If a recognized pseudofield is passed to the `fields` api parameter,
+#' it is suppressed by [REDCapR::redcap_read()] and [REDCapR::redcap_read_oneshot()]
+#' so the server doesn't throw an error.
+#' Requesting a pseudofield is discouraged, so a message is returned to the user.
+#'
+#' Pseudofields include:
+#' * `redcap_event_name`: for longitudinal projects or multi-arm projects.
+#' * `redcap_repeat_instrument`:  for projects with repeating instruments.
+#' * `redcap_repeat_instance`:   for projects with repeating instruments.
+#' * `redcap_data_access_group`: for projects with DAGs when the
+#'   `export_data_access_groups` api parameter is TRUE.
+#' * `redcap_survey_identifier`:  for projects with surveys when the
+#'   `export_survey_fields` api parameter is TRUE.
+#' * *instrument_name*`_timestamp`: for projects with surveys.
+#'   For example, an instrument called "demographics" will have a pseudofield
+#'   named `demographics_timestamp`.
+#'   REDCapR does not suppress requests for timestamps, so the server will
+#'   throw an error like
+#'
+#'   ```
+#'   ERROR: The following values in the parameter fields are not valid: 'demographics_timestamp'
+#'   ```
+#'
 #' @author
 #' Will Beasley
 #'
@@ -229,7 +255,14 @@ redcap_read_oneshot <- function(
 
   validate_field_names(fields, stop_on_error = TRUE)
 
-  pseudofields <- c("redcap_event_name", "redcap_repeat_instrument", "redcap_repeat_instance")
+  pseudofields <- c(
+    "redcap_event_name",
+    "redcap_repeat_instrument",
+    "redcap_repeat_instance",
+    "redcap_survey_identifier",
+    "redcap_data_access_group"
+  )
+
   if (1L <= length(fields) && any(fields %in% pseudofields)) {
     fields  <- setdiff(fields, pseudofields) # Remove any that are requested.
     message(

R/redcap-read.R

@@ -156,6 +156,32 @@
 #' * select the desired user, and then select 'Edit User Privileges',
 #' * in the 'Data Exports' radio buttons, select 'Full Data Set'.
 #'
+#' The REDCap project may contain "pseudofields", depending on its structure.
+#' Pseudofields are exported for certain project structures, but are not
+#' defined by users and do not appear in the codebook.
+#' If a recognized pseudofield is passed to the `fields` api parameter,
+#' it is suppressed by [REDCapR::redcap_read()] and [REDCapR::redcap_read_oneshot()]
+#' so the server doesn't throw an error.
+#' Requesting a pseudofield is discouraged, so a message is returned to the user.
+#'
+#' Pseudofields include:
+#' * `redcap_event_name`: for longitudinal projects or multi-arm projects.
+#' * `redcap_repeat_instrument`:  for projects with repeating instruments.
+#' * `redcap_repeat_instance`:   for projects with repeating instruments.
+#' * `redcap_data_access_group`: for projects with DAGs when the
+#'   `export_data_access_groups` api parameter is TRUE.
+#' * `redcap_survey_identifier`:  for projects with surveys when the
+#'   `export_survey_fields` api parameter is TRUE.
+#' * *instrument_name*`_timestamp`: for projects with surveys.
+#'   For example, an instrument called "demographics" will have a pseudofield
+#'   named `demographics_timestamp`.
+#'   REDCapR does not suppress requests for timestamps, so the server will
+#'   throw an error like
+#'
+#'   ```
+#'   ERROR: The following values in the parameter fields are not valid: 'demographics_timestamp'
+#'   ```
+#'
 #' @author
 #' Will Beasley
 #'