Inspect a dataset to anticipate problems before writing to a REDCap project

Source: R/validate.R

This set of functions inspect a data frame to anticipate problems before writing with REDCap's API.

validate_for_write( d, convert_logical_to_integer )

validate_data_frame_inherits( d )

validate_no_logical( data_types, stop_on_error )

validate_field_names( field_names, stop_on_error = FALSE )

validate_repeat_instance( d, stop_on_error )

Arguments

d

The base::data.frame() or tibble::tibble() containing the dataset used to update the REDCap project.

data_types

The data types of the data frame corresponding to the REDCap project.

field_names

The names of the fields/variables in the REDCap project. Each field is an individual element in the character vector.

stop_on_error

If TRUE, an error is thrown for violations. Otherwise, a dataset summarizing the problems is returned.

convert_logical_to_integer

This mimics the convert_logical_to_integer parameter in redcap_write() when checking for potential importing problems. Defaults to FALSE.

Value

A tibble::tibble(), where each potential violation is a row. The two columns are:

  • field_name: The name of the field/column/variable that might cause problems during the upload.

  • field_index: The position of the field. (For example, a value of '1' indicates the first column, while a '3' indicates the third column.)

  • concern: A description of the problem potentially caused by the field.

  • suggestion: A potential solution to the concern.

Details

All functions listed in the Usage section above inspect a specific aspect of the dataset. The validate_for_write() function executes all these individual validation checks. It allows the client to check everything with one call.

Currently it verifies that the dataset

  • inherits from data.table::data.table().

  • does not contain logical values (because REDCap typically wants 0/1 values instead of FALSE/TRUE).

  • starts with a lowercase letter, and subsequent optional characters are a sequence of (a) lowercase letters, (b) digits 0-9, and/or (c) underscores. (The exact regex is ^[a-z][0-9a-z_]*$.)

  • has an integer for redcap_repeat_instance, if the column is present.

If you encounter additional types of problems when attempting to write to REDCap, please tell us by creating a new issue, and we'll incorporate a new validation check into this function.

References

The official documentation can be found on the 'API Help Page' and 'API Examples' pages on the REDCap wiki (i.e., https://community.projectredcap.org/articles/456/api-documentation.html and https://community.projectredcap.org/articles/462/api-examples.html). If you do not have an account for the wiki, please ask your campus REDCap administrator to send you the static material.

Author

Will Beasley

Examples

d <- data.frame(
  record_id      = 1:4,
  flag_logical   = c(TRUE, TRUE, FALSE, TRUE),
  flag_Uppercase = c(4, 6, 8, 2)
)
REDCapR::validate_for_write(d = d)
#> # A tibble: 2 × 4
#>   field_name     field_index concern                                  suggestion
#>   <chr>                <int> <chr>                                    <chr>     
#> 1 flag_Uppercase           3 A REDCap project does not allow field n… Change th…
#> 2 flag_logical             2 The REDCap API does not automatically c… Convert t…

REDCapR::validate_for_write(d = d, convert_logical_to_integer = TRUE)
#> # A tibble: 1 × 4
#>   field_name     field_index concern                                  suggestion
#>   <chr>                <int> <chr>                                    <chr>     
#> 1 flag_Uppercase           3 A REDCap project does not allow field n… Change th…

# If `d` is not a data.frame, the remaining validation checks are skipped:
# REDCapR::validate_for_write(as.matrix(mtcars))
# REDCapR::validate_for_write(c(mtcars, iris))