Skip to content

Commit

Permalink
reorder parameters in documentation
Browse files Browse the repository at this point in the history 
ref #204
  • Loading branch information
@wibeasley
wibeasley committed May 27, 2018
1 parent a9fc40f commit d28b68c
Show file tree
Hide file tree
Showing 6 changed files with 135 additions and 64 deletions.
40 changes: 34 additions & 6 deletions R/redcap-read-oneshot-eav.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,20 @@
#' @param records_collapsed A single string, where the desired ID values are separated by commas. Optional.
#' @param fields An array, where each element corresponds a desired project field. Optional.
#' @param fields_collapsed A single string, where the desired field names are separated by commas. Optional.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
# forms
#' @param events An array, where each element corresponds a desired project event Optional.
#' @param events_collapsed A single string, where the desired event names are separated by commas. Optional.
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param raw_or_label A string (either `'raw'` or `'label'` that specifies whether to export the raw coded values or the labels for the options of multiple choice fields. Default is `'raw'`.
#' @param raw_or_label_headers A string (either `'raw'` or `'label'` that specifies for the CSV headers whether to export the variable/field names (raw) or the field labels (label). Default is `'raw'`.
# exportCheckboxLabel
# returnFormat
# export_survey_fields
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
#'
#' @param verbose A boolean value indicating if `message`s should be printed to the R console during the operation. The verbose output might contain sensitive information (*e.g.* PHI), so turn this off if the output might be visible somewhere public. Optional.
#' @param config_options A list of options to pass to `POST` method in the `httr` package. See the details below. Optional.
#'
#' @return Currently, a list is returned with the following elements,
#' * `data`: An R [base::data.frame()] of the desired records and columns.
#' * `success`: A boolean value indicating if the operation was apparently successful.
Expand Down Expand Up @@ -83,11 +89,18 @@ redcap_read_oneshot_eav <- function(
token,
records = NULL, records_collapsed = "",
fields = NULL, fields_collapsed = "",
# forms
events = NULL, events_collapsed = "",
export_data_access_groups = FALSE,
filter_logic = "",
raw_or_label = "raw",
raw_or_label_headers = "raw",
# exportCheckboxLabel
# returnFormat
# export_survey_fields
export_data_access_groups = FALSE,
filter_logic = "",

# guess_type
# guess_max
verbose = TRUE,
config_options = NULL
) {
Expand All @@ -97,10 +110,24 @@ redcap_read_oneshot_eav <- function(

checkmate::assert_character(redcap_uri , any.missing=F, len=1, pattern="^.{1,}$")
checkmate::assert_character(token , any.missing=F, len=1, pattern="^.{1,}$")
# records
# fields
# forms
# events
checkmate::assert_subset( raw_or_label , c("raw", "label"))
# raw_or_label_headers
# exportCheckboxLabel
# returnFormat
# export_survey_fields
checkmate::assert_logical( export_data_access_groups , any.missing=F, len=1)
checkmate::assert_character(filter_logic , any.missing=F, len=1, pattern="^.{0,}$")
checkmate::assert_subset( raw_or_label , c("raw", "label"))
#
# guess_type
# verbose
# config_options
# id_position

# TODO: convert this to checkmate::assert_subset
if( !(raw_or_label_headers %in% c("raw", "label")) )
stop("The optional parameter `raw_or_label_headers` must be either 'raw' or 'label'.")

Expand Down Expand Up @@ -168,7 +195,8 @@ redcap_read_oneshot_eav <- function(

if( success ) {

# This next line exists solely to avoid RCMD checks
# This next line exists solely to avoid R CMD checks
# TODO: remove this line and use .data$... inside dplyr
. <- record <- event_id <- value <- field_type <- field_name <- is_checkbox <- select_choices_or_calculations <- ids <- NULL

try (
Expand Down
58 changes: 39 additions & 19 deletions R/redcap-read-oneshot.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,22 @@
#' @param records_collapsed A single string, where the desired ID values are separated by commas. Optional.
#' @param fields An array, where each element corresponds a desired project field. Optional.
#' @param fields_collapsed A single string, where the desired field names are separated by commas. Optional.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
# forms
#' @param events An array, where each element corresponds a desired project event Optional.
#' @param events_collapsed A single string, where the desired event names are separated by commas. Optional.
#' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param raw_or_label A string (either `'raw'` or `'label'`) that specifies whether to export the raw coded values or the labels for the options of multiple choice fields. Default is `'raw'`.
#' @param raw_or_label_headers A string (either `'raw'` or `'label'` that specifies for the CSV headers whether to export the variable/field names (raw) or the field labels (label). Default is `'raw'`.
# exportCheckboxLabel
# returnFormat
#' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
#'
#' @param guess_type A boolean value indicating if all columns should be returned as character. If false, [readr::read_csv()] guesses the intended data type for each column.
#' @param guess_max A positive integer passed to [readr::read_csv()] that specifies the maximum number of records to use for guessing column types.
#' @param verbose A boolean value indicating if `message`s should be printed to the R console during the operation. The verbose output might contain sensitive information (*e.g.* PHI), so turn this off if the output might be visible somewhere public. Optional.
#' @param config_options A list of options to pass to `POST` method in the `httr` package. See the details below. Optional.
#'
#' @return Currently, a list is returned with the following elements,
#' * `data`: An R [base::data.frame()] of the desired records and columns.
#' * `success`: A boolean value indicating if the operation was apparently successful.
Expand Down Expand Up @@ -71,33 +76,49 @@
redcap_read_oneshot <- function(
redcap_uri,
token,
records = NULL, records_collapsed = "",
fields = NULL, fields_collapsed = "",
events = NULL, events_collapsed = "",
export_survey_fields = FALSE,
export_data_access_groups = FALSE,
filter_logic = "",
raw_or_label = "raw",
raw_or_label_headers = "raw",
guess_type = TRUE,
guess_max = 1000L,
verbose = TRUE,
config_options = NULL
records = NULL, records_collapsed = "",
fields = NULL, fields_collapsed = "",
# forms
events = NULL, events_collapsed = "",
raw_or_label = "raw",
raw_or_label_headers = "raw",
# exportCheckboxLabel
# returnFormat
export_survey_fields = FALSE,
export_data_access_groups = FALSE,
filter_logic = "",

guess_type = TRUE,
guess_max = 1000L,
verbose = TRUE,
config_options = NULL
) {
#TODO: NULL verbose parameter pulls from getOption("verbose")

start_time <- Sys.time()

checkmate::assert_character(redcap_uri , any.missing=F, len=1, pattern="^.{1,}$")
checkmate::assert_character(token , any.missing=F, len=1, pattern="^.{1,}$")
# records
# fields
# forms
# events
checkmate::assert_subset( raw_or_label , c("raw", "label"))
# raw_or_label_headers
# exportCheckboxLabel
# returnFormat
checkmate::assert_logical(export_survey_fields, any.missing=F, len=1)
checkmate::assert_logical( export_data_access_groups , any.missing=F, len=1)
checkmate::assert_character(filter_logic , any.missing=F, len=1, pattern="^.{0,}$")
checkmate::assert_subset( raw_or_label , c("raw", "label"))
#
checkmate::assert_logical( guess_type , any.missing=F, len=1)
checkmate::assert_integerish(guess_max , any.missing=F, len=1, lower=1)
# verbose
# config_options

# TODO: convert this to checkmate::assert_subset
if( !(raw_or_label_headers %in% c("raw", "label")) )
stop("The optional parameter `raw_or_label_headers` must be either 'raw' or 'label'.")
stop("The optional parameter `raw_or_label_headers` must be either 'raw' or 'label'.")

token <- sanitize_token(token)
validate_field_names(fields)
Expand All @@ -110,7 +131,6 @@ redcap_read_oneshot <- function(
events_collapsed <- ifelse(is.null(events), "", paste0(events, collapse=",")) #This is an empty string if `events` is NULL.
if( all(nchar(filter_logic)==0) )
filter_logic <- ifelse(is.null(filter_logic), "", filter_logic) #This is an empty string if `filter_logic` is NULL.
checkmate::assert_logical(export_survey_fields, any.missing=F, len=1)

if( any(grepl("[A-Z]", fields_collapsed)) )
warning("The fields passed to REDCap appear to have at least uppercase letter. REDCap variable names are snake case.")
Expand Down Expand Up @@ -148,7 +168,7 @@ redcap_read_oneshot <- function(

raw_text <- httr::content(result, "text")
raw_text <- gsub("\r\n", "\n", raw_text)
# browser()

elapsed_seconds <- as.numeric(difftime(Sys.time(), start_time, units="secs"))

# raw_text <- "The hostname (redcap-db.hsc.net.ou.edu) / username (redcapsql) / password (XXXXXX) combination could not connect to the MySQL server. \r\n\t\tPlease check their values."
Expand Down
59 changes: 41 additions & 18 deletions R/redcap-read.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,17 @@
#' @param records_collapsed A single string, where the desired ID values are separated by commas. Optional.
#' @param fields An array, where each element corresponds a desired project field. Optional.
#' @param fields_collapsed A single string, where the desired field names are separated by commas. Optional.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
# forms
#' @param events An array, where each element corresponds a desired project event Optional.
#' @param events_collapsed A single string, where the desired event names are separated by commas. Optional.
#' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param raw_or_label A string (either 'raw` or 'label' that specifies whether to export the raw coded values or the labels for the options of multiple choice fields. Default is `'raw'`.
#' @param raw_or_label_headers A string (either `'raw'` or `'label'` that specifies for the CSV headers whether to export the variable/field names (raw) or the field labels (label). Default is `'raw'`.
# exportCheckboxLabel
# returnFormat
#' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
#' @param export_data_access_groups A boolean value that specifies whether or not to export the `redcap_data_access_group` field when data access groups are utilized in the project. Default is `FALSE`. See the details below.
#' @param filter_logic String of logic text (e.g., `[gender] = 'male'`) for filtering the data to be returned by this API method, in which the API will only return the records (or record-events, if a longitudinal project) where the logic evaluates as TRUE. An blank/empty string returns all records.
#'
#' @param guess_type A boolean value indicating if all columns should be returned as character. If true, [readr::read_csv()] guesses the intended data type for each column.
#' @param verbose A boolean value indicating if `message`s should be printed to the R console during the operation. The verbose output might contain sensitive information (*e.g.* PHI), so turn this off if the output might be visible somewhere public. Optional.
#' @param config_options A list of options to pass to `POST` method in the `httr` package. See the details in `redcap_read_oneshot()` Optional.
Expand Down Expand Up @@ -68,28 +72,47 @@
#'

redcap_read <- function(
batch_size = 100L,
interbatch_delay = 0.5,
continue_on_error = FALSE,
batch_size = 100L,
interbatch_delay = 0.5,
continue_on_error = FALSE,
redcap_uri,
token,
records = NULL, records_collapsed = "",
fields = NULL, fields_collapsed = "",
events = NULL, events_collapsed = "",
export_survey_fields = FALSE,
export_data_access_groups = FALSE,
filter_logic = "",
raw_or_label = "raw",
raw_or_label_headers = "raw",
guess_type = TRUE,
verbose = TRUE,
config_options = NULL,
id_position = 1L
records = NULL, records_collapsed = "",
fields = NULL, fields_collapsed = "",
# forms
events = NULL, events_collapsed = "",
raw_or_label = "raw",
raw_or_label_headers = "raw",
# exportCheckboxLabel
# returnFormat
export_survey_fields = FALSE,
export_data_access_groups = FALSE,
filter_logic = "",

guess_type = TRUE,
verbose = TRUE,
config_options = NULL,
id_position = 1L
) {

checkmate::assert_character(redcap_uri, any.missing=F, len=1, pattern="^.{1,}$")
checkmate::assert_character(token, any.missing=F, len=1, pattern="^.{1,}$")
# records
# fields
# forms
# events
checkmate::assert_subset( raw_or_label , c("raw", "label"))
# raw_or_label_headers
# exportCheckboxLabel
# returnFormat
# export_survey_fields
checkmate::assert_logical( export_data_access_groups , any.missing=F, len=1)
checkmate::assert_character(filter_logic , any.missing=F, len=1, pattern="^.{0,}$")
#
checkmate::assert_logical( guess_type , any.missing=F, len=1)
# verbose
# config_options
# id_position

token <- sanitize_token(token)
validate_field_names(fields)
Expand Down
14 changes: 7 additions & 7 deletions man/redcap_read.Rd
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit d28b68c

Please sign in to comment.