validate {REDCapR}

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

Description

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

Usage

validate_for_write( d )

validate_no_logical( data_types, stop_on_error )

validate_field_names( field_names, stop_on_error = FALSE )

validate_field_names_collapsed( field_names_collapsed, stop_on_error = FALSE )

Arguments

data_types

The data types of the base::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() 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.

field_names_collapsed

The names of the fields/variables in the REDCap project. All fields are combined in a single vector element, separated by commas.

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.

Value

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

• field_name: The name of the base::data.frame() 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.

Author(s)

Will Beasley

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.

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)