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 )

validate_no_logical( data_types, stop_on_error )

validate_field_names( field_names, stop_on_error = FALSE )

Arguments

data_types

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

stop_on_error

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

d

The base::data.frame() or tibble::tibble() containing the dataset used to update 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.

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

  • 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_]*$.)

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                                     sugge…¹
#>   <chr>                <int> <chr>                                       <chr>  
#> 1 flag_logical             2 The REDCap API does not automatically conv… Conver…
#> 2 flag_Uppercase           3 A REDCap project does not allow field name… Change…
#> # … with abbreviated variable name ¹​suggestion