R/validate.R
validate.Rd
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 )
The base::data.frame()
or tibble::tibble()
containing the dataset used to update
the REDCap project.
The data types of the data frame corresponding to the REDCap project.
The names of the fields/variables in the REDCap project. Each field is an individual element in the character vector.
If TRUE
, an error is thrown for violations.
Otherwise, a dataset summarizing the problems is returned.
This mimics the convert_logical_to_integer
parameter in
redcap_write()
when checking for potential importing problems.
Defaults to FALSE
.
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.
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.
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.
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))