This function uses REDCap's API to select and return data.
redcap_read_oneshot(
redcap_uri,
token,
records = NULL,
fields = NULL,
forms = NULL,
events = NULL,
raw_or_label = "raw",
raw_or_label_headers = "raw",
export_checkbox_label = FALSE,
export_survey_fields = FALSE,
export_data_access_groups = FALSE,
filter_logic = "",
datetime_range_begin = as.POSIXct(NA),
datetime_range_end = as.POSIXct(NA),
blank_for_gray_form_status = FALSE,
col_types = NULL,
guess_type = TRUE,
guess_max = 1000,
http_response_encoding = "UTF-8",
locale = readr::default_locale(),
verbose = TRUE,
config_options = NULL,
handle_httr = NULL
)
The uri/url of the REDCap server typically formatted as "https://server.org/apps/redcap/api/". Required.
The user-specific string that serves as the password for a project. Required.
An array, where each element corresponds to the ID of a desired record. Optional.
An array, where each element corresponds to a desired project field. Optional.
An array, where each element corresponds to a desired project form. Optional.
An array, where each element corresponds to a desired project event. Optional.
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'
.
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'
.
specifies the format of checkbox field values
specifically when exporting the data as labels. If raw_or_label
is
'label'
and export_checkbox_label
is TRUE, the values will be the text
displayed to the users. Otherwise, the values will be 0/1.
A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp'). The timestamp outputs reflect the survey's completion time (according to the time and timezone of the REDCap server.)
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.
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.
To return only records that have been created or modified after a given datetime, provide a POSIXct value. If not specified, REDCap will assume no begin time.
To return only records that have been created or modified before a given datetime, provide a POSIXct value. If not specified, REDCap will assume no end time.
A boolean value that specifies whether
or not to export blank values for instrument complete status fields that have
a gray status icon. All instrument complete status fields having a gray icon
can be exported either as a blank value or as "0" (Incomplete). Blank values
are recommended in a data export if the data will be re-imported into a
REDCap project. Default is FALSE
.
A readr::cols()
object passed internally to
readr::read_csv()
. Optional.
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. Ignored if col_types
is not null.
A positive base::numeric value
passed to readr::read_csv()
that
specifies the maximum number of records to use for guessing column types.
The encoding value passed to
httr::content()
. Defaults to 'UTF-8'.
a readr::locale()
object to specify preferences like
number, date, and time formats. This object is passed to
readr::read_csv()
. Defaults to readr::default_locale()
.
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.
A list of options passed to httr::POST()
.
See details at httr::httr_options()
. Optional.
The value passed to the handle
parameter of
httr::POST()
.
This is useful for only unconventional authentication approaches. It
should be NULL
for most institutions. Optional.
Currently, a list is returned with the following elements:
data
: A tibble::tibble()
of the desired records and columns.
success
: A boolean value indicating if the operation was apparently
successful.
status_code
: The
http status code
of the operation.
outcome_message
: A human readable string indicating the operation's
outcome.
records_collapsed
: The desired records IDs, collapsed into a single
string, separated by commas.
fields_collapsed
: The desired field names, collapsed into a single
string, separated by commas.
filter_logic
: The filter statement passed as an argument.
elapsed_seconds
: The duration of the function.
raw_text
: If an operation is NOT successful, the text returned by
REDCap. If an operation is successful, the raw_text
is returned as an
empty string to save RAM.
If no records are retrieved (such as no records meet the filter criteria), a zero-row tibble is returned. Currently the empty tibble has zero columns, but that may change in the future.
If you do not pass an export_data_access_groups
value, it will default
to FALSE
. The following is from the API help page for version 10.5.1:
This flag is only viable if the user whose token is being used to make the
API request is not in a data access group. If the user is in a group,
then this flag will revert to its default value.
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.
# \dontrun{
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
token <- "9A81268476645C4E5F03428B8AC3AA7B"
# Return all records and all variables.
ds <- REDCapR::redcap_read_oneshot(redcap_uri=uri, token=token)$data
#> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200.
# Return only records with IDs of 1 and 3
desired_records_v1 <- c(1, 3)
ds_some_rows_v1 <- REDCapR::redcap_read_oneshot(
redcap_uri = uri,
token = token,
records = desired_records_v1
)$data
#> 2 records and 25 columns were read from REDCap in 0.3 seconds. The http status code was 200.
# Return only the fields record_id, name_first, and age
desired_fields_v1 <- c("record_id", "name_first", "age")
ds_some_fields_v1 <- REDCapR::redcap_read_oneshot(
redcap_uri = uri,
token = token,
fields = desired_fields_v1
)$data
#> 5 records and 3 columns were read from REDCap in 0.2 seconds. The http status code was 200.
# Specify the column types.
col_types <- readr::cols(
record_id = readr::col_integer(),
race___1 = readr::col_logical(),
race___2 = readr::col_logical(),
race___3 = readr::col_logical(),
race___4 = readr::col_logical(),
race___5 = readr::col_logical(),
race___6 = readr::col_logical()
)
ds_col_types <- REDCapR::redcap_read_oneshot(
redcap_uri = uri,
token = token,
col_types = col_types
)$data
#> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200.
# }