This vignette covers the the basic functions exposed by the httr and curl packages which allow you to interact with REDCap through its API.
The function redcap_read_oneshot uses the httr package to call the REDCap API.
There is some information that is specific to the REDCap project, as opposed to an individual operation. This includes the (1) uri of the server, and the (2) token for the user’s project.
library(REDCapR) #Load the package into the current R session.
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
token <- "9A81268476645C4E5F03428B8AC3AA7B" #`UnitTestPhiFree` user and simple project (pid 153)If no information is passed about the desired records or fields, then the entire data set is returned. Only two parameters are required, redcap_uri and token. Unless the verbose parameter is set to FALSE, a message will be printed on the R console with the number of records and fields returned.
#Return all records and all variables.
ds_all_rows_all_fields <- redcap_read(redcap_uri=uri, token=token)$dataThe data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.5 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 5 records at 2016-09-09 08:42:48Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records).5 records and 24 columns were read from REDCap in 0.5 seconds. The http status code was 200.ds_all_rows_all_fields #Inspect the returned dataset record_id name_first name_last address
1 1 Nutmeg Nutmouse 14 Rose Cottage St.\nKenning UK, 323232
2 2 Tumtum Nutmouse 14 Rose Cottage Blvd.\nKenning UK 34243
3 3 Marcus Wood 243 Hill St.\nGuthrie OK 73402
4 4 Trudy DAG 342 Elm\nDuncanville TX, 75116
5 5 John Lee Walker Hotel Suite\nNew Orleans LA, 70115
telephone email dob age sex
1 (405) 321-1111 nutty@mouse.com 2003-08-30 11 0
2 (405) 321-2222 tummy@mouse.comm 2003-03-10 11 1
3 (405) 321-3333 mw@mwood.net 1934-04-09 80 1
4 (405) 321-4444 peroxide@blonde.com 1952-11-02 61 0
5 (405) 321-5555 left@hippocket.com 1955-04-15 59 1
demographics_complete height weight bmi
1 2 7.00 1 204.1
2 2 6.00 1 277.8
3 2 180.00 80 24.7
4 2 165.00 54 19.8
5 2 193.04 104 27.9
comments
1 Character in a book, with some guessing
2 A mouse character from a good book
3 completely made up
4 This record doesn't have a DAG assigned\n\nSo call up Trudy on the telephone\nSend her a letter in the mail
5 Had a hand for trouble and a eye for cash\n\nHe had a gold watch chain and a black mustache
mugshot health_complete race___1 race___2 race___3 race___4 race___5
1 [document] 1 0 0 0 0 1
2 [document] 0 0 0 1 0 1
3 [document] 2 0 0 0 1 1
4 [document] 2 0 1 0 0 1
5 [document] 0 1 0 0 0 0
race___6 ethnicity race_and_ethnicity_complete
1 0 1 2
2 0 1 0
3 0 0 2
4 0 1 2
5 1 2 2If only a subset of the records is desired, the two approaches are shown below. The first is to pass an array (where each element is an ID) to the records parameter. The second is to pass a single string (where the elements are separated by commas) to the records_collapsed parameter.
The first format is more natural for more R users. The second format is what is expected by the REDCap API. If a value for records is specified, but records_collapsed is not specified, then redcap_read_oneshot automatically converts the array into the format needed by the API.
#Return only records with IDs of 1 and 3
desired_records_v1 <- c(1, 3)
ds_some_rows_v1 <- redcap_read(
redcap_uri = uri,
token = token,
records = desired_records_v1
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.2 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 2 records at 2016-09-09 08:42:51Reading batch 1 of 1, with subjects 1 through 3 (ie, 2 unique subject records).2 records and 24 columns were read from REDCap in 0.5 seconds. The http status code was 200.#Return only records with IDs of 1 and 3 (alternate way)
desired_records_v2 <- "1, 3"
ds_some_rows_v2 <- redcap_read(
redcap_uri = uri,
token = token,
records_collapsed = desired_records_v2
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.2 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 2 records at 2016-09-09 08:42:53Reading batch 1 of 1, with subjects 1 through 3 (ie, 2 unique subject records).2 records and 24 columns were read from REDCap in 0.5 seconds. The http status code was 200.ds_some_rows_v2 #Inspect the returned dataset record_id name_first name_last address
1 1 Nutmeg Nutmouse 14 Rose Cottage St.\nKenning UK, 323232
2 3 Marcus Wood 243 Hill St.\nGuthrie OK 73402
telephone email dob age sex demographics_complete
1 (405) 321-1111 nutty@mouse.com 2003-08-30 11 0 2
2 (405) 321-3333 mw@mwood.net 1934-04-09 80 1 2
height weight bmi comments mugshot
1 7 1 204.1 Character in a book, with some guessing [document]
2 180 80 24.7 completely made up [document]
health_complete race___1 race___2 race___3 race___4 race___5 race___6
1 1 0 0 0 0 1 0
2 2 0 0 0 1 1 0
ethnicity race_and_ethnicity_complete
1 1 2
2 0 2If only a subset of the fields is desired, then two approaches exist. The first is to pass an array (where each element is an field) to the fields parameter. The second is to pass a single string (where the elements are separated by commas) to the fields_collapsed parameter. Like with records and records_collapsed described above, this function converts the more natural format (ie, fields) to the format required by the API (ie, fields_collapsed) if fields is specified and fields_collapsed is not.
#Return only the fields record_id, name_first, and age
desired_fields_v1 <- c("record_id", "name_first", "age")
ds_some_fields_v1 <- redcap_read(
redcap_uri = uri,
token = token,
fields = desired_fields_v1
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.5 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 5 records at 2016-09-09 08:42:54Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records).5 records and 3 columns were read from REDCap in 0.5 seconds. The http status code was 200.#Return only the fields record_id, name_first, and age (alternate way)
desired_fields_v2 <- "record_id, name_first, age"
ds_some_fields_v2 <- redcap_read(
redcap_uri = uri,
token = token,
fields_collapsed = desired_fields_v2
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.5 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 5 records at 2016-09-09 08:42:56Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records).5 records and 3 columns were read from REDCap in 0.5 seconds. The http status code was 200.ds_some_fields_v2 #Inspect the returned dataset record_id name_first age
1 1 Nutmeg 11
2 2 Tumtum 11
3 3 Marcus 80
4 4 Trudy 61
5 5 John Lee 59The two techniques above can be combined when your datasets are large and you don’t want to pull records with certain values. Suppose you want to select subjects from the previous dataset if the were born before 1960 and their weight was over 70kg. Two calls to the server are required. The first call to REDCap pulls all the records, but for only three columns: record_id, dob, and weight. From this subset, identify the records that you want to pull all the data for; in this case, the desired record_id values are 3 & 5. The second call to REDCap pulls all the columns, but only for the identified records.
######
## Step 1: First call to REDCap
desired_fields_v3 <- c("record_id", "dob", "weight")
ds_some_fields_v3 <- redcap_read(
redcap_uri = uri,
token = token,
fields = desired_fields_v3
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.7 seconds. The http status code was 200.5 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 5 records at 2016-09-09 08:42:58Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records).5 records and 3 columns were read from REDCap in 0.5 seconds. The http status code was 200.ds_some_fields_v3 #Examine the these three variables. record_id dob weight
1 1 2003-08-30 1
2 2 2003-03-10 1
3 3 1934-04-09 80
4 4 1952-11-02 54
5 5 1955-04-15 104######
## Step 2: identify desired records, based on age & weight
before_1960 <- (ds_some_fields_v3$dob <= as.Date("1960-01-01"))
heavier_than_70_kg <- (ds_some_fields_v3$weight > 70)
desired_records_v3 <- ds_some_fields_v3[before_1960 & heavier_than_70_kg, ]$record_id
desired_records_v3 #Peek at IDs of the identified records[1] 3 5######
## Step 3: second call to REDCap
#Return only records that met the age & weight criteria.
ds_some_rows_v3 <- redcap_read(
redcap_uri = uri,
token = token,
records = desired_records_v3
)$dataThe data dictionary describing 16 fields was read from REDCap in 0.5 seconds. The http status code was 200.2 records and 1 columns were read from REDCap in 0.5 seconds. The http status code was 200.Starting to read 2 records at 2016-09-09 08:43:00Reading batch 1 of 1, with subjects 3 through 5 (ie, 2 unique subject records).2 records and 24 columns were read from REDCap in 0.4 seconds. The http status code was 200.ds_some_rows_v3 #Examine the results. record_id name_first name_last address
1 3 Marcus Wood 243 Hill St.\nGuthrie OK 73402
2 5 John Lee Walker Hotel Suite\nNew Orleans LA, 70115
telephone email dob age sex
1 (405) 321-3333 mw@mwood.net 1934-04-09 80 1
2 (405) 321-5555 left@hippocket.com 1955-04-15 59 1
demographics_complete height weight bmi
1 2 180.00 80 24.7
2 2 193.04 104 27.9
comments
1 completely made up
2 Had a hand for trouble and a eye for cash\n\nHe had a gold watch chain and a black mustache
mugshot health_complete race___1 race___2 race___3 race___4 race___5
1 [document] 2 0 0 0 1 1
2 [document] 0 1 0 0 0 0
race___6 ethnicity race_and_ethnicity_complete
1 0 0 2
2 1 2 2The examples above have shown only the resulting data.frame, by specifying $data at the end of the call. However, more is available to those wanting additional information, such as 1. The data object has the data.frame, as in the previous examples. 1. The success boolean value indicates if redcap_read_oneshot believes the operation completed as intended. 1. The status_codes is a collection of http status codes, separated by semicolons. There is one code for each batch attempted. 1. The outcome_messages: A collection of human readable strings indicating the operations’ semicolons. There is one code for each batch attempted. In an unsuccessful operation, it should contain diagnostic information. 1. The records_collapsed field passed to the API. This shows which record subsets, if any, were requested. 1. The fields_collapsed fields passed to the API. This shows which field subsets, if any, were requested. 1. The elapsed_seconds measures the duration of the call.
#Return only the fields record_id, name_first, and age
all_information <- redcap_read(
redcap_uri = uri,
token = token,
fields = desired_fields_v1
)The data dictionary describing 16 fields was read from REDCap in 0.4 seconds. The http status code was 200.5 records and 1 columns were read from REDCap in 0.4 seconds. The http status code was 200.Starting to read 5 records at 2016-09-09 08:43:02Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records).5 records and 3 columns were read from REDCap in 0.5 seconds. The http status code was 200.all_information #Inspect the additional information$data
record_id name_first age
1 1 Nutmeg 11
2 2 Tumtum 11
3 3 Marcus 80
4 4 Trudy 61
5 5 John Lee 59
$success
[1] TRUE
$status_codes
[1] "200"
$outcome_messages
[1] "5 records and 3 columns were read from REDCap in 0.5 seconds. The http status code was 200."
$records_collapsed
[1] ""
$fields_collapsed
[1] "record_id,name_first,age"
$filter_logic
[1] ""
$events_collapsed
[1] ""
$elapsed_seconds
[1] 1.814596For the sake of documentation and reproducibility, the current vignette was build on a system using the following software.
Report created by Will at 2016-09-09, 08:43:03 -0500R version 3.3.1 Patched (2016-09-02 r71210)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows >= 8 x64 (build 9200)
locale:
[1] LC_COLLATE=English_United States.1252
[2] LC_CTYPE=English_United States.1252
[3] LC_MONETARY=English_United States.1252
[4] LC_NUMERIC=C
[5] LC_TIME=English_United States.1252
attached base packages:
[1] stats graphics grDevices utils datasets methods base
other attached packages:
[1] REDCapR_0.9.6 knitr_1.14
loaded via a namespace (and not attached):
[1] Rcpp_0.12.7 rstudioapi_0.6 xml2_1.0.0 magrittr_1.5
[5] devtools_1.12.0 R6_2.1.3 stringr_1.1.0 httr_1.2.1
[9] tools_3.3.1 data.table_1.9.6 git2r_0.15.0 withr_1.0.2
[13] htmltools_0.3.5 rversions_1.0.3 yaml_2.1.13 digest_0.6.10
[17] crayon_1.3.2 formatR_1.4 rsconnect_0.4.3 testthat_1.0.2
[21] curl_1.2 memoise_1.0.0 evaluate_0.9 rmarkdown_1.0
[25] stringi_1.1.1 chron_2.3-47