On this page
diff --git a/articles/SecurityDatabase.html b/articles/SecurityDatabase.html
index 972f6602..da610fc4 100644
--- a/articles/SecurityDatabase.html
+++ b/articles/SecurityDatabase.html
@@ -14,8 +14,8 @@
At this point, the data.frame ds_1 has everything you
@@ -603,7 +603,7 @@
On this page
diff --git a/reference/redcap_write.html b/reference/redcap_write.html
index bd463577..bf379546 100644
--- a/reference/redcap_write.html
+++ b/reference/redcap_write.html
@@ -1,5 +1,5 @@
-Write/Import records to a REDCap project — redcap_write • REDCapR Write/Import records to a REDCap project — redcap_write • REDCapR Skip to contents
diff --git a/reference/redcap_write_oneshot.html b/reference/redcap_write_oneshot.html
index 93d3f369..6da763b9 100644
--- a/reference/redcap_write_oneshot.html
+++ b/reference/redcap_write_oneshot.html
@@ -1,5 +1,5 @@
-Write/Import records to a REDCap project — redcap_write_oneshot • REDCapR Write/Import records to a REDCap project — redcap_write_oneshot • REDCapR Skip to contents
diff --git a/reference/replace_nas_with_explicit.html b/reference/replace_nas_with_explicit.html
index a9d79284..d1d549d1 100644
--- a/reference/replace_nas_with_explicit.html
+++ b/reference/replace_nas_with_explicit.html
@@ -1,5 +1,5 @@
-Create explicit factor level for missing values — replace_nas_with_explicit • REDCapR Create explicit factor level for missing values — replace_nas_with_explicit • REDCapR Read a token and other credentials from a (non-REDCap) database or file — retrieve_credential • REDCapR Read a token and other credentials from a (non-REDCap) database or file — retrieve_credential • REDCapR Skip to contents
diff --git a/reference/sanitize_token.html b/reference/sanitize_token.html
index eaae69ba..56ec98f8 100644
--- a/reference/sanitize_token.html
+++ b/reference/sanitize_token.html
@@ -1,5 +1,5 @@
-Validate and sanitize the user's REDCap token — sanitize_token • REDCapR Validate and sanitize the user's REDCap token — sanitize_token • REDCapR Convert a vector to the array format expected by the REDCap API — to_api_array • REDCapR Convert a vector to the array format expected by the REDCap API — to_api_array • REDCapR Inspect a dataset to anticipate problems before writing to a REDCap project — validate • REDCapR Inspect a dataset to anticipate problems before writing to a REDCap project — validate • REDCapR Skip to contents
diff --git a/search.json b/search.json
index fd9e73b6..6e85d58b 100644
--- a/search.json
+++ b/search.json
@@ -1 +1 @@
-[{"path":"https://ouhscbbmc.github.io/REDCapR/CONDUCT.html","id":null,"dir":"","previous_headings":"","what":"Contributor Code of Conduct","title":"Contributor Code of Conduct","text":"contributors maintainers project, pledge respect people contribute reporting issues, posting feature requests, updating documentation, submitting pull requests patches, activities. committed making participation project harassment-free experience everyone, regardless level experience, gender, gender identity expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion. Examples unacceptable behavior participants include use sexual language imagery, derogatory comments personal attacks, trolling, public private harassment, insults, unprofessional conduct. Project maintainers right responsibility remove, edit, reject comments, commits, code, wiki edits, issues, contributions aligned Code Conduct. Project maintainers follow Code Conduct may removed project team. Instances abusive, harassing, otherwise unacceptable behavior may reported opening issue contacting one project maintainers. Code Conduct adapted Contributor Covenant (http:contributor-covenant.org), version 1.0.0, available https://contributor-covenant.org/version/1/0/0/.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/LICENSE.html","id":null,"dir":"","previous_headings":"","what":"MIT License","title":"MIT License","text":"Copyright (c) 2021 REDCapR authors Permission hereby granted, free charge, person obtaining copy software associated documentation files (“Software”), deal Software without restriction, including without limitation rights use, copy, modify, merge, publish, distribute, sublicense, /sell copies Software, permit persons Software furnished , subject following conditions: copyright notice permission notice shall included copies substantial portions Software. SOFTWARE PROVIDED “”, WITHOUT WARRANTY KIND, EXPRESS IMPLIED, INCLUDING LIMITED WARRANTIES MERCHANTABILITY, FITNESS PARTICULAR PURPOSE NONINFRINGEMENT. EVENT SHALL AUTHORS COPYRIGHT HOLDERS LIABLE CLAIM, DAMAGES LIABILITY, WHETHER ACTION CONTRACT, TORT OTHERWISE, ARISING , CONNECTION SOFTWARE USE DEALINGS SOFTWARE.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"reading-redcap-data","dir":"Articles","previous_headings":"","what":"Reading REDCap Data","title":"Basic REDCapR Operations","text":"functions redcap_read() redcap_read_oneshot() use httr package call REDCap API.","code":"## Loading required namespace: kableExtra"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"set-project-wide-values","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Set project-wide values","title":"Basic REDCapR Operations","text":"information specific REDCap project, opposed individual operation. includes (1) uri server, (2) token user’s project.","code":"library(REDCapR) # Load the package into the current R session. uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" # simple"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"read-all-records-and-fields","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Read all records and fields","title":"Basic REDCapR Operations","text":"information passed desired records fields, entire data set returned. two parameters required, redcap_uri token. Unless verbose parameter set FALSE, message printed R console number records fields returned.","code":"# Return all records and all variables. ds_all_rows_all_fields <- redcap_read(redcap_uri = uri, token = token)$data #> 24 variable metadata records were read from REDCap in 0.3 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 5 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 5 records at 2024-11-06 13:23:40.899079. #> Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records). #> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200. ds_all_rows_all_fields # Inspect the returned dataset #> # A tibble: 5 × 25 #> record_id name_first name_last address telephone email dob age sex #> #> 1 1 Nutmeg Nutmouse \"14 Ros… (405) 32… nutt… 2003-08-30 11 0 #> 2 2 Tumtum Nutmouse \"14 Ros… (405) 32… tumm… 2003-03-10 11 1 #> 3 3 Marcus Wood \"243 Hi… (405) 32… mw@m… 1934-04-09 80 1 #> 4 4 Trudy DAG \"342 El… (405) 32… pero… 1952-11-02 61 0 #> 5 5 John Lee Walker \"Hotel … (405) 32… left… 1955-04-15 59 1 #> # ℹ 16 more variables: demographics_complete , height , weight , #> # bmi , comments , mugshot , health_complete , #> # race___1 , race___2 , race___3 , race___4 , #> # race___5 , race___6 , ethnicity , interpreter_needed , #> # race_and_ethnicity_complete "},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"read-a-subset-of-the-records","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Read a subset of the records","title":"Basic REDCapR Operations","text":"subset records desired, two approaches shown . first pass array (element ID) records parameter. second pass single string (elements separated commas) records_collapsed parameter. first format natural R users. second format expected REDCap API. value records specified, records_collapsed specified, redcap_read_oneshot automatically converts array format needed API.","code":"# Return only records with IDs of 1 and 3 desired_records <- c(1, 3) ds_some_rows_v1 <- redcap_read( redcap_uri = uri, token = token, records = desired_records )$data #> 24 variable metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 2 records at 2024-11-06 13:23:42.975089. #> Reading batch 1 of 1, with subjects 1 through 3 (ie, 2 unique subject records). #> 2 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200."},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"read-a-subset-of-the-fields","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Read a subset of the fields","title":"Basic REDCapR Operations","text":"subset fields desired, two approaches exist. first pass array (element field) fields parameter. second pass single string (elements separated commas) fields_collapsed parameter. Like records records_collapsed described , function converts natural format (.e., fields) format required API (.e., fields_collapsed) fields specified fields_collapsed .","code":"# Return only the fields record_id, name_first, and age desired_fields <- c(\"record_id\", \"name_first\", \"age\") ds_some_fields <- redcap_read( redcap_uri = uri, token = token, fields = desired_fields )$data #> 24 variable metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 1.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 5 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 5 records at 2024-11-06 13:23:46.113915. #> Reading 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.2 seconds. The http status code was 200."},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"read-a-subset-of-records-conditioned-on-the-values-in-some-variables","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Read a subset of records, conditioned on the values in some variables","title":"Basic REDCapR Operations","text":"two techniques can combined datasets large don’t want pull records certain values. Suppose want select subjects previous dataset born 1960 weight 70kg. Two calls server required. first call REDCap pulls records, three columns: record_id, dob, weight. subset, identify records want pull data ; case, desired record_id values 3 & 5. second call REDCap pulls columns, identified records.","code":"###### ## 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 )$data #> 24 variable metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 5 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 5 records at 2024-11-06 13:23:48.200291. #> Reading 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.2 seconds. The http status code was 200. ds_some_fields_v3 #Examine the these three variables. #> # A tibble: 5 × 3 #> 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 )$data #> 24 variable metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 2 records at 2024-11-06 13:23:50.185887. #> Reading batch 1 of 1, with subjects 3 through 5 (ie, 2 unique subject records). #> 2 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200. ds_some_rows_v3 #Examine the results. #> # A tibble: 2 × 25 #> record_id name_first name_last address telephone email dob age sex #> #> 1 3 Marcus Wood \"243 Hi… (405) 32… mw@m… 1934-04-09 80 1 #> 2 5 John Lee Walker \"Hotel … (405) 32… left… 1955-04-15 59 1 #> # ℹ 16 more variables: demographics_complete , height , weight , #> # bmi , comments , mugshot , health_complete , #> # race___1 , race___2 , race___3 , race___4 , #> # race___5 , race___6 , ethnicity , interpreter_needed , #> # race_and_ethnicity_complete "},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"additional-returned-information","dir":"Articles","previous_headings":"Reading REDCap Data","what":"Additional Returned Information","title":"Basic REDCapR Operations","text":"examples shown resulting data frame, specifying $data end call. However, available wanting additional information, : data object data frame, previous examples. success boolean value indicates redcap_read_oneshot believes operation completed intended. status_codes collection http status codes, separated semicolons. one code batch attempted. outcome_messages: collection human readable strings indicating operations’ semicolons. one code batch attempted. unsuccessful operation, contain diagnostic information. records_collapsed field passed API. shows record subsets, , requested. fields_collapsed fields passed API. shows field subsets, , requested. elapsed_seconds measures duration call.","code":"#Return only the fields record_id, name_first, and age all_information <- redcap_read( redcap_uri = uri, token = token, fields = desired_fields ) #> 24 variable metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 5 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 5 records at 2024-11-06 13:23:52.169352. #> Reading 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.2 seconds. The http status code was 200. all_information #Inspect the additional information #> $data #> # A tibble: 5 × 3 #> 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.2 seconds. The http status code was 200.\" #> #> $records_collapsed #> [1] \"\" #> #> $fields_collapsed #> [1] \"record_id,name_first,age\" #> #> $forms_collapsed #> [1] \"\" #> #> $events_collapsed #> [1] \"\" #> #> $filter_logic #> [1] \"\" #> #> $datetime_range_begin #> [1] NA #> #> $datetime_range_end #> [1] NA #> #> $elapsed_seconds #> [1] 1.893903"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/BasicREDCapROperations.html","id":"session-information","dir":"Articles","previous_headings":"","what":"Session Information","title":"Basic REDCapR Operations","text":"sake documentation reproducibility, current report rendered following environment. Click line expand. Report rendered runner 2024-11-06, 13:23 +0000 14 seconds.","code":"#> ─ Session info ─────────────────────────────────────────────────────────────── #> setting value #> version R version 4.4.2 (2024-10-31) #> os macOS Sonoma 14.7 #> system aarch64, darwin20 #> ui X11 #> language en #> collate en_US.UTF-8 #> ctype en_US.UTF-8 #> tz UTC #> date 2024-11-06 #> pandoc 3.1.11 @ /usr/local/bin/ (via rmarkdown) #> #> ─ Packages ─────────────────────────────────────────────────────────────────── #> package * version date (UTC) lib source #> backports 1.5.0 2024-05-23 [1] CRAN (R 4.4.0) #> bit 4.5.0 2024-09-20 [1] CRAN (R 4.4.1) #> bit64 4.5.2 2024-09-22 [1] CRAN (R 4.4.1) #> bslib 0.8.0 2024-07-29 [1] CRAN (R 4.4.0) #> cachem 1.1.0 2024-05-16 [1] CRAN (R 4.4.0) #> checkmate 2.3.2 2024-07-29 [1] CRAN (R 4.4.0) #> cli 3.6.3 2024-06-21 [1] CRAN (R 4.4.0) #> colorspace 2.1-1 2024-07-26 [1] CRAN (R 4.4.0) #> crayon 1.5.3 2024-06-20 [1] CRAN (R 4.4.0) #> curl 6.0.0 2024-11-05 [1] CRAN (R 4.4.1) #> desc 1.4.3 2023-12-10 [1] CRAN (R 4.4.0) #> digest 0.6.37 2024-08-19 [1] CRAN (R 4.4.1) #> dplyr 1.1.4 2023-11-17 [1] CRAN (R 4.4.0) #> evaluate 1.0.1 2024-10-10 [1] CRAN (R 4.4.1) #> fansi 1.0.6 2023-12-08 [1] CRAN (R 4.4.0) #> fastmap 1.2.0 2024-05-15 [1] CRAN (R 4.4.0) #> fs 1.6.5 2024-10-30 [1] CRAN (R 4.4.1) #> generics 0.1.3 2022-07-05 [1] CRAN (R 4.4.0) #> glue 1.8.0 2024-09-30 [1] CRAN (R 4.4.1) #> hms 1.1.3 2023-03-21 [1] CRAN (R 4.4.0) #> htmltools 0.5.8.1 2024-04-04 [1] CRAN (R 4.4.0) #> httr 1.4.7 2023-08-15 [1] CRAN (R 4.4.0) #> jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.4.0) #> jsonlite 1.8.9 2024-09-20 [1] CRAN (R 4.4.1) #> kableExtra 1.4.0 2024-01-24 [1] CRAN (R 4.4.0) #> knitr * 1.48 2024-07-07 [1] CRAN (R 4.4.0) #> lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.4.0) #> magrittr * 2.0.3 2022-03-30 [1] CRAN (R 4.4.0) #> munsell 0.5.1 2024-04-01 [1] CRAN (R 4.4.0) #> pillar 1.9.0 2023-03-22 [1] CRAN (R 4.4.0) #> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.4.0) #> pkgdown 2.1.1 2024-09-17 [1] CRAN (R 4.4.1) #> R6 2.5.1 2021-08-19 [1] CRAN (R 4.4.0) #> ragg 1.3.3 2024-09-11 [1] CRAN (R 4.4.1) #> readr 2.1.5 2024-01-10 [1] CRAN (R 4.4.0) #> REDCapR * 1.3.0.9000 2024-11-06 [1] local #> rlang 1.1.4 2024-06-04 [1] CRAN (R 4.4.0) #> rmarkdown 2.29 2024-11-04 [1] CRAN (R 4.4.1) #> rstudioapi 0.17.1 2024-10-22 [1] CRAN (R 4.4.1) #> sass 0.4.9 2024-03-15 [1] CRAN (R 4.4.0) #> scales 1.3.0 2023-11-28 [1] CRAN (R 4.4.0) #> sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.4.0) #> stringi 1.8.4 2024-05-06 [1] CRAN (R 4.4.0) #> stringr 1.5.1 2023-11-14 [1] CRAN (R 4.4.0) #> svglite 2.1.3 2023-12-08 [1] CRAN (R 4.4.0) #> systemfonts 1.1.0 2024-05-15 [1] CRAN (R 4.4.0) #> textshaping 0.4.0 2024-05-24 [1] CRAN (R 4.4.0) #> tibble 3.2.1 2023-03-20 [1] CRAN (R 4.4.0) #> tidyselect 1.2.1 2024-03-11 [1] CRAN (R 4.4.0) #> tzdb 0.4.0 2023-05-12 [1] CRAN (R 4.4.0) #> utf8 1.2.4 2023-10-22 [1] CRAN (R 4.4.0) #> vctrs 0.6.5 2023-12-01 [1] CRAN (R 4.4.0) #> viridisLite 0.4.2 2023-05-02 [1] CRAN (R 4.4.0) #> vroom 1.6.5 2023-12-05 [1] CRAN (R 4.4.0) #> withr 3.0.2 2024-10-28 [1] CRAN (R 4.4.1) #> xfun 0.49 2024-10-31 [1] CRAN (R 4.4.1) #> xml2 1.3.6 2023-12-04 [1] CRAN (R 4.4.0) #> yaml 2.3.10 2024-07-26 [1] CRAN (R 4.4.0) #> #> [1] /Users/runner/work/_temp/Library #> [2] /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library #> #> ──────────────────────────────────────────────────────────────────────────────"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"description","dir":"Articles","previous_headings":"","what":"Description","title":"Security Database","text":"SQL code adds schemas, table two stored procedures existing Microsoft SQL Server database. second database essential calling REDCap API, helps manage tokens securely. database contains tokens sensitive content (passwords, API tokens, file paths) stored Git repository (even private Git repository). passwords can retrieved REDCapR::retrieve_credential_mssql().","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"create-a-dsn-on-each-client","dir":"Articles","previous_headings":"","what":"Create a DSN on each client","title":"Security Database","text":"executing SQL code existing database, create ODBC DSN client machine calls database. Download recent drivers (Aug 2018, recent version 17 Windows Linux), run wizard. Many values wizard remain default values. important ones change. Set DSN’s name field whatever used repository’s R code. Set authenticity method Integrated Windows authentication. Set default database name database containing tokens code , DSN database named auxiliary_security.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"note","dir":"Articles","previous_headings":"","what":"Note","title":"Security Database","text":"use Microsoft SQL Server, fits university’s infrastructure easily. approach theoretically can work LDAP-enabled database server. Please contact us institution using something SQL Server (different configuration components), like help adapting approach.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"create-database","dir":"Articles","previous_headings":"","what":"Create Database","title":"Security Database","text":"SQL code run inside existing database establish schemas, table, stored procedure used REDCapR::retrieve_credential_mssql(). example, ’ve arbitrarily called database auxiliary_security.","code":"------- SQL code to create necessary components in a Microsoft SQL Sever database ------- ----------------------------------------------------------------------- -- Create two schemas. -- The first schema is accessible by all REDCap API users. -- The second schema is restricted to administrators. -- CREATE SCHEMA [redcap] CREATE SCHEMA [redcap_private] GO ----------------------------------------------------------------------- -- Create a table to contain the token CREATE TABLE redcap_private.tbl_credential ( id smallint primary key, username varchar(30) not null, project_id smallint not null, instance varchar(30) not null, token char(32) not null, redcap_uri varchar(255) not null ) CREATE UNIQUE NONCLUSTERED INDEX IX_tbl_credential_unique ON redcap_private.tbl_credential ( instance asc, project_id asc, username asc ) ----------------------------------------------------------------------- -- Create a stored procedure for users to call to retrieve the token. -- Notice it should a different (and more permissive) schema than the table. -- CREATE PROCEDURE redcap.prc_credential @project_id smallint, @instance varchar(30) AS BEGIN SET NOCOUNT ON; SELECT username, project_id, token, redcap_uri FROM redcap_private.tbl_credential WHERE username = system_user -- The username from the server's OS. AND project_id = @project_id -- Restricts to the desired REDCap project. AND instance = @instance -- System accommodates multiple REDCap instances. END"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"create-user-credentials-to-the-auxiliary-database","dir":"Articles","previous_headings":"","what":"Create user credentials to the auxiliary database","title":"Security Database","text":"Add user’s LDAP account auxiliary_security database can query tables retrieve API. Notice gives permissions retrieve token. still must grant API privileges appropriate REDCap project. automation R file copy API token MySQL database auxiliary_security database (see ‘Transfer Credentials’ section). database admins authorization ‘redcap_private’ schema. Typical users authorized schema. current system allows typical users view tokens.","code":"----------------------------------------------------------------------- -- Add a user account to the auxiliary_security database so that they can query the tables to retrieve their API. -- Notice that this only gives the permissions to retrieve the token. You must still: -- 1) grant them API privileges to each appropriate REDCap project, and -- 2) copy the API from the REDCap database into the auxiliary_security database. -- Also, do not give typical users authorization for the 'redcap_private' schema. The current system allows them to view only their own tokens. ----------------------------------------------------------------------- -- STEP #1: Declare the user name. If everything runs correctly, this should be the only piece of code that you need to modify. print 'Step #1 executing....' USE [master] GO DECLARE @qualified_user_name varchar(255); SET @qualified_user_name = '[OUHSC\\lsuarez3]' print 'Resulting login name: ' + @qualified_user_name; print '' --EXEC sp_helplogins @LoginNamePattern=@qualified_user_name --SELECT * FROM master..syslogins WHERE name = @qualified_user_name --SELECT * FROM auxiliary_security.sys.sysusers --SELECT * FROM sys.database_permissions --SELECT * FROM sys.server_principals ----------------------------------------------------------------------- -- STEP #2: Create a login for the *server*. print 'Step #2 executing....' DECLARE @sql_create_login nvarchar(max) SET @sql_create_login = 'CREATE LOGIN ' + @qualified_user_name + ' FROM WINDOWS WITH DEFAULT_DATABASE=[auxiliary_security]' EXECUTE sp_executesql @sql_create_login DECLARE @login_count AS INT; SET @login_count = (SELECT COUNT(*) AS login_count FROM master..syslogins WHERE '[' + loginname + ']' = @qualified_user_name) print 'Logins matching desired name should equal 1. It equals: ' + CONVERT(varchar, @login_count); print '' ----------------------------------------------------------------------- -- STEP #3: Create a user account for the *database*, after switching the database under focus to auxiliary_security. print 'Step #3 executing....' USE [auxiliary_security] DECLARE @sql_create_user nvarchar(max) SET @sql_create_user = 'CREATE USER ' + @qualified_user_name + ' FOR LOGIN ' + @qualified_user_name EXECUTE sp_executesql @sql_create_user DECLARE @user_count AS INT; SET @user_count = (SELECT COUNT(*) AS user_count FROM auxiliary_security.sys.sysusers WHERE '[' + name + ']' = @qualified_user_name) print 'User accounts matching desired name should equal 1. It equals: ' + CONVERT(varchar, @user_count); print '' ----------------------------------------------------------------------- -- STEP #4: Grant appropriate privileges for the 'redcap' schema. print 'Step #4 executing....' DECLARE @sql_grant_schema_redcap nvarchar(max) SET @sql_grant_schema_redcap = 'GRANT EXECUTE ON SCHEMA::[redcap] TO ' + @qualified_user_name EXECUTE sp_executesql @sql_grant_schema_redcap print 'Step #4 executed'; print '' ----------------------------------------------------------------------- -- STEP #5: Grant appropriate privileges for the 'Security' schema. print 'Step #5 executing....' DECLARE @sql_grant_schema_security nvarchar(max) SET @sql_grant_schema_security = 'GRANT EXECUTE ON SCHEMA::[security] TO ' + @qualified_user_name EXECUTE sp_executesql @sql_grant_schema_security print 'Step #5 executed'; print '' ----------------------------------------------------------------------- -- OPTIONAL STEP: Delete the user from the database (the first line) and then the server (the second line). -- The person's other database user accounts (besides with the auxiliary_security database) will NOT be automatically deleted by these two lines. --USE [auxiliary_security]; DROP USER [OUHSC\\lsuarez3] --USE [master]; DROP LOGIN [OUHSC\\lsuarez3] ----------------------------------------------------------------------- -- REFERENCES & NOTES --The @qualified_user_name must have both (a) the 'OUHSC' domain qualification, and (b) the square brackets (to escape the backslash). --Using sp_executesql to add users: https://www.sqlservercentral.com/Forums/Topic497615-359-1.aspx --Check if a server login exists: https://stackoverflow.com/questions/37275/sql-query-for-logins --Retrieve database users: https://stackoverflow.com/questions/2445444/how-to-get-a-list-of-users-for-all-instances-databases --Concatenating strings: https://blog.sqlauthority.com/2010/11/25/sql-server-concat-function-in-sql-server-sql-concatenation/ --DROP USER from database: https://msdn.microsoft.com/en-us/library/ms189438.aspx --DROP LOGIN from server: https://msdn.microsoft.com/en-us/library/ms188012.aspx --Declaring variables (eg, the username above): https://technet.microsoft.com/en-us/library/aa258839.aspx --A different (& non-dynamic) way to establish a user: https://pic.dhe.ibm.com/infocenter/dmndhelp/v8r5m0/index.jsp?topic=%2Fcom.ibm.wbpm.imuc.sbpm.doc%2Ftopics%2Fdb_create_users_nd_aix.html --If the variable has to cross a 'GO' (which the current version of the script doesn't need): https://stackoverflow.com/questions/937336/is-there-a-way-to-persist-a-variable-across-a-go"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"transfer-credentials","dir":"Articles","previous_headings":"","what":"Transfer Credentials","title":"Security Database","text":"Manually transferring tokens auxiliary server becomes unmanageable institution’s collection API users grows. script demonstrates programmatically transfer tokens multiple REDCap instances. basic steps : Read MySQL database(s) underneath REDCap instance campus. Combine & groom credentials. Upload SQL Server (called auxiliary_security ).","code":"rm(list=ls(all=TRUE)) #Clear the memory for any variables set from any previous runs. # ---- load-sources ------------------------------------------------------------ # ---- load-packages ----------------------------------------------------------- if (!require(OuhscMunge)) stop('The `OuhscMunge` package needs to be installed with `remotes::install_github(\"OuhscBbmc/OuhscMunge\")`.') testit::assert( \"The `OuhscMunge` package should meet a minimal version.\", compareVersion( as.character(packageVersion(\"OuhscMunge\")), \"0.1.9.9009\") >= 0L ) library(magrittr) requireNamespace(\"DBI\") requireNamespace(\"odbc\") requireNamespace(\"dplyr\") requireNamespace(\"readr\") requireNamespace(\"tibble\") requireNamespace(\"testit\") requireNamespace(\"checkmate\") requireNamespace(\"OuhscMunge\") # remotes::install_github(\"OuhscBbmc/OuhscMunge\") # ---- declare-globals --------------------------------------------------------- # This file assume your campus has two REDCap instances. # Modify each (a) database name, (b) REDCap URL, and (c) DSN name. name_production <- \"production\" name_dev <- \"dev\" uri_production <- \"https://redcap-production.ouhsc.edu/redcap/api/\", uri_dev <- \"https://redcap-dev.ouhsc.edu/redcap/api/\" dsn_production <- \"redcap-production\" dsn_dev <- \"redcap-dev\" dsn_source <- \"auxiliary_security\" # The DSN of the token server. # The Activity Directory name that should precede each username. # This should correspond with the result of SQL Server's `SYSTEM_USER` function # (https://msdn.microsoft.com/en-us/library/ms179930.aspx) ldap_prefix <- \"OUHSC\\\\\" #### # Nothing below this line should need to change, assuming: # 1. the vignette was followed exactly (https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html), # 2. your campus has exactly two REDCap instances. # SQL sent to the MySQL database underneath each REDCap instance. sql <- \" SELECT username, project_id, api_token FROM redcap_user_rights WHERE api_token IS NOT NULL \" # Update this ad-hoc CSV. Each row should represent one REDCap instance. ds_url <- tibble::tribble( ~instance , ~redcap_uri, name_production , uri_production, name_dev , uri_dev ) # Remove variables that aren't used below. rm(uri_production, uri_dev) # ---- load-data --------------------------------------------------------------- # Load the credentials from the first/production REDCap instance. cnn_production <- DBI::dbConnect(odbc::odbc(), dsn=dsn_production) ds_production <- DBI::dbGetQuery(cnn_production, sql) DBI::dbDisconnect(cnn_production); rm(cnn_production, dsn_production) # Load the credentials from the second/dev REDCap instance. cnn_dev <- DBI::dbConnect(odbc::odbc(), dsn=dsn_dev) ds_dev <- DBI::dbGetQuery(cnn_dev, sql) DBI::dbDisconnect(cnn_dev); rm(cnn_dev, dsn_dev) rm(sql) # Assert these are valid datasets and contain at least 5 rows. # Adjust '5' to smaller value if necessary. It's just to catch blatant retrieval problems. checkmate::assert_data_frame(ds_production, min.rows=5) checkmate::assert_data_frame(ds_dev , min.rows=5) # ---- tweak-data -------------------------------------------------------------- # Label each instance, so they're distinguishable later. ds_production$instance <- name_production ds_dev$instance <- name_dev # Stack the token collection from each instance. Then prefix the username and include the URL of each instance. ds <- ds_production %>% dplyr::union(ds_dev) %>% # Remove union if the dev instance isn't included. tibble::as_tibble() %>% dplyr::select( username = username, project_id = project_id, instance = instance, token = api_token ) %>% dplyr::mutate( username = paste0(ldap_prefix, username), # Qualify for the Active Directory. ) %>% dplyr::left_join( ds_url, by=\"instance\") %>% # Include the instance URL. dplyr::arrange(instance, project_id, username) %>% tibble::rowid_to_column(\"id\") # For the sake of a clustered primary key. rm(ds_production, ds_dev, ds_url) rm(name_production, name_dev) rm(ldap_prefix) # ---- verify-values ----------------------------------------------------------- # Assert that the dataset is well-behaved. # OuhscMunge::verify_value_headstart(ds) checkmate::assert_integer( ds$id , any.missing=FALSE, lower=1, upper=.Machine$integer.max, unique=TRUE) checkmate::assert_character(ds$username , any.missing=FALSE, pattern=\"^.{1,255}$\" ) checkmate::assert_integer( ds$project_id , any.missing=FALSE, lower=1, upper=.Machine$integer.max ) checkmate::assert_character(ds$token , any.missing=FALSE, pattern=\"^[A-Z0-9]{32}$\" , unique=TRUE) checkmate::assert_character(ds$instance , any.missing=FALSE, pattern=\"^.{1,255}$\" ) checkmate::assert_character(ds$redcap_uri , any.missing=FALSE, pattern=\"^.{1,255}$\" ) testit::assert( \"The `username` x `project_id` x `instance` must be unique.\", sum(duplicated(paste0(ds$username, \"-\", ds$project_id, \"-\", ds$instance))) == 0L ) testit::assert(\"At least 10 tokens should be ready to write.\" , 10L <= nrow(ds)) # ---- specify-columns-to-upload ----------------------------------------------- # Dictate the exact columns and order that will be uploaded. columns_to_write <- c(\"id\", \"username\", \"project_id\", \"instance\", \"token\", \"redcap_uri\") ds_slim <- ds[, columns_to_write] rm(columns_to_write) # ---- upload-to-db ------------------------------------------------------------------ OuhscMunge::upload_sqls_odbc( d = ds_slim, schema_name = \"redcap_private\", table_name = \"tbl_credential\", dsn_name = dsn_source, create_table = FALSE, clear_table = TRUE, transaction = TRUE, verbose = TRUE ) # Uploading 252 tokens takes 0.004 minutes."},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","id":"document-info","dir":"Articles","previous_headings":"","what":"Document Info","title":"Security Database","text":"document primarily based REDCap version 8.4.0, last updated 2018-08-10. development version document available GitHub: https://ouhscbbmc.github.io/REDCapR/articles/SecurityDatabase.html","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"server-configuration-and-authorization","dir":"Articles","previous_headings":"Language Agnostic","what":"Server Configuration and Authorization","title":"Troubleshooting REDCap API Calls","text":"first group checks primarily focuses server logins accounts. Unlike later sections, REDCap administrator privileges necessary checks. account server? can verified Browse Users section server’s Control Center. ’re REDCap admin, put user’s position –user account? ’re typical user, may consult institution’s REDCap administrator checks. permissions specific project? can verified User Rights section within project. Notice ’s possible (ultimately useful) account , server, don’t skip previous step. Can log normally interface? However username password aren’t working, API theoretically might still work uses token instead password. verified account responding automated email sent ? can verified Browse Users section server’s Control Center. (Talk REDCap admin.) email address ’ve entered, green ‘Verified’ label icon. granted desired import /export permissions? can verified User Rights section API section (’s Manage Project Tokens tab) within project. Alternatively, can verified API Tokens section server’s Control Center. using correct token? can verified API section (’s Manage Project Tokens tab) within project. Click magnifying glass icon user’s row. Alternatively, can verified API Tokens section server’s Control Center. checks pass, proceed next section. , start consulting REDCap administrator.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"reading","dir":"Articles","previous_headings":"Language Agnostic","what":"Reading","title":"Troubleshooting REDCap API Calls","text":"section examines potential problems occur data leaves working server, handled programming language (e.g., Python R). Postman Chrome plugin recommended several people makes troubleshooting much efficient. API Playground producing expected result? REDCap’s “API Playground” holds hand () offering dropdown list API methods available REDCap instance, (b) presenting series dropdown boxes appropriate selected method. Find API link visible left margin REDCap. ’ve completed inputs, click ‘Execute’ view plain-text returned server. bottom playground page, interface attempts translate specific API call different languages, like Python R. suggestions usually correct, inspect critically, auto-generated script. URL/URI correct? Notice url typically ends “api/” resembles https://redcap.ouhsc.edu/redcap/api/ https://redcap.ouhsc.edu/ (even https://redcap.ouhsc.edu/ redirects https://redcap.ouhsc.edu/redcap/). Postman installed operating correctly? helps start different REDCap server, can use dummy project containing fake data hosted OUHSC BBMC. url https://redcap-dev-2.ouhsc.edu/redcap/api/. three key-value pairs: (1) ‘token’ 9A068C425B1341D69E83064A2D273A70, (2) ‘content’ record, (3) ‘format’ CSV. checking server, token value change, content format . return five records CSV format. ‘status’ 200 OK. result look roughly like . Notice line breaks included text values . Can administrator query API successfully Postman admin token? administrator, create account , verify token works server project. Can administrator query API successfully Postman user’s token? Use Postman , replace token user’s token. whole problem solved, reissue new API tokens user. Can user query API successfully Postman token? values enter exactly entered previous step. failure (assuming previous step successful) suggests network firewall issue. server behind institution’s firewall, verify connecting successfully VPN. Can user query API cURL? cURL command line tool ’s underneath lot libraries. ’s installed correctly location machine, can executed terminal command line. checks pass, proceed next section. , start consulting REDCap administrator. fails, consider creating GitHub issue package (e.g., redcapAPI REDCapR R, phpcap PHP, PyCap Python).","code":"record_id,name_first,name_last,address,telephone,email,dob,age,ethnicity,race,sex,height,weight,bmi,comments,demographics_complete \"1\",\"Nutmeg\",\"Nutmouse\",\"14 Rose Cottage St. Kenning UK, 323232\",\"(432) 456-4848\",\"nutty@mouse.com\",\"2003-08-30\",10,1,2,0,5,1,400,\"Character in a book, with some guessing\",2 \"2\",\"Tumtum\",\"Nutmouse\",\"14 Rose Cottage Blvd. Kenning UK 34243\",\"(234) 234-2343\",\"tummy@mouse.comm\",\"2003-03-10\",10,1,6,1,6,1,277.8,\"A mouse character from a good book\",2 \"3\",\"Marcus\",\"Wood\",\"243 Hill St. Guthrie OK 73402\",\"(433) 435-9865\",\"mw@mwood.net\",\"1934-04-09\",79,0,4,1,180,80,24.7,\"completely made up\",2 \"4\",\"Trudy\",\"DAG\",\"342 Elm Duncanville TX, 75116\",\"(987) 654-3210\",\"peroxide@blonde.com\",\"1952-11-02\",61,1,4,0,165,54,19.8,\"This record doesn't have a DAG assigned So call up Trudy on the telephone Send her a letter in the mail\",2 \"5\",\"John Lee\",\"Walker\",\"Hotel Suite New Orleans LA, 70115\",\"(333) 333-4444\",\"left@hippocket.com\",\"1955-04-15\",58,1,4,1,193.04,104,27.9,\"Had a hand for trouble and a eye for cash He had a gold watch chain and a black mustache\",2 curl -X POST -H \"Cache-Control: no-cache\" -F \"token=9A068C425B1341D69E83064A2D273A70\" -F \"content=record\" -F \"format=csv\" \"https://redcap-dev-2.ouhsc.edu/redcap/api/\""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"writing","dir":"Articles","previous_headings":"Language Agnostic","what":"Writing","title":"Troubleshooting REDCap API Calls","text":"Troubleshooting import operations trickier export operations two major reasons. First, database potentially persists import mistakes. contrast, repeatedly exporting data won’t affect subsequent reads. Considering cloning REDCap project testing problem resolved. Remember create new token (’re automatically created projects cloned, even users copied), modify code’s token point new testing clone. second reason importing can trickier schema (e.g., names data types) local dataset must match project’s schema. Current recommendations include checking can write simpler projects (perhaps 1 ID field 1 string field), progressively moving mimic problematic project’s schema dataset. Also, consider exporting dataset machine, look differences. Note import calculated fields REDCap. dataset pass REDCapR::validate_for_write()? REDCapR::validate_for_write() inspects data frame anticipate problems writing REDCap’s API. reference manual contains specifics validation checks. Can import small subset project? instance, just record_id column. Can export dataset import without modifications? instance, using REDCapR: First, manually complete ~10 example record web browser, export/download records REDCapR::redcap_read_oneshot() data frame. (longitudinal repeating instruments, make sure examples cover dimensions adequately) Second, can successfully upload data.frame (without modification) REDCapR::redcap_write_oneshot()? , dataset provide template structure real dataset assign values. , helpful piece troubleshooting. longitudinal /repeating structure correct? Three variables frequently misspecified: redcap_event_name (longitudinal projects) redcap_repeat_instrument & redcap_repeat_instance (repeating instruments). values variables clearer understand complete step inspect layout. longitudinal projects: Example values redcap_event_name “admission_1_arm_1”, “admission_2_arm_1”, “admission_3_arm_1”. (Notice “_arm_1” suffix used even arms specified project.) projects repeating instruments: Examples values redcap_repeat_instrument “lab”, “vitals”, “medication”; instrument names specified REDCap Designer. Example values redcap_repeat_instance “1”, “2”, “3”, “4”, “5”; consecutive sequence within participant’s longitudinal event. participant 101 two lab results, one vitals record, three medications, dataset structure might : Can import entire project? Can columns written rows? one checks fail, please start consulting REDCap administrator.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"gotchas-agnostic","dir":"Articles","previous_headings":"Language Agnostic","what":"Common Gotchas","title":"Troubleshooting REDCap API Calls","text":"Problems project’s metadata/dictionary. exporting metadata fails (e.g., REDCapR::redcap_metadata_read() redcapAPI::exportMetaData()), manually download data dictionary REDCap browser. Inspect plain text closely text editor like Visual Studio Code; avoid programs like Excel tend interpret, align, decorate values, sometimes masks problems. Scrutinize elements, especially look nonstandard characters. See next bullet. API libraries test problematic elements project handled correctly. encounter element causes problems, please consider creating new GitHub Issue describes problem (e.g., REDCapR, redcapAPI, phpcap). issue, attach problematic fields data dictionary. ’re uncomfortable sharing dictionary world, consider emailing developer. ’s just data dictionary, PHI included. package developer can’t find way gracefully adapt, ’ll least try provide better error message. Identify problematic characters. special case previous bullet. Look fancy characters might interpreted smoothly. instance, editing data dictionary Excel, sometimes straight quotes converted curly quotes. might cause problem later, API client tries interpret character using wrong encoding. ASCII characters REDCap dictionaries appear interpreted smoothly.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"reading-without-a-package","dir":"Articles","previous_headings":"R","what":"Reading without a Package","title":"Troubleshooting REDCap API Calls","text":"several ways call REDCap’s API R. packages redcapAPI REDCapR rely httr package, calls curl package, calls cURL. httr installed user’s local machine? , running library(httr) produce error messages ’re starting fresh session R: recent version httr? several ways , easiest probably run update.packages(ask = FALSE, repos = \"https://cran.rstudio.com\"). optional argument ask prevents user needing respond ‘Y’ outdated package. Can query test project using httr? redcapAPI REDCapR packages employ something similar following function httr. ’re curious, relevant source code redcapAPI REDCapR. check fails, consider attempting url token used Postman example. Alternatively, can try using RCurl package, mostly replaced httr packages developed since 2014. Can query subset project using httr? step like previous one, two differences. First, ’s using REDCap project (instead test project). Second, pulls fewer records, smaller collection fields. Subsetting can help troubleshoot avoiding (thus identifying) cells problematic values. Notice call now passes values records fields parameters. Also notice value single long string (rather vector shorter strings, natural R users). Can query entire project using httr? two advantages trying subset data. First, small datasets avoid time-errors plague large datasets. Second, may avoid problematic values passed pipeline. current check fails previous check succeeds, experiment different expanses records fields. help determine values causing problems, ’s simply much data pulled one pass. desired dataset large, consider can prune unnecessary records fields. , one solution pull smaller, multiple batches using API, reassemble . redcap_read() function REDCapR automatically, allows user specify batch_size. checks pass, proceed next section. , start consulting REDCap administrator.","code":"library(httr) redcap_uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" post_body <- list( token = token, content = 'record', format = 'csv', type = 'flat' ) raw_text <- httr::POST( url = redcap_uri, body = post_body, httr::verbose() # Remove this line to suppress the console updates. ) raw_text raw_text <- RCurl::postForm( uri = redcap_uri , token = token , content = 'record' , format = 'csv' , type = 'flat' ) redcap_uri <- \"https://the.urlofyourinsitution.edu/api/\" token <- \"your-secret-token\" records_collapsed <- \"1,2,3\" # Assumes dataset contains ID values of 1-3. fields_collapsed <- \"record_id,name_first,name_last\" # Assumes dataset contains these variables. post_body <- list( token = token, content = 'record', format = 'csv', type = 'flat', records = records_collapsed, fields = fields_collapsed ) raw_text <- httr::POST( url = redcap_uri, body = post_body, httr::verbose() # Remove this line to suppress the console updates. ) raw_text redcap_uri <- \"https://the.urlofyourinsitution.edu/api/\" token <- \"your-secret-token\" records_collapsed <- NULL fields_collapsed <- NULL post_body <- list( token = token, content = 'record', format = 'csv', type = 'flat', records = records_collapsed, fields = fields_collapsed ) raw_text <- httr::POST( url = redcap_uri, body = post_body, httr::verbose() # Remove this line to suppress the console updates. ) raw_text"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"reading-with-the-redcapr-package","dir":"Articles","previous_headings":"R","what":"Reading with the REDCapR Package","title":"Troubleshooting REDCap API Calls","text":"REDCapR wraps convenience functions around httr reduce size complexity user’s code. package’s basic functions demonstrated vignette documented reference manual. ’re using REDCapR, can skip section proceed “Exporting REDCap R, using redcapAPI” “Importing REDCap R” . REDCapR redcapAPI different R packages, developers collaborate share advice. latest version REDCapR installed machine? Currently easiest way install REDCapR remotes package. following code installs remotes, installs REDCapR. CRAN version REDCapR updated times year, code download latest stable version. REDCapR load successfully machine? , running library(REDCapR) produce following output ’re starting fresh session R: Can export data dictionary? Sometimes problem exists within metadata/dictionary, instead actual data values. Verify structure content specific project interpretable local environment. fails, see “Problems project’s metadata/dictionary” Common Gotchas . problematic data dictionary may produce error Error inherits(ds, \"data.frame\") : object 'ds' found calling REDCapR::redcap_metadata_read(). Can export example project? fake data hosted OUHSC BBMC previous section. previous code produce similar output. Notice five rows columns wrap around console window narrow. Can export project? code similar previous check, uri token values need modified. Alternatively, redcap_project object can declared initially, makes subsequent calls cleaner token url required object declared. export operation still unsuccessful using REDCapR? “Can user query entire REDCap project using httr?” check succeeded, REDCapR checks , consider posting new GitHub issue package developers. one checks fail, please start consulting REDCap administrator.","code":"install.packages(\"remotes\", repos = \"https://cran.rstudio.com\") remotes::install_github(repo = \"OuhscBbmc/REDCapR\") library(REDCapR) # Loading required package: REDCapR library(REDCapR) # Load the package into the current R session, if you haven't already. redcap_uri <- \"https://the.urlofyourinsitution.edu/api/\" token <- \"your-secret-token\" redcap_metadata_read(redcap_uri = uri, token = token) library(REDCapR) # Load the package into the current R session. uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" redcap_read(redcap_uri = uri, token = token)$data 5 records and 1 columns were read from REDCap in 0.41 seconds. Starting to read 5 records at 2014-06-27 17:19:49 Reading batch 1 of 1, with ids 1 through 5. 5 records and 16 columns were read from REDCap in 0.42 seconds. record_id name_first name_last address telephone email 1 1 Nutmeg Nutmouse 14 Rose Cottage St.\\nKenning UK, 323232 (432) 456-4848 nutty@mouse.com 2 2 Tumtum Nutmouse 14 Rose Cottage Blvd.\\nKenning UK 34243 (234) 234-2343 tummy@mouse.comm 3 3 Marcus Wood 243 Hill St.\\nGuthrie OK 73402 (433) 435-9865 mw@mwood.net 4 4 Trudy DAG 342 Elm\\nDuncanville TX, 75116 (987) 654-3210 peroxide@blonde.com 5 5 John Lee Walker Hotel Suite\\nNew Orleans LA, 70115 (333) 333-4444 left@hippocket.com dob age ethnicity race sex height weight bmi 1 2003-08-30 10 1 2 0 5.00 1 400.0 2 2003-03-10 10 1 6 1 6.00 1 277.8 3 1934-04-09 79 0 4 1 180.00 80 24.7 4 1952-11-02 61 1 4 0 165.00 54 19.8 5 1955-04-15 58 1 4 1 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 demographics_complete 1 2 2 2 3 2 4 2 5 2 library(REDCapR) # Load the package into the current R session, if you haven't already. redcap_uri <- \"https://the.urlofyourinsitution.edu/api/\" token <- \"your-secret-token\" redcap_read(redcap_uri = uri, token = token)$data library(REDCapR) # Load the package into the current R session, if you haven't already. uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" project <- redcap_project$new(redcap_uri = uri, token = token) ds_three_columns <- project$read(fields = c(\"record_id\", \"sex\", \"age\"))$data ids_of_males <- ds_three_columns$record_id[ds_three_columns$sex == 1] ids_of_minors <- ds_three_columns$record_id[ds_three_columns$age < 18] ds_males <- project$read(records = ids_of_males, batch_size = 2)$data ds_minors <- project$read(records = ids_of_minors)$data"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"reading-with-the-redcapapi-package","dir":"Articles","previous_headings":"R","what":"Reading with the redcapAPI Package","title":"Troubleshooting REDCap API Calls","text":"httr redcapAPI wraps convenience functions around httr reduce size complexity user’s code. ’re using redcapAPI, can skip section proceed ‘Importing REDCap R’ . specific discussion redcapAPI can found package’s wiki. redcapAPI REDCapR different packages, developers collaborate share advice. redcapAPI installed machine? Currently, easiest way install redcapAPI CRAN. Developmental versions may available GitHub. redcapAPI load successfully machine? , running library(redcapAPI) produce following output ’re starting fresh session R: Can export data dictionary? Sometimes problem exists within metadata/dictionary, instead actual data values. Verify structure content specific project interpretable local environment. fails, see “Problems project’s metadata/dictionary.” Gotchas Can export example project? fake data hosted OUHSC BBMC previous section. previous code produce similar output. Notice five rows columns wrap around console window narrow. Can export project? code similar previous check, uri token values need modified. export operation still unsuccessful using redcapAPI? “Can user query entire REDCap project using httr?” check succeeded, redcapAPI checks , consider posting new GitHub issue package developers. one checks fail, please start consulting REDCap administrator.","code":"install.packages(\"redcapAPI\") install.packages(\"remotes\", repos = \"https://cran.rstudio.com\") remotes::install_github(repo = \"nutterb/redcapAPI\") library(redcapAPI) # Loading required package: redcapAPI library(redcapAPI) # Load the package into the current R session, if you haven't already. redcap_uri <- \"https://the.urlofyourinsitution.edu/api/\" token <- \"your-secret-token\" exportMetaData(rcon) library(redcapAPI) # Load the package into the current R session. rcon <- redcapConnection( url = \"https://redcap-dev-2.ouhsc.edu/redcap/api/\", token = \"9A068C425B1341D69E83064A2D273A70\" ) exportRecords(rcon) record_id name_first name_last address telephone email 1 1 Nutmeg Nutmouse 14 Rose Cottage St.\\nKenning UK, 323232 (432) 456-4848 nutty@mouse.com 2 2 Tumtum Nutmouse 14 Rose Cottage Blvd.\\nKenning UK 34243 (234) 234-2343 tummy@mouse.comm 3 3 Marcus Wood 243 Hill St.\\nGuthrie OK 73402 (433) 435-9865 mw@mwood.net 4 4 Trudy DAG 342 Elm\\nDuncanville TX, 75116 (987) 654-3210 peroxide@blonde.com 5 5 John Lee Walker Hotel Suite\\nNew Orleans LA, 70115 (333) 333-4444 left@hippocket.com dob age ethnicity race sex height weight bmi 1 2003-08-30 10 1 2 0 5.00 1 400.0 2 2003-03-10 10 1 6 1 6.00 1 277.8 3 1934-04-09 79 0 4 1 180.00 80 24.7 4 1952-11-02 61 1 4 0 165.00 54 19.8 5 1955-04-15 58 1 4 1 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 demographics_complete 1 2 2 2 3 2 4 2 5 2 library(redcapAPI) # Load the package into the current R session, if you haven't already. rcon <- redcapConnection( url = \"https://the.urlofyourinsitution.edu/api/\", # Adapt this to your server. token = \"your-secret-token\" # Adapt this to your user's token. ) exportRecords(rcon)"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"troubleshooting-strategies","dir":"Articles","previous_headings":"General Information","what":"Troubleshooting Strategies","title":"Troubleshooting REDCap API Calls","text":"Simplify. Eliminate potential sources problems cumulatively. example, reduce columns & records read/write. Start fresh. ’s feasible, start new REDCap project gradually add elements original project. Identify problematic element testing API call addition.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"resources","dir":"Articles","previous_headings":"General Information","what":"Resources","title":"Troubleshooting REDCap API Calls","text":"REDCap used many environments, ’s surprising lot libraries developed cater different scenarios languages. active list maintained REDCap-Tools. entry needs added, please notify us; instructions found bottom page. basic API documentation available REDCap server, typically access REDCap wiki, newer examples might exist https://community.projectredcap.org/articles/462/api-examples.html. official documentation can found “API Help Page” “API Examples” pages REDCap wiki (.e., https://community.projectredcap.org/articles/456/api-documentation.html https://community.projectredcap.org/articles/462/api-examples.html). account wiki, please ask campus REDCap administrator send static material. Scott Burns, primary developer PyCap good intro http://sburns.org/2013/07/22/intro--redcap-api.html Benjamin Nutter, primary developer redcapAPI good wiki https://github.com/nutterb/redcapAPI/wiki addition troubleshooting document, REDCapR vignettes covers basic advanced operations.","code":"https://<*your server name*>/redcap/api/help"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html","id":"document-info","dir":"Articles","previous_headings":"General Information","what":"Document Info","title":"Troubleshooting REDCap API Calls","text":"document primarily based REDCap version 6.0.2 last updated 2020-01-21. development version document available GitHub: https://ouhscbbmc.github.io/REDCapR/articles/TroubleshootingApiCalls.html.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"set-project-wide-values","dir":"Articles","previous_headings":"","what":"Set project-wide values","title":"Advanced REDCapR Operations","text":"information specific REDCap project, opposed individual operation. includes (1) uri server, (2) token user’s project. hosted machine used REDCapR’s public test suite, can run example computer. Unless tests running. PHI-free demos, strongly suggest storing tokens securely avoiding hard-coding like . recommendation store tokens database. feasible institution, consider storing secured csv retrieving REDCapR::retrieve_credential_local().","code":"library(REDCapR) #Load the package into the current R session. uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token_simple <- \"9A068C425B1341D69E83064A2D273A70\" token_longitudinal <- \"DA6F2BB23146BD5A7EA3408C1A44A556\""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"converting-from-talllong-to-wide","dir":"Articles","previous_headings":"","what":"Converting from tall/long to wide","title":"Advanced REDCapR Operations","text":"Disclaimer: Occasionally ’re asked longitudinal dataset converted “long/tall format” (typically row one observation participant) “wide format” (row participant). Usually advise . Besides database benefits long structure, wide structure restricts options stat routine. modern longitudinal analysis procedures (e.g., growth curve models multilevel/hierarchical models) accept wide. ’re pretty much stuck repeated measures anova, inflexible real-world medical-ish analyses. requires patient measurement every time point; otherwise anova excludes patient entirely. However like going wide produce visual tables publications, ’s one way R. First retrieve dataset REDCap. widening one variable (e.g., pmq1), code’s pretty simple: scenarios, multiple variables (e.g., pmq1 - pmq4) can widened single tidyr::pivot_wider() operation. example contains additional wrinkle REDCap event names “first_dose” “first_visit” renamed “dose_1” “visit_1”, help values dose visit values proper numbers. However, widening scenarios, can easier go even longer/taller (e.g., ds_eav) reversing direction going wide. Lots packages documentation exist. current preference tidyverse approach pivoting, data.table approach worth considering ’re comfortable package. Stack Overflow post describes several ways. recommend reshape reshape2 packages, developers replaced tidyr functions described .","code":"library(magrittr) suppressPackageStartupMessages(requireNamespace(\"dplyr\")) suppressPackageStartupMessages(requireNamespace(\"tidyr\")) events_to_retain <- c(\"dose_1_arm_1\", \"visit_1_arm_1\", \"dose_2_arm_1\", \"visit_2_arm_1\") ds_long <- REDCapR::redcap_read_oneshot(redcap_uri = uri, token = token_longitudinal)$data #> 18 records and 125 columns were read from REDCap in 0.4 seconds. The http status code was 200. ds_long %>% dplyr::select(study_id, redcap_event_name, pmq1, pmq2, pmq3, pmq4) #> # A tibble: 18 × 6 #> study_id redcap_event_name pmq1 pmq2 pmq3 pmq4 #> #> 1 100 enrollment_arm_1 NA NA NA NA #> 2 100 dose_1_arm_1 2 2 1 1 #> 3 100 visit_1_arm_1 1 0 0 0 #> 4 100 dose_2_arm_1 3 1 0 0 #> 5 100 visit_2_arm_1 0 1 0 0 #> 6 100 final_visit_arm_1 NA NA NA NA #> 7 220 enrollment_arm_1 NA NA NA NA #> 8 220 dose_1_arm_1 0 1 0 2 #> 9 220 visit_1_arm_1 0 3 1 0 #> 10 220 dose_2_arm_1 1 2 0 1 #> 11 220 visit_2_arm_1 3 4 1 0 #> 12 220 final_visit_arm_1 NA NA NA NA #> 13 304 enrollment_arm_2 NA NA NA NA #> 14 304 deadline_to_opt_ou_arm_2 NA NA NA NA #> 15 304 first_dose_arm_2 0 1 0 0 #> 16 304 first_visit_arm_2 2 0 0 0 #> 17 304 final_visit_arm_2 NA NA NA NA #> 18 304 deadline_to_return_arm_2 NA NA NA NA ds_wide <- ds_long %>% dplyr::select(study_id, redcap_event_name, pmq1) %>% dplyr::filter(redcap_event_name %in% events_to_retain) %>% tidyr::pivot_wider( id_cols = study_id, names_from = redcap_event_name, values_from = pmq1 ) ds_wide #> # A tibble: 2 × 5 #> study_id dose_1_arm_1 visit_1_arm_1 dose_2_arm_1 visit_2_arm_1 #> #> 1 100 2 1 3 0 #> 2 220 0 0 1 3 pattern <- \"^(\\\\w+?)_arm_(\\\\d)$\" ds_wide <- ds_long %>% dplyr::select(study_id, redcap_event_name, pmq1, pmq2, pmq3, pmq4) %>% dplyr::mutate( event = sub(pattern, \"\\\\1\", redcap_event_name), event = dplyr::recode(event, \"first_dose\"=\"dose_1\", \"first_visit\"=\"visit_1\"), arm = as.integer(sub(pattern, \"\\\\2\", redcap_event_name)) ) %>% dplyr::select(study_id, event, arm, pmq1, pmq2, pmq3, pmq4) %>% dplyr::filter(!(event %in% c(\"enrollment\", \"final_visit\", \"deadline_to_return\", \"deadline_to_opt_ou\") )) %>% tidyr::pivot_wider( id_cols = c(study_id, arm), names_from = event, values_from = c(pmq1, pmq2, pmq3, pmq4) ) ds_wide #> # A tibble: 3 × 18 #> study_id arm pmq1_dose_1 pmq1_visit_1 pmq1_dose_2 pmq1_visit_2 pmq2_dose_1 #> #> 1 100 1 2 1 3 0 2 #> 2 220 1 0 0 1 3 1 #> 3 304 2 0 2 NA NA 1 #> # ℹ 11 more variables: pmq2_visit_1 , pmq2_dose_2 , #> # pmq2_visit_2 , pmq3_dose_1 , pmq3_visit_1 , #> # pmq3_dose_2 , pmq3_visit_2 , pmq4_dose_1 , #> # pmq4_visit_1 , pmq4_dose_2 , pmq4_visit_2 ds_eav <- ds_long %>% dplyr::select(study_id, redcap_event_name, pmq1, pmq2, pmq3, pmq4) %>% dplyr::mutate( event = sub(pattern, \"\\\\1\", redcap_event_name), event = dplyr::recode(event, \"first_dose\" = \"dose_1\", \"first_visit\" = \"visit_1\"), arm = as.integer(sub(pattern, \"\\\\2\", redcap_event_name)) ) %>% dplyr::select(study_id, event, arm, pmq1, pmq2, pmq3, pmq4) %>% tidyr::pivot_longer( cols = c(pmq1, pmq2, pmq3, pmq4), names_to = \"key\", values_to = \"value\" ) %>% # For old versions of tidyr that predate `pivot_wider()`: # tidyr::gather(key=key, value=value, pmq1, pmq2, pmq3, pmq4) %>% dplyr::filter(!(event %in% c( \"enrollment\", \"final_visit\", \"deadline_to_return\", \"deadline_to_opt_ou\") )) %>% dplyr::mutate( # Simulate correcting for mismatched names across arms: key = paste0(key, \"_\", event) ) %>% dplyr::select(-event) # Show the first 10 rows of the EAV table. ds_eav %>% head(10) #> # A tibble: 10 × 4 #> study_id arm key value #> #> 1 100 1 pmq1_dose_1 2 #> 2 100 1 pmq2_dose_1 2 #> 3 100 1 pmq3_dose_1 1 #> 4 100 1 pmq4_dose_1 1 #> 5 100 1 pmq1_visit_1 1 #> 6 100 1 pmq2_visit_1 0 #> 7 100 1 pmq3_visit_1 0 #> 8 100 1 pmq4_visit_1 0 #> 9 100 1 pmq1_dose_2 3 #> 10 100 1 pmq2_dose_2 1 # Spread the EAV to wide. ds_wide_2 <- ds_eav %>% tidyr::pivot_wider( id_cols = c(study_id, arm), names_from = key, values_from = value ) # For old versions of tidyr that predate `pivot_wider()`: # tidyr::spread(key=key, value=value) ds_wide_2 #> # A tibble: 3 × 18 #> study_id arm pmq1_dose_1 pmq2_dose_1 pmq3_dose_1 pmq4_dose_1 pmq1_visit_1 #> #> 1 100 1 2 2 1 1 1 #> 2 220 1 0 1 0 2 0 #> 3 304 2 0 1 0 0 2 #> # ℹ 11 more variables: pmq2_visit_1 , pmq3_visit_1 , #> # pmq4_visit_1 , pmq1_dose_2 , pmq2_dose_2 , #> # pmq3_dose_2 , pmq4_dose_2 , pmq1_visit_2 , #> # pmq2_visit_2 , pmq3_visit_2 , pmq4_visit_2 "},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"query-the-underlying-mysql-database","dir":"Articles","previous_headings":"","what":"Query the Underlying MySQL Database","title":"Advanced REDCapR Operations","text":"require feature available instance’s API, first upgrade institution’s REDCap instance see feature added recently. Second, check someone released desired API-like features REDCap External Module. Third, may need query database underneath REDCap’s web server. Transfer Credentials section Security Database Vignette provides complete example using R query MySQL database odbc. find ’s best develop query MySQL Workbench, copy code R (alternatively, use OuhscMunge::execute_sql_file()). example retrieves first_submit_time, helpful need timestamp surveys marked completed. Replace ‘444’ pid, 1001 1003 desired events.","code":"SELECT p.participant_id as participant_survey_id ,r.record as record_id ,p.event_id ,e.descrip as event_name ,r.first_submit_time ,r.completion_time -- ,p.* -- ,r.* FROM redcapv3.redcap_surveys_participants as p left join redcapv3.redcap_surveys_response as r on p.participant_id = r.participant_id left join redcapv3.redcap_events_metadata as e on p.event_id = e.event_id WHERE p.survey_id = 444 and p.event_id in ( 1001, -- start of the year 1002, -- mid term 1003 -- end of year )"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"ssl-options","dir":"Articles","previous_headings":"","what":"SSL Options","title":"Advanced REDCapR Operations","text":"official cURL site discusses process using SSL verify server connected . Use SSL cert file come openssl package. Force connection use SSL=3 (preferred, possibly insecure).","code":"cert_location <- system.file(\"cacert.pem\", package = \"openssl\") if (file.exists(cert_location)) { config_options <- list(cainfo = cert_location) ds_different_cert_file <- redcap_read_oneshot( redcap_uri = uri, token = token_simple, config_options = config_options )$data } #> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200. config_options <- list(sslversion = 3) ds_ssl_3 <- redcap_read_oneshot( redcap_uri = uri, token = token_simple, config_options = config_options )$data #> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200. config_options <- list(ssl.verifypeer = FALSE) ds_no_ssl <- redcap_read_oneshot( redcap_uri = uri, token = token_simple, config_options = config_options )$data #> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200."},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"convert-spss-output-to-redcap-data-dictionary","dir":"Articles","previous_headings":"","what":"Convert SPSS Output to REDCap data dictionary","title":"Advanced REDCapR Operations","text":"solution https://stackoverflow.com//51013678/1082435 converts levels specified SPSS output like dropdown choices REDCap data dictionary like","code":"SEX 0 Male 1 Female LANGUAGE 1 English 2 Spanish 3 Other 6 Unknown Variable Values SEX 0, Male | 1, Female LANGUAGE 1, English | 2, Spanish | 3, Other | 6, Unknown"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/advanced-redcapr-operations.html","id":"session-information","dir":"Articles","previous_headings":"","what":"Session Information","title":"Advanced REDCapR Operations","text":"sake documentation reproducibility, current report rendered following environment. Click line expand. Report rendered runner 2024-11-06, 13:23 +0000 2 seconds.","code":"#> ─ Session info ─────────────────────────────────────────────────────────────── #> setting value #> version R version 4.4.2 (2024-10-31) #> os macOS Sonoma 14.7 #> system aarch64, darwin20 #> ui X11 #> language en #> collate en_US.UTF-8 #> ctype en_US.UTF-8 #> tz UTC #> date 2024-11-06 #> pandoc 3.1.11 @ /usr/local/bin/ (via rmarkdown) #> #> ─ Packages ─────────────────────────────────────────────────────────────────── #> package * version date (UTC) lib source #> backports 1.5.0 2024-05-23 [1] CRAN (R 4.4.0) #> bit 4.5.0 2024-09-20 [1] CRAN (R 4.4.1) #> bit64 4.5.2 2024-09-22 [1] CRAN (R 4.4.1) #> bslib 0.8.0 2024-07-29 [1] CRAN (R 4.4.0) #> cachem 1.1.0 2024-05-16 [1] CRAN (R 4.4.0) #> checkmate 2.3.2 2024-07-29 [1] CRAN (R 4.4.0) #> cli 3.6.3 2024-06-21 [1] CRAN (R 4.4.0) #> colorspace 2.1-1 2024-07-26 [1] CRAN (R 4.4.0) #> crayon 1.5.3 2024-06-20 [1] CRAN (R 4.4.0) #> curl 6.0.0 2024-11-05 [1] CRAN (R 4.4.1) #> desc 1.4.3 2023-12-10 [1] CRAN (R 4.4.0) #> digest 0.6.37 2024-08-19 [1] CRAN (R 4.4.1) #> dplyr 1.1.4 2023-11-17 [1] CRAN (R 4.4.0) #> evaluate 1.0.1 2024-10-10 [1] CRAN (R 4.4.1) #> fansi 1.0.6 2023-12-08 [1] CRAN (R 4.4.0) #> fastmap 1.2.0 2024-05-15 [1] CRAN (R 4.4.0) #> fs 1.6.5 2024-10-30 [1] CRAN (R 4.4.1) #> generics 0.1.3 2022-07-05 [1] CRAN (R 4.4.0) #> glue 1.8.0 2024-09-30 [1] CRAN (R 4.4.1) #> hms 1.1.3 2023-03-21 [1] CRAN (R 4.4.0) #> htmltools 0.5.8.1 2024-04-04 [1] CRAN (R 4.4.0) #> httr 1.4.7 2023-08-15 [1] CRAN (R 4.4.0) #> jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.4.0) #> jsonlite 1.8.9 2024-09-20 [1] CRAN (R 4.4.1) #> kableExtra 1.4.0 2024-01-24 [1] CRAN (R 4.4.0) #> knitr * 1.48 2024-07-07 [1] CRAN (R 4.4.0) #> lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.4.0) #> magrittr * 2.0.3 2022-03-30 [1] CRAN (R 4.4.0) #> munsell 0.5.1 2024-04-01 [1] CRAN (R 4.4.0) #> pillar 1.9.0 2023-03-22 [1] CRAN (R 4.4.0) #> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.4.0) #> pkgdown 2.1.1 2024-09-17 [1] CRAN (R 4.4.1) #> purrr 1.0.2 2023-08-10 [1] CRAN (R 4.4.0) #> R6 2.5.1 2021-08-19 [1] CRAN (R 4.4.0) #> ragg 1.3.3 2024-09-11 [1] CRAN (R 4.4.1) #> readr 2.1.5 2024-01-10 [1] CRAN (R 4.4.0) #> REDCapR * 1.3.0.9000 2024-11-06 [1] local #> rlang 1.1.4 2024-06-04 [1] CRAN (R 4.4.0) #> rmarkdown 2.29 2024-11-04 [1] CRAN (R 4.4.1) #> rstudioapi 0.17.1 2024-10-22 [1] CRAN (R 4.4.1) #> sass 0.4.9 2024-03-15 [1] CRAN (R 4.4.0) #> scales 1.3.0 2023-11-28 [1] CRAN (R 4.4.0) #> sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.4.0) #> stringi 1.8.4 2024-05-06 [1] CRAN (R 4.4.0) #> stringr 1.5.1 2023-11-14 [1] CRAN (R 4.4.0) #> svglite 2.1.3 2023-12-08 [1] CRAN (R 4.4.0) #> systemfonts 1.1.0 2024-05-15 [1] CRAN (R 4.4.0) #> textshaping 0.4.0 2024-05-24 [1] CRAN (R 4.4.0) #> tibble 3.2.1 2023-03-20 [1] CRAN (R 4.4.0) #> tidyr 1.3.1 2024-01-24 [1] CRAN (R 4.4.0) #> tidyselect 1.2.1 2024-03-11 [1] CRAN (R 4.4.0) #> tzdb 0.4.0 2023-05-12 [1] CRAN (R 4.4.0) #> utf8 1.2.4 2023-10-22 [1] CRAN (R 4.4.0) #> vctrs 0.6.5 2023-12-01 [1] CRAN (R 4.4.0) #> viridisLite 0.4.2 2023-05-02 [1] CRAN (R 4.4.0) #> vroom 1.6.5 2023-12-05 [1] CRAN (R 4.4.0) #> withr 3.0.2 2024-10-28 [1] CRAN (R 4.4.1) #> xfun 0.49 2024-10-31 [1] CRAN (R 4.4.1) #> xml2 1.3.6 2023-12-04 [1] CRAN (R 4.4.0) #> yaml 2.3.10 2024-07-26 [1] CRAN (R 4.4.0) #> #> [1] /Users/runner/work/_temp/Library #> [2] /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library #> #> ──────────────────────────────────────────────────────────────────────────────"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"background","dir":"Articles","previous_headings":"","what":"Background","title":"Retrieving Longitudinal and Repeating Structures","text":"vignette pertains reading REDCap records project () longitudinal events (b) repeating measure. first section conceptually discusses REDCap stores complex structures. remaining sections describe best retrieve complex structures REDCapTidyieR REDCapR packages. new R REDCap, consider start Typical REDCap Workflow Data Analyst Basic REDCapR Operations vignettes return document. reading simple project, just call REDCapR’s redcap_read(). want perform operation (writing records REDCap), review Reference REDCapR functions see currently available. REDCap project longitudinal contains repeating measures, single call API (single export browser) return dataset readily analyzed. Instead, dataset resemble Table 5. isn’t software bug, haven’t told software like data structured. isn’t good way jam multidimensional space rectangle points. advice querying REDCap querying database system: request separate datasets natural “grain” assemble fit analyses.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"possible-table-structures","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured","what":"Possible Table Structures","title":"Retrieving Longitudinal and Repeating Structures","text":"Suppose two patients (.e., “1” “2”) three intake variables (.e., height, weight, bmi). record piece paper, probably look like Table 1. table’s grain “patient”, row represents distinct patient. Understanding grain structure help understand structures re-expressions set observations.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"table-1-patient-grain","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Possible Table Structures","what":"Table 1: patient grain","title":"Retrieving Longitudinal and Repeating Structures","text":"patient-grain structure data points comfortably inputted humans REDCap, default exported browser API. However stored differently REDCap’s internal database. REDCap’s flexibility driver success. research team learns REDCap, can reuse knowledge capture anything leukemia lunch orders. achieve flexibility world REDCap EMRs, data stored along observation grain. computer science, commonly called EAV structure (stands entity-attribute-value). patient’s ID entity, variable type attribute, observed point value. can also thought “key-value store” nested within patient (“key” synonym “attribute”). Notice two wider rows morphed six skinnier rows –one row per observation. curious database administrator, peek structure rows redcap_data table. important table database.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"table-2-observation-grain-for-intake-instrument","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Possible Table Structures","what":"Table 2: observation grain for intake instrument","title":"Retrieving Longitudinal and Repeating Structures","text":"REDCap EMR databases store observations underlying table. table simplification redcap_data table, heart REDCap’s internal database. investigation gains longitudinal repeating component, becomes necessary include dimension time. Suppose protocol specifies five time points; blood pressure instrument captured times 1, 2, & 3 laboratory instrument captured times 1 & 2. record stage paper, likely resemble Tables 3a & 3b: one vitals one labs.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"table-3b-patient-time-grain-for-laboratory-instrument","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Possible Table Structures","what":"Table 3b: patient-time grain for laboratory instrument","title":"Retrieving Longitudinal and Repeating Structures","text":"measurements added REDCap’s observation table, resembles Table 4. Two new columns required uniquely distinguish instrument ordinal position. Notice first six rows copied Table 2; empty values repeating structure.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"table-4-observation-grain-for-intake-blood_pressure-and-laboratory-instruments","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Possible Table Structures","what":"Table 4: observation grain for intake, blood_pressure, and laboratory instruments","title":"Retrieving Longitudinal and Repeating Structures","text":"mentioned , isn’t universally good way coerce Tables 1, 3a, 3b single rectangle rows represent different things. REDCap’s perspective, ’s good transformation redcap_data (.e., Table 4) appropriate statistical programs. forced combine different entities, best option probably Table 5. call “block dataset”, borrowing linear algebra’s block matrix term. can see mishmash tables masquerading unified dataset. rows lack conceptual coherency Tables 1, 3a, & 3b.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"table-5-mishmashed-grain","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Possible Table Structures","what":"Table 5: mishmashed grain","title":"Retrieving Longitudinal and Repeating Structures","text":"block dataset inherently bad. , Table 5 can unambiguously transformed Table 4. Table 5’s primary limitation block dataset understood analysis software used conventional medical research. best, dataset always require additional preparation. worst, analyst model rows inappropriately, produce misleading conclusions. Table 5’s secondary limitation inefficiency. empty cells aren’t computationally free. Every cell must queried database concatenated REDCap’s web server order return Table 5 plain-text csv, json, xml format. simple example, half block dataset’s cells wasted. emptiness frequently exceeds 90% real-world REDCap projects (tend many variables repeating instances). emptiness always exceeds 99.9% real-world EMRs. reason, REDCap EMR design observation table resemble computational structure sparse matrix. (important difference REDCap’s unspecified cells interpreted null/empty, sparse matrix’s unspecified cells interpreted zero.) case sparse matrix, substantial memory requirement reductions can realized storing non-zero entries. Depending number distribution non-zero entries, different data structures can used yield huge savings memory compared basic approach. trade-accessing individual elements becomes complex additional structures needed able recover original matrix unambiguously. (source: Wikipedia: Sparse matrix - storage)","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"observation","dir":"Articles","previous_headings":"Illustration of How Data Points are Structured > Terminology","what":"observation","title":"Retrieving Longitudinal and Repeating Structures","text":"term “observation” world medical databases different granular meaning tidyverse literature. REDCap medical databases, observation typically single point (heart rate systolic blood pressure) contextual variables (associated date, unit, visit ID, patient ID); see Tables 2 4 . tidyverse publications, observation roughly equivalent REDCap instrument (collection associated values); see Tables 1, 3a, 3b. (use medical terminology vignette. ’d love hear someone another term ’s unambiguous.)","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"retrieving-from-redcap","dir":"Articles","previous_headings":"","what":"Retrieving from REDCap","title":"Retrieving Longitudinal and Repeating Structures","text":"Many new REDCap users submit single API call unintentionally obtain something like Table 5; try extract something resembling Tables 1, 3a, & 3b. Although can successful, strongly discourage . code difficult maintain portable REDCap projects different instruments. (code really slow ugly .) advice start Table 5 assembled –retrieve information better way. Like database systems, request three tables separately server combine desktop fit analyses necessary. Two approaches appropriate scenarios: multiple calls REDCapR’s redcap_read(), single call REDCapTidieR’s redcap_read_tidy(). code vignette requires magrittr package %>% (alternatively can use |> ’re using R 4.0.2 later). vignette uses credentials retrieve practice/fake dataset. appropriate datasets containing PHI sensitive information. Please see Part 2 - Retrieve Protected Token Typical REDCap Workflow Data Analyst vignette secure approaches.","code":"# Support pipes library(magrittr) # Retrieve token path_credential <- system.file(\"misc/dev-2.credentials\", package = \"REDCapR\") credential <- REDCapR::retrieve_credential_local( path_credential = path_credential, project_id = 62 )"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"one-redcapr-call-for-each-table","dir":"Articles","previous_headings":"Retrieving from REDCap","what":"One REDCapR Call for Each Table","title":"Retrieving Longitudinal and Repeating Structures","text":"tidy datasets represented Tables 1, 3a, 3b can obtained calling REDCapR three times –one call per table. Using forms parameter, pass “intake” get Table 1, “blood_pressure” get Table 3a, “laboratory” get Table 3b. Although required, recommend specifying readr::cols() object ensure desired variable data types.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"retrieve-patient-level-table-corresponding-to-table-1","dir":"Articles","previous_headings":"Retrieving from REDCap > One REDCapR Call for Each Table","what":"Retrieve patient-level table (corresponding to Table 1)","title":"Retrieving Longitudinal and Repeating Structures","text":"","code":"col_types_intake <- readr::cols_only( record_id = readr::col_integer(), height = readr::col_double(), weight = readr::col_double(), bmi = readr::col_double() ) ds_intake <- REDCapR::redcap_read( redcap_uri = credential$redcap_uri, # From the previous code snippet. token = credential$token, forms = c(\"intake\"), col_types = col_types_intake, verbose = FALSE, )$data ds_intake"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"retrieve-patient-time-level-tables-corresponding-to-tables-3a-3b","dir":"Articles","previous_headings":"Retrieving from REDCap > One REDCapR Call for Each Table","what":"Retrieve patient-time-level tables (corresponding to Tables 3a & 3b)","title":"Retrieving Longitudinal and Repeating Structures","text":"","code":"col_types_blood_pressure <- readr::cols( record_id = readr::col_integer(), redcap_repeat_instrument = readr::col_character(), redcap_repeat_instance = readr::col_integer(), sbp = readr::col_double(), dbp = readr::col_double(), blood_pressure_complete = readr::col_integer() ) ds_blood_pressure <- REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, forms = c(\"blood_pressure\"), col_types = col_types_blood_pressure, verbose = FALSE )$data ds_blood_pressure %>% tidyr::drop_na(redcap_repeat_instrument) col_types_laboratory <- readr::cols( record_id = readr::col_integer(), redcap_repeat_instrument = readr::col_character(), redcap_repeat_instance = readr::col_integer(), lab = readr::col_character(), conc = readr::col_character(), laboratory_complete = readr::col_integer() ) ds_laboratory <- REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, forms = c(\"laboratory\"), col_types = col_types_laboratory, verbose = FALSE )$data ds_laboratory %>% tidyr::drop_na(redcap_repeat_instrument)"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"retrieve-block-tables-corresponding-to-table-5","dir":"Articles","previous_headings":"Retrieving from REDCap > One REDCapR Call for Each Table","what":"Retrieve block tables (corresponding to Table 5)","title":"Retrieving Longitudinal and Repeating Structures","text":"reason need block dataset API, one call retrieve .","code":"ds_block <- REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, col_types = readr::cols(.default = readr::col_character()), verbose = FALSE, )$data ds_block"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"one-redcaptidier-call-for-all-tables","dir":"Articles","previous_headings":"Retrieving from REDCap","what":"One REDCapTidieR Call for All Tables","title":"Retrieving Longitudinal and Repeating Structures","text":"REDCapTidieR’s initial motivation facilitate longitudinal analyses promote tidy data hygiene. {Stephan Kadauke & Richard Hanna, please represent package wish. Tell ’ve positioned differently .}","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"choosing-between-the-approaches","dir":"Articles","previous_headings":"Retrieving from REDCap","what":"Choosing between the Approaches","title":"Retrieving Longitudinal and Repeating Structures","text":"retrieving data REDCap, recommend calling REDCapTidieR many scenarios, : new managing analyzing data R, analyses require dataset’s rows columns, ’d benefit auxiliary information REDCapTidieR’s supertibble, instrument’s structure. However recommend calling REDCapR scenarios. worth calling REDCapR multiple times : performing operation retrieving/reading data REDCap, comfortable managing analyzing data R, analyses require fraction data (() need first event, (b) analyses don’t involve instruments), want specify variables’ data types readr::cols(). doubt, start REDCapTidieR. Escalate REDCapR download time long might decreased reducing information retrieved server transported across network. course many scenarios solved best combination packages, () REDCapR populates initial demographics REDCap, (b) research staff enter measures collected patients time, (c) REDCapTidieR retrieves complete longitudinal dataset, (d) dplyr joins tibbles, finally (e) lme4 tests hypotheses involving patient trajectories time.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"escalating-to-redcapr","dir":"Articles","previous_headings":"Retrieving from REDCap","what":"Escalating to REDCapR","title":"Retrieving Longitudinal and Repeating Structures","text":"Even think ’ll need REDCapR’s low-level control, consider starting REDCapTidieR anyway. …particularly unsure specify grain table. structure REDCapTidieR’s tables easily compatible conventional analyses. need performance REDCapR unsure tables look, simply execute something like REDCapTidieR::redcap_read_tidy(url, project_token) study output. try mimic exactly REDCapR::redcap_read() calls. Finally, cull unwanted cells using parameters REDCapR::redcap_read(). data points even leave REDCap instance, improve performance. possible strategies include passing arguments forms: retrieve specified instruments/forms. Beginners start . easy conceptualize usually big increase speed just little development work. events: retrieve desired events within longitudinal project. instance analyses involve “intake” “follow #1” events, leave follow ups #2, #3, #4 server. fields: granular forms. can combined calls forms, passing \"bmi\" fields c(\"blood_pressure\", \"laboratory\") forms. records: example scenario, pluck individual patients associated events repeating instances. useful research, ’s usually combined REDCapR calls. See Read subset records, conditioned values variables section REDCapR’s Basic REDCapR Operations vignette. filter_logic: leverage observation values limit rows returned. underlying table index obs values, less computationally efficient options . datetime_range_begin & datetime_range_end: return records created modified specified window. Note efficiency gain moving block dataset REDCapTidieR different gain moving REDCapTidieR REDCapR. moving Table 5 REDCapTidieR Supertibble, eliminating empty cells never contain worthwhile data. moving REDCapTidieR Supertibble call collection REDCapR calls, eliminating cells contain data, may relevant analysis (patient’s name time lab specimen collected). {paragraph needs work.}","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"longitudinal","dir":"Articles","previous_headings":"Advanced","what":"Longitudinal","title":"Retrieving Longitudinal and Repeating Structures","text":"{TODO: Generalize argument longitudinal events}","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"caching-results-to-improve-performance","dir":"Articles","previous_headings":"Advanced","what":"Caching Results to Improve Performance","title":"Retrieving Longitudinal and Repeating Structures","text":"escalating REDCapR didn’t decrease duration enough, consider strategy calling REDCap per day (either package) saving results secured disk. efficient analyses require large dataset, real-time dataset. many retrospective projects, multiple analyses day can reuse dataset retrieved night (function like readr::write_rds()). helped complicated investigations multiple statisticians frantically tackle overlapping aspects funder’s deadline. Essentially transferring security responsibilities REDCap file server. balance advantages, approach’s drawbacks include: extra effort required create, secure, maintain networked drive accessible authorized analysts. take 15-60 minutes, depending institution. extra effort required create automated program retrieve cache dataset every night. See [CDS] head start. REDCap’s logs support meaningful audit human accessing API. User access audits now responsibility file system.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"caching-results-for-other-languages","dir":"Articles","previous_headings":"Advanced","what":"Caching Results for other Languages","title":"Retrieving Longitudinal and Repeating Structures","text":"Packages programming languages developed access REDCap’s API, PyCap PhpCap. Please see complete list https://redcap-tools.github.io/projects/. caching strategy described may also benefit investigation : uses language like SAS support packages. strongly discourage deploying loose scripts call API. something fixed original script, must distributed developer ~50 client institutions, must copied ~100 projects within institution. contrast, developer updates package distributed repository like CRAN, client needs run base::update.packages() per machine update packages –just REDCap packages. Data scientists already regularly. uses language like Julia lacks stable updated package. REDCap developers always releasing useful features (e.g., repeated measures) improve quality efficiency research. Leverage . investigation incorporates multiple programming languages like analysis team use consistent dataset. scenario, recommend code save R dataset multiple file formats, csv file feather file.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/longitudinal-and-repeating.html","id":"session-information","dir":"Articles","previous_headings":"","what":"Session Information","title":"Retrieving Longitudinal and Repeating Structures","text":"sake documentation reproducibility, current report rendered following environment. Click line expand.","code":"#> ─ Session info ─────────────────────────────────────────────────────────────── #> setting value #> version R version 4.4.2 (2024-10-31) #> os macOS Sonoma 14.7 #> system aarch64, darwin20 #> ui X11 #> language en #> collate en_US.UTF-8 #> ctype en_US.UTF-8 #> tz UTC #> date 2024-11-06 #> pandoc 3.1.11 @ /usr/local/bin/ (via rmarkdown) #> #> ─ Packages ─────────────────────────────────────────────────────────────────── #> package * version date (UTC) lib source #> backports 1.5.0 2024-05-23 [1] CRAN (R 4.4.0) #> bit 4.5.0 2024-09-20 [1] CRAN (R 4.4.1) #> bit64 4.5.2 2024-09-22 [1] CRAN (R 4.4.1) #> bslib 0.8.0 2024-07-29 [1] CRAN (R 4.4.0) #> cachem 1.1.0 2024-05-16 [1] CRAN (R 4.4.0) #> checkmate 2.3.2 2024-07-29 [1] CRAN (R 4.4.0) #> cli 3.6.3 2024-06-21 [1] CRAN (R 4.4.0) #> colorspace 2.1-1 2024-07-26 [1] CRAN (R 4.4.0) #> crayon 1.5.3 2024-06-20 [1] CRAN (R 4.4.0) #> curl 6.0.0 2024-11-05 [1] CRAN (R 4.4.1) #> desc 1.4.3 2023-12-10 [1] CRAN (R 4.4.0) #> digest 0.6.37 2024-08-19 [1] CRAN (R 4.4.1) #> dplyr 1.1.4 2023-11-17 [1] CRAN (R 4.4.0) #> evaluate 1.0.1 2024-10-10 [1] CRAN (R 4.4.1) #> fansi 1.0.6 2023-12-08 [1] CRAN (R 4.4.0) #> fastmap 1.2.0 2024-05-15 [1] CRAN (R 4.4.0) #> fs 1.6.5 2024-10-30 [1] CRAN (R 4.4.1) #> generics 0.1.3 2022-07-05 [1] CRAN (R 4.4.0) #> glue 1.8.0 2024-09-30 [1] CRAN (R 4.4.1) #> hms 1.1.3 2023-03-21 [1] CRAN (R 4.4.0) #> htmltools 0.5.8.1 2024-04-04 [1] CRAN (R 4.4.0) #> httr 1.4.7 2023-08-15 [1] CRAN (R 4.4.0) #> jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.4.0) #> jsonlite 1.8.9 2024-09-20 [1] CRAN (R 4.4.1) #> kableExtra 1.4.0 2024-01-24 [1] CRAN (R 4.4.0) #> knitr * 1.48 2024-07-07 [1] CRAN (R 4.4.0) #> lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.4.0) #> magrittr * 2.0.3 2022-03-30 [1] CRAN (R 4.4.0) #> munsell 0.5.1 2024-04-01 [1] CRAN (R 4.4.0) #> pillar 1.9.0 2023-03-22 [1] CRAN (R 4.4.0) #> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.4.0) #> pkgdown 2.1.1 2024-09-17 [1] CRAN (R 4.4.1) #> purrr 1.0.2 2023-08-10 [1] CRAN (R 4.4.0) #> R6 2.5.1 2021-08-19 [1] CRAN (R 4.4.0) #> ragg 1.3.3 2024-09-11 [1] CRAN (R 4.4.1) #> readr 2.1.5 2024-01-10 [1] CRAN (R 4.4.0) #> REDCapR 1.3.0.9000 2024-11-06 [1] local #> rlang 1.1.4 2024-06-04 [1] CRAN (R 4.4.0) #> rmarkdown 2.29 2024-11-04 [1] CRAN (R 4.4.1) #> rstudioapi 0.17.1 2024-10-22 [1] CRAN (R 4.4.1) #> sass 0.4.9 2024-03-15 [1] CRAN (R 4.4.0) #> scales 1.3.0 2023-11-28 [1] CRAN (R 4.4.0) #> sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.4.0) #> stringi 1.8.4 2024-05-06 [1] CRAN (R 4.4.0) #> stringr 1.5.1 2023-11-14 [1] CRAN (R 4.4.0) #> svglite 2.1.3 2023-12-08 [1] CRAN (R 4.4.0) #> systemfonts 1.1.0 2024-05-15 [1] CRAN (R 4.4.0) #> textshaping 0.4.0 2024-05-24 [1] CRAN (R 4.4.0) #> tibble 3.2.1 2023-03-20 [1] CRAN (R 4.4.0) #> tidyr 1.3.1 2024-01-24 [1] CRAN (R 4.4.0) #> tidyselect 1.2.1 2024-03-11 [1] CRAN (R 4.4.0) #> tzdb 0.4.0 2023-05-12 [1] CRAN (R 4.4.0) #> utf8 1.2.4 2023-10-22 [1] CRAN (R 4.4.0) #> vctrs 0.6.5 2023-12-01 [1] CRAN (R 4.4.0) #> viridisLite 0.4.2 2023-05-02 [1] CRAN (R 4.4.0) #> vroom 1.6.5 2023-12-05 [1] CRAN (R 4.4.0) #> withr 3.0.2 2024-10-28 [1] CRAN (R 4.4.1) #> xfun 0.49 2024-10-31 [1] CRAN (R 4.4.1) #> xml2 1.3.6 2023-12-04 [1] CRAN (R 4.4.0) #> yaml 2.3.10 2024-07-26 [1] CRAN (R 4.4.0) #> #> [1] /Users/runner/work/_temp/Library #> [2] /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library #> #> ──────────────────────────────────────────────────────────────────────────────"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"verify-redcapr-is-installed","dir":"Articles","previous_headings":"Part 1 - Pre-requisites","what":"Verify REDCapR is installed","title":"Typical REDCap Workflow for a Data Analyst","text":"First confirm REDCapR package installed local machine. , following line throw error Loading required namespace: REDCapR. Failed error: ‘package called ‘REDCapR’’. call fails, follow installation instructions REDCapR website. ’re workshop attendee, can use vignette copy snippets code local machine follow along examples: https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html.","code":"requireNamespace(\"REDCapR\") #> Loading required namespace: REDCapR # If this fails, run `install.packages(\"REDCapR\")` or `remotes::install_github(repo=\"OuhscBbmc/REDCapR\")`"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"verify-redcap-access","dir":"Articles","previous_headings":"Part 1 - Pre-requisites","what":"Verify REDCap Access","title":"Typical REDCap Workflow for a Data Analyst","text":"Check institution’s REDCap administrator ensure access REDCap server, access specific REDCap project, API token appropriate privileges specific REDCap project. might first time ’ve ever needed request token, institution may formal process API approval. REDCap admin can help. vignette, ’ll use fake dataset hosted https://redcap-dev-2.ouhsc.edu/redcap/api/ accessible token “9A068C425B1341D69E83064A2D273A70”. Note REDCap Admins: REDCapR::redcap_read() function properly, user must Export permissions ‘Full Data Set’. Users ‘De-Identified’ export privileges can still use REDCapR::redcap_read_oneshot(). grant appropriate permissions: go ‘User Rights’ REDCap project site, select desired user, select ‘Edit User Privileges’, ‘Data Exports’ radio buttons, select ‘Full Data Set’.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"review-codebook","dir":"Articles","previous_headings":"Part 1 - Pre-requisites","what":"Review Codebook","title":"Typical REDCap Workflow for a Data Analyst","text":"developing REDCap analysis code, spend least 10 minutes review codebook, whose link near top left corner REDCap project page, “Project Home Design” heading. Learning details save time later improve quality research. ’re new project, meet investigator least 30 minutes learn context, collection process, idiosyncrasies dataset. conversation, develop plan grooming dataset ready analysis. part standard advice analyst’s involvement start early investigation’s life span.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"part-2---retrieve-protected-token","dir":"Articles","previous_headings":"","what":"Part 2 - Retrieve Protected Token","title":"Typical REDCap Workflow for a Data Analyst","text":"REDCap API token essentially combination personal password ID specific project ’re requesting data . Protect like password PHI (protected health information). project PHI, never hard-code password directly R file. words, PHI project accessed R file includes line Instead, suggest storing token location can accessed . two recommendations.","code":"my_secret_token <- \"9A81268476645C4E5F03428B8AC3AA7B\""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"security-method-1-token-file","dir":"Articles","previous_headings":"Part 2 - Retrieve Protected Token","what":"Security Method 1: Token File","title":"Typical REDCap Workflow for a Data Analyst","text":"basic goals () separate secret values R file dedicated file (b) secure dedicated file. using git repository, prevent file committed entry .gitignore. Ask institution’s security team recommendation. retrieve_credential_local() function REDCapR package loads relevant information csv R. plain-text file might look like : retrieve credentials first project listed , pass value “33” project_id. credential file already created vignette. next real project, call create_credential_local() start well-formed csv file can contain tokens. Compared method , one less secure easier establish.","code":"redcap_uri,username,project_id,token,comment \"https://redcap-dev-2.ouhsc.edu/redcap/api/\",\"myusername\",\"33\",\"9A068C425B1341D69E83064A2D273A70\",\"simple\" \"https://redcap-dev-2.ouhsc.edu/redcap/api/\",\"myusername\",\"34\",\"DA6F2BB23146BD5A7EA3408C1A44A556\",\"longitudinal\" \"https://redcap-dev-2.ouhsc.edu/redcap/api/\",\"myusername\",\"36\",\"F9CBFFF78C3D78F641BAE9623F6B7E6A\",\"simple-write\" path_credential <- system.file(\"misc/dev-2.credentials\", package = \"REDCapR\") credential <- REDCapR::retrieve_credential_local( path_credential = path_credential, project_id = 33 ) credential #> $redcap_uri #> [1] \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" #> #> $username #> [1] \"myusername\" #> #> $project_id #> [1] 33 #> #> $token #> [1] \"9A068C425B1341D69E83064A2D273A70\" #> #> $comment #> [1] \"simple\""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"security-method-2-token-server","dir":"Articles","previous_headings":"Part 2 - Retrieve Protected Token","what":"Security Method 2: Token Server","title":"Typical REDCap Workflow for a Data Analyst","text":"preferred method involves saving tokens separate database uses something like Active Directory authenticate requests. method described detail Security Database vignette. approach realistically requires someone institution least basic database administration experience.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"part-3---read-data-unstructured-approach","dir":"Articles","previous_headings":"","what":"Part 3 - Read Data: Unstructured Approach","title":"Typical REDCap Workflow for a Data Analyst","text":"redcap_uri token fields required arguments REDCapR::redcap_read(); credential object created previous section. point, data.frame ds_1 everything need start analyzing project. Pause workshop minutes. Raise hand ’re trouble.","code":"ds_1 <- REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token )$data #> 24 variable metadata records were read from REDCap in 0.3 seconds. The http status code was 200. #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. #> 3 instrument metadata records were read from REDCap in 0.2 seconds. The http status code was 200. #> 1 rows were read from REDCap in 0.2 seconds. The http status code was 200. #> 2 data access groups were read from REDCap in 0.2 seconds. The http status code was 200. #> 5 records and 1 columns were read from REDCap in 0.2 seconds. The http status code was 200. #> Starting to read 5 records at 2024-11-06 13:24:13.457158. #> Reading batch 1 of 1, with subjects 1 through 5 (ie, 5 unique subject records). #> 5 records and 25 columns were read from REDCap in 0.2 seconds. The http status code was 200. ds_1 #> # A tibble: 5 × 25 #> record_id name_first name_last address telephone email dob age sex #> #> 1 1 Nutmeg Nutmouse \"14 Ros… (405) 32… nutt… 2003-08-30 11 0 #> 2 2 Tumtum Nutmouse \"14 Ros… (405) 32… tumm… 2003-03-10 11 1 #> 3 3 Marcus Wood \"243 Hi… (405) 32… mw@m… 1934-04-09 80 1 #> 4 4 Trudy DAG \"342 El… (405) 32… pero… 1952-11-02 61 0 #> 5 5 John Lee Walker \"Hotel … (405) 32… left… 1955-04-15 59 1 #> # ℹ 16 more variables: demographics_complete , height , weight , #> # bmi , comments , mugshot , health_complete , #> # race___1 , race___2 , race___3 , race___4 , #> # race___5 , race___6 , ethnicity , interpreter_needed , #> # race_and_ethnicity_complete hist(ds_1$weight) summary(ds_1) #> record_id name_first name_last address #> Min. :1 Length:5 Length:5 Length:5 #> 1st Qu.:2 Class :character Class :character Class :character #> Median :3 Mode :character Mode :character Mode :character #> Mean :3 #> 3rd Qu.:4 #> Max. :5 #> #> telephone email dob age #> Length:5 Length:5 Min. :1934-04-09 Min. :11.0 #> Class :character Class :character 1st Qu.:1952-11-02 1st Qu.:11.0 #> Mode :character Mode :character Median :1955-04-15 Median :59.0 #> Mean :1969-11-06 Mean :44.4 #> 3rd Qu.:2003-03-10 3rd Qu.:61.0 #> Max. :2003-08-30 Max. :80.0 #> #> sex demographics_complete height weight #> Min. :0.0 Min. :2 Min. : 6.0 Min. : 1 #> 1st Qu.:0.0 1st Qu.:2 1st Qu.: 7.0 1st Qu.: 1 #> Median :1.0 Median :2 Median :165.0 Median : 54 #> Mean :0.6 Mean :2 Mean :110.2 Mean : 48 #> 3rd Qu.:1.0 3rd Qu.:2 3rd Qu.:180.0 3rd Qu.: 80 #> Max. :1.0 Max. :2 Max. :193.0 Max. :104 #> #> bmi comments mugshot health_complete #> Min. : 19.8 Length:5 Length:5 Min. :0 #> 1st Qu.: 24.7 Class :character Class :character 1st Qu.:0 #> Median : 27.9 Mode :character Mode :character Median :1 #> Mean :110.9 Mean :1 #> 3rd Qu.:204.1 3rd Qu.:2 #> Max. :277.8 Max. :2 #> #> race___1 race___2 race___3 race___4 race___5 #> Min. :0.0 Min. :0.0 Min. :0.0 Min. :0.0 Min. :0.0 #> 1st Qu.:0.0 1st Qu.:0.0 1st Qu.:0.0 1st Qu.:0.0 1st Qu.:1.0 #> Median :0.0 Median :0.0 Median :0.0 Median :0.0 Median :1.0 #> Mean :0.2 Mean :0.2 Mean :0.2 Mean :0.2 Mean :0.8 #> 3rd Qu.:0.0 3rd Qu.:0.0 3rd Qu.:0.0 3rd Qu.:0.0 3rd Qu.:1.0 #> Max. :1.0 Max. :1.0 Max. :1.0 Max. :1.0 Max. :1.0 #> #> race___6 ethnicity interpreter_needed race_and_ethnicity_complete #> Min. :0.0 Min. :0 Min. :0.00 Min. :0.0 #> 1st Qu.:0.0 1st Qu.:1 1st Qu.:0.00 1st Qu.:2.0 #> Median :0.0 Median :1 Median :0.00 Median :2.0 #> Mean :0.2 Mean :1 Mean :0.25 Mean :1.6 #> 3rd Qu.:0.0 3rd Qu.:1 3rd Qu.:0.25 3rd Qu.:2.0 #> Max. :1.0 Max. :2 Max. :1.00 Max. :2.0 #> NA's :1 summary(lm(age ~ 1 + sex + bmi, data = ds_1)) #> #> Call: #> lm(formula = age ~ 1 + sex + bmi, data = ds_1) #> #> Residuals: #> 1 2 3 4 5 #> -2.491 1.954 9.132 2.491 -11.086 #> #> Coefficients: #> Estimate Std. Error t value Pr(>|t|) #> (Intercept) 63.34496 8.89980 7.118 0.0192 * #> sex 13.55626 9.62958 1.408 0.2945 #> bmi -0.24426 0.04337 -5.632 0.0301 * #> --- #> Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 #> #> Residual standard error: 10.55 on 2 degrees of freedom #> Multiple R-squared: 0.9442, Adjusted R-squared: 0.8884 #> F-statistic: 16.92 on 2 and 2 DF, p-value: 0.05581"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"part-4---read-data-choosing-columns-and-rows","dir":"Articles","previous_headings":"","what":"Part 4 - Read Data: Choosing Columns and Rows","title":"Typical REDCap Workflow for a Data Analyst","text":"read dataset first time, probably haven’t decided columns needed makes sense retrieve everything. gain familiarity data analytic objectives, consider selective variables rows transported remote server local machine. Advantages include: server almost always efficient filtering language like R Python. REDCap’s PHP code retrieves less data REDCap’s database translates less text format (like csv json). Fewer bytes transmitted across network. local machine better performance, R smaller dataset manage. brain doesn’t look past unnecessary columns. R code doesn’t filter server already removed. Highly-sensitive PHI columns unnecessary analysis remain server.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"specify-record-ids","dir":"Articles","previous_headings":"Part 4 - Read Data: Choosing Columns and Rows","what":"Specify Record IDs","title":"Typical REDCap Workflow for a Data Analyst","text":"basic operation limit rows passing exact record identifiers.","code":"# Return only records with IDs of 1 and 4 desired_records <- c(1, 4) REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, records = desired_records, verbose = FALSE )$data #> # A tibble: 2 × 25 #> record_id name_first name_last address telephone email dob age sex #> #> 1 1 Nutmeg Nutmouse \"14 Ros… (405) 32… nutt… 2003-08-30 11 0 #> 2 4 Trudy DAG \"342 El… (405) 32… pero… 1952-11-02 61 0 #> # ℹ 16 more variables: demographics_complete , height , weight , #> # bmi , comments , mugshot , health_complete , #> # race___1 , race___2 , race___3 , race___4 , #> # race___5 , race___6 , ethnicity , interpreter_needed , #> # race_and_ethnicity_complete "},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"specify-row-filter","dir":"Articles","previous_headings":"Part 4 - Read Data: Choosing Columns and Rows","what":"Specify Row Filter","title":"Typical REDCap Workflow for a Data Analyst","text":"useful operation limit rows passing expression filter records returning. See server’s documentation syntax rules filter statements. Remember enclose variable names square brackets. Also aware differences strings numbers.","code":"# Return only records with a birth date after January 2003 REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, filter_logic = \"'2003-01-01' < [dob]\", verbose = FALSE )$data #> # A tibble: 2 × 25 #> record_id name_first name_last address telephone email dob age sex #> #> 1 1 Nutmeg Nutmouse \"14 Ros… (405) 32… nutt… 2003-08-30 11 0 #> 2 2 Tumtum Nutmouse \"14 Ros… (405) 32… tumm… 2003-03-10 11 1 #> # ℹ 16 more variables: demographics_complete , height , weight , #> # bmi , comments , mugshot , health_complete , #> # race___1 , race___2 , race___3 , race___4 , #> # race___5 , race___6 , ethnicity , interpreter_needed , #> # race_and_ethnicity_complete "},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"specify-column-names","dir":"Articles","previous_headings":"Part 4 - Read Data: Choosing Columns and Rows","what":"Specify Column Names","title":"Typical REDCap Workflow for a Data Analyst","text":"Limit returned fields passing vector desired names.","code":"# Return only the fields record_id, name_first, and age desired_fields <- c(\"record_id\", \"name_first\", \"age\") REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, fields = desired_fields, verbose = FALSE )$data #> # A tibble: 5 × 3 #> 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"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"part-5---read-data-structured-approach","dir":"Articles","previous_headings":"","what":"Part 5 - Read Data: Structured Approach","title":"Typical REDCap Workflow for a Data Analyst","text":"automation scripts matures institutional resources depend output, output stable. One way make predictable specify column names column data types. previous example, notice R (specifically readr::read_csv()) made best guess reported “Column specification” section. following example, REDCapR passes col_types readr::read_csv() converts plain-text output returned REDCap R data frame. (precise, tibble returned.) readr sees column values like 1, 2, 3, 4, make reasonable guess column double precision floating-point data type. However recommend using simplest data type reasonable simpler data type less likely contain unintended values ’s typically faster, consumes less memory, translates cleanly across platforms. specifically identifiers like record_id specify either integer character.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"specify-column-names-types","dir":"Articles","previous_headings":"Part 5 - Read Data: Structured Approach","what":"Specify Column Names & Types","title":"Typical REDCap Workflow for a Data Analyst","text":"","code":"# Specify the column types. desired_fields <- c(\"record_id\", \"race\") 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() ) REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, fields = desired_fields, verbose = FALSE, col_types = col_types )$data #> # A tibble: 5 × 7 #> record_id race___1 race___2 race___3 race___4 race___5 race___6 #> #> 1 1 FALSE FALSE FALSE FALSE TRUE FALSE #> 2 2 FALSE FALSE TRUE FALSE TRUE FALSE #> 3 3 FALSE FALSE FALSE TRUE TRUE FALSE #> 4 4 FALSE TRUE FALSE FALSE TRUE FALSE #> 5 5 TRUE FALSE FALSE FALSE FALSE TRUE"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"specify-everything-is-a-character","dir":"Articles","previous_headings":"Part 5 - Read Data: Structured Approach","what":"Specify Everything is a Character","title":"Typical REDCap Workflow for a Data Analyst","text":"REDCap internally stores every value string. accept full responsibility data types, tell readr::cols() keep strings.","code":"# Specify the column types. desired_fields <- c(\"record_id\", \"race\") col_types <- readr::cols(.default = readr::col_character()) REDCapR::redcap_read( redcap_uri = credential$redcap_uri, token = credential$token, fields = desired_fields, verbose = FALSE, col_types = col_types )$data #> # A tibble: 5 × 7 #> record_id race___1 race___2 race___3 race___4 race___5 race___6 #> #> 1 1 0 0 0 0 1 0 #> 2 2 0 0 1 0 1 0 #> 3 3 0 0 0 1 1 0 #> 4 4 0 1 0 0 1 0 #> 5 5 1 0 0 0 0 1"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"other-redcapr-resources","dir":"Articles","previous_headings":"Part 6 - Next Steps","what":"Other REDCapR Resources","title":"Typical REDCap Workflow for a Data Analyst","text":"addition documentation function REDCapR package contains handful vignettes including troubleshooting guide.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"create-an-arch-for-reuse","dir":"Articles","previous_headings":"Part 6 - Next Steps","what":"Create an Arch for Reuse","title":"Typical REDCap Workflow for a Data Analyst","text":"multiple R files use REDCapR call REDCap dataset, consider refactoring scripts extraction code written , called multiple analysis files. “arch” pattern described slides 9-16 2014 REDCapCon presentation, Literate Programming Patterns Practices Continuous Quality Improvement (CQI).","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"downstream-reproducible-reports","dir":"Articles","previous_headings":"Part 6 - Next Steps","what":"Downstream Reproducible Reports","title":"Typical REDCap Workflow for a Data Analyst","text":"dataset R, take advantage reproducible research tools available. Tomorrow, R/Medicine workshop topic using exciting new Quarto program ’s similar R Markdown. Also see relevant R/Medicine 2020 presentation videos. course, book Yihui Xie colleagues.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"batching","dir":"Articles","previous_headings":"Part 6 - Next Steps","what":"Batching","title":"Typical REDCap Workflow for a Data Analyst","text":"default, REDCapR::redcap_read() requests datasets 100 patients time, stacks resulting subsets together returning data.frame. can adjusted improve performance; ‘Details’ section REDCapR::redcap_read() discusses trade offs.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"writing-to-the-server","dir":"Articles","previous_headings":"Part 6 - Next Steps","what":"Writing to the Server","title":"Typical REDCap Workflow for a Data Analyst","text":"Reading record data one API capability. REDCapR exposes 20+ API functions, reading metadata, retrieving survey links, writing records back REDCap. last operation relevant Kenneth McLean’s presentation following five-minute break.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"notes","dir":"Articles","previous_headings":"","what":"Notes","title":"Typical REDCap Workflow for a Data Analyst","text":"vignette originally designed 2021 R/Medicine REDCap workshop Peter Higgins, Amanda Miller, Kenneth McLean. work made possible part NIH grant U54GM104938 Oklahoma Shared Clinical Translational Resource).","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html","id":"session-information","dir":"Articles","previous_headings":"","what":"Session Information","title":"Typical REDCap Workflow for a Data Analyst","text":"sake documentation reproducibility, current report rendered following environment. Click line expand.","code":"#> ─ Session info ─────────────────────────────────────────────────────────────── #> setting value #> version R version 4.4.2 (2024-10-31) #> os macOS Sonoma 14.7 #> system aarch64, darwin20 #> ui X11 #> language en #> collate en_US.UTF-8 #> ctype en_US.UTF-8 #> tz UTC #> date 2024-11-06 #> pandoc 3.1.11 @ /usr/local/bin/ (via rmarkdown) #> #> ─ Packages ─────────────────────────────────────────────────────────────────── #> package * version date (UTC) lib source #> backports 1.5.0 2024-05-23 [1] CRAN (R 4.4.0) #> bit 4.5.0 2024-09-20 [1] CRAN (R 4.4.1) #> bit64 4.5.2 2024-09-22 [1] CRAN (R 4.4.1) #> bslib 0.8.0 2024-07-29 [1] CRAN (R 4.4.0) #> cachem 1.1.0 2024-05-16 [1] CRAN (R 4.4.0) #> checkmate 2.3.2 2024-07-29 [1] CRAN (R 4.4.0) #> cli 3.6.3 2024-06-21 [1] CRAN (R 4.4.0) #> crayon 1.5.3 2024-06-20 [1] CRAN (R 4.4.0) #> curl 6.0.0 2024-11-05 [1] CRAN (R 4.4.1) #> desc 1.4.3 2023-12-10 [1] CRAN (R 4.4.0) #> digest 0.6.37 2024-08-19 [1] CRAN (R 4.4.1) #> dplyr 1.1.4 2023-11-17 [1] CRAN (R 4.4.0) #> evaluate 1.0.1 2024-10-10 [1] CRAN (R 4.4.1) #> fansi 1.0.6 2023-12-08 [1] CRAN (R 4.4.0) #> fastmap 1.2.0 2024-05-15 [1] CRAN (R 4.4.0) #> fs 1.6.5 2024-10-30 [1] CRAN (R 4.4.1) #> generics 0.1.3 2022-07-05 [1] CRAN (R 4.4.0) #> glue 1.8.0 2024-09-30 [1] CRAN (R 4.4.1) #> highr 0.11 2024-05-26 [1] CRAN (R 4.4.0) #> hms 1.1.3 2023-03-21 [1] CRAN (R 4.4.0) #> htmltools 0.5.8.1 2024-04-04 [1] CRAN (R 4.4.0) #> httr 1.4.7 2023-08-15 [1] CRAN (R 4.4.0) #> jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.4.0) #> jsonlite 1.8.9 2024-09-20 [1] CRAN (R 4.4.1) #> knitr 1.48 2024-07-07 [1] CRAN (R 4.4.0) #> lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.4.0) #> magrittr 2.0.3 2022-03-30 [1] CRAN (R 4.4.0) #> pillar 1.9.0 2023-03-22 [1] CRAN (R 4.4.0) #> pkgconfig 2.0.3 2019-09-22 [1] CRAN (R 4.4.0) #> pkgdown 2.1.1 2024-09-17 [1] CRAN (R 4.4.1) #> R6 2.5.1 2021-08-19 [1] CRAN (R 4.4.0) #> ragg 1.3.3 2024-09-11 [1] CRAN (R 4.4.1) #> readr 2.1.5 2024-01-10 [1] CRAN (R 4.4.0) #> REDCapR 1.3.0.9000 2024-11-06 [1] local #> rlang 1.1.4 2024-06-04 [1] CRAN (R 4.4.0) #> rmarkdown 2.29 2024-11-04 [1] CRAN (R 4.4.1) #> sass 0.4.9 2024-03-15 [1] CRAN (R 4.4.0) #> sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.4.0) #> systemfonts 1.1.0 2024-05-15 [1] CRAN (R 4.4.0) #> textshaping 0.4.0 2024-05-24 [1] CRAN (R 4.4.0) #> tibble 3.2.1 2023-03-20 [1] CRAN (R 4.4.0) #> tidyselect 1.2.1 2024-03-11 [1] CRAN (R 4.4.0) #> tzdb 0.4.0 2023-05-12 [1] CRAN (R 4.4.0) #> utf8 1.2.4 2023-10-22 [1] CRAN (R 4.4.0) #> vctrs 0.6.5 2023-12-01 [1] CRAN (R 4.4.0) #> vroom 1.6.5 2023-12-05 [1] CRAN (R 4.4.0) #> withr 3.0.2 2024-10-28 [1] CRAN (R 4.4.1) #> xfun 0.49 2024-10-31 [1] CRAN (R 4.4.1) #> yaml 2.3.10 2024-07-26 [1] CRAN (R 4.4.0) #> #> [1] /Users/runner/work/_temp/Library #> [2] /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library #> #> ──────────────────────────────────────────────────────────────────────────────"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"strategy","dir":"Articles","previous_headings":"Part 1 - Intro","what":"Strategy","title":"Writing to a REDCap Project","text":"described Retrieving Longitudinal Repeating Structures vignette, best way read write data projects longitudinal/repeating elements break “block matrix” dataset individual datasets. rectangle coherent grain. Following strategy, ’ll write REDCap server two distinct steps: Upload patient-level instrument(s) Upload repeating instrument separately. actual upload phase pretty straight-forward –’s just call REDCapR::redcap_write(). vignette’s code prepares dataset upload run smoothly.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"pre-requisites","dir":"Articles","previous_headings":"Part 1 - Intro","what":"Pre-requisites","title":"Writing to a REDCap Project","text":"See Typical REDCap Workflow Data Analyst vignette Verify REDCapR installed Verify REDCap Access Review Codebook","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"retrieve-token","dir":"Articles","previous_headings":"Part 1 - Intro","what":"Retrieve Token","title":"Writing to a REDCap Project","text":"Please closely read Retrieve Protected Token section, important security implications. current vignette imports fake dataset REDCap, ’ll use token stored local file.","code":"# retrieve-credential path_credential <- system.file(\"misc/dev-2.credentials\", package = \"REDCapR\") credential <- REDCapR::retrieve_credential_local( path_credential = path_credential, project_id = 3748 ) c(credential$redcap_uri, credential$token)"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"datasets-to-write-to-server","dir":"Articles","previous_headings":"Part 1 - Intro","what":"Datasets to Write to Server","title":"Writing to a REDCap Project","text":"keep vignette focused writing/importing/uploading server, ’ll start data needs written. example tables prepared Raymond Balise 2023 R/Medicine workshop, “Using REDCap R Rapidly Produce Biomedical Publications”. two tables, different granularity: ds_patient: row represents one patient, ds_daily: row represents one daily measurement per patient.","code":"# load-patient ds_patient <- \"test-data/vignette-repeating-write/data-patient.rds\" |> system.file(package = \"REDCapR\") |> readr::read_rds() ds_patient # load-repeating ds_daily <- \"test-data/vignette-repeating-write/data-daily.rds\" |> system.file(package = \"REDCapR\") |> readr::read_rds() ds_daily"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"part-2---write-data-one-row-per-patient","dir":"Articles","previous_headings":"","what":"Part 2 - Write Data: One row per patient","title":"Writing to a REDCap Project","text":"Besides data.frame write REDCap, required arguments REDCapR::redcap_write() function redcap_uri token; contained credential object created previous section. discussed Troubleshooting vignette, recommend running two preliminary checks trying write dataset server first time.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"prep-stoplight-fields","dir":"Articles","previous_headings":"Part 2 - Write Data: One row per patient","what":"Prep: Stoplight Fields","title":"Writing to a REDCap Project","text":"REDCap project isn’t longitudinal doesn’t arms, uploading patient-level data.frame REDCap doesn’t require adding variables. However typically populate *_complete variables communicate record’s status. row needs human add values inspect existing values consider marking instrument “incomplete” “unverified”; patient’s instrument record appear red yellow REDCap’s Record Dashboard. Otherwise consider marking instrument “complete” appear green. example project, patient-level instrument “enrollment”, corresponding variable enrollment_complete.","code":"# patient-complete ds_patient <- ds_patient |> dplyr::mutate( enrollment_complete = REDCapR::constant(\"form_complete\"), )"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"prep-redcaprvalidate_for_write","dir":"Articles","previous_headings":"Part 2 - Write Data: One row per patient","what":"Prep: REDCapR::validate_for_write()","title":"Writing to a REDCap Project","text":"REDCapR::validate_for_write() inspects data frame anticipate potential problems writing REDCap’s API. tibble returned, one row per potential problem (suggestion avoid ). Ideally 0-row tibble returned. encounter problems can checked automation, please tell us issue. ’ll work incorporate new check REDCapR::validate_for_write(). dataset’s problems caught reaching server, solutions easier identify implement.","code":"REDCapR::validate_for_write(ds_patient, convert_logical_to_integer = TRUE)"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"prep-write-small-subset-first","dir":"Articles","previous_headings":"Part 2 - Write Data: One row per patient","what":"Prep: Write Small Subset First","title":"Writing to a REDCap Project","text":"first time complicated project, consider loading small subset rows columns. case, start three columns two rows.","code":"# patient-subset ds_patient |> dplyr::select( # First three columns id_code, date, is_mobile, ) |> dplyr::slice(1:2) |> # First two rows REDCapR::redcap_write( ds_to_write = _, redcap_uri = credential$redcap_uri, token = credential$token, convert_logical_to_integer = TRUE )"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"prep-recode-variables-where-necessary","dir":"Articles","previous_headings":"Part 2 - Write Data: One row per patient","what":"Prep: Recode Variables where Necessary","title":"Writing to a REDCap Project","text":"variables data.frame might represented differently REDCap. common transformation changing strings integers underlie radio buttons. Common approaches dplyr::case_match() using joining lookup tables (mappings expressed csv). ’s -line example dplyr::case_match().","code":"ds_patient <- ds_patient |> dplyr::mutate( race = dplyr::case_match( race, \"White\" ~ 1L, \"Black or African American\" ~ 2L, \"Asian\" ~ 3L, \"Native American\" ~ 4L, \"Pacific Islander\" ~ 5L, \"Multiracial\" ~ 6L, \"Refused or don't know\" ~ 7L ) )"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"write-entire-patient-level-table","dir":"Articles","previous_headings":"Part 2 - Write Data: One row per patient","what":"Write Entire Patient-level Table","title":"Writing to a REDCap Project","text":"small subset works, usually jump ahead try columns rows. larger table fails, split difference () smaller working example (b) larger failing example. See middle point (fewer rows /columns failing point) succeeds fails. repeat. “bisection” “binary search” debugging technique helpful many areas programming statistical modeling.","code":"# patient-entire ds_patient |> REDCapR::redcap_write( ds_to_write = _, redcap_uri = credential$redcap_uri, token = credential$token, convert_logical_to_integer = TRUE )"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"add-plumbing-variables","dir":"Articles","previous_headings":"Part 3 - Write Data: Repeating Instrument","what":"Add Plumbing Variables","title":"Writing to a REDCap Project","text":"stated vignette’s intro, structure dataset uploaded server must precise. uploading repeating instruments, several important columns: record_id: typically indicates patient’s id. (field can renamed project.) redcap_event_name: project longitudinal arms, indicates event. Otherwise, don’t need add variable. redcap_repeat_instrument: Indicates instrument/form repeating columns. redcap_repeat_instance: Typically sequential positive integer (e.g., 1, 2, 3, …) indicating order. combination variables needs unique. Please read Retrieving Longitudinal Repeating Structures vignette details variables meanings. need pass specific variables REDCap server understands hierarchical structure data points.","code":"# repeat-plumbing ds_daily <- ds_daily |> dplyr::group_by(id_code) |> dplyr::mutate( redcap_repeat_instrument = \"daily\", redcap_repeat_instance = dplyr::row_number(da_date), daily_complete = REDCapR::constant(\"form_complete\"), ) |> dplyr::ungroup() |> dplyr::select( id_code, # Or `record_id`, if you didn't rename it # redcap_event_name, # If the project is longitudinal or has arms redcap_repeat_instrument, # The name of the repeating instrument/form redcap_repeat_instance, # The sequence of the repeating instrument tidyselect::everything(), # All columns not explicitly passed to `dplyr::select()` daily_complete, # Indicates incomplete, unverified, or complete ) # Check for potential problems. (Remember zero rows are good.) REDCapR::validate_for_write(ds_daily, convert_logical_to_integer = TRUE) ds_daily"},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"writing-repeating-instrument-variables","dir":"Articles","previous_headings":"Part 3 - Write Data: Repeating Instrument","what":"Writing Repeating Instrument Variables","title":"Writing to a REDCap Project","text":"","code":"# daily-entire ds_daily |> REDCapR::redcap_write( ds_to_write = _, redcap_uri = credential$redcap_uri, token = credential$token, convert_logical_to_integer = TRUE )"},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"more-complexity","dir":"Articles","previous_headings":"Part 4 - Next Steps","what":"More Complexity","title":"Writing to a REDCap Project","text":"vignette required two data.frames, complex projects sometimes need . example, repeating instrument data.frame writing step. Arms longitudinal events need considered .","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"batching","dir":"Articles","previous_headings":"Part 4 - Next Steps","what":"Batching","title":"Writing to a REDCap Project","text":"default, REDCapR::redcap_write() requests datasets 100 patients time, stacks resulting subsets together returning data.frame. can adjusted improve performance; ‘Details’ section REDCapR::redcap_write() discusses trade offs. usually shoot ~10 seconds per batch.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"manual-vs-api","dir":"Articles","previous_headings":"Part 4 - Next Steps","what":"Manual vs API","title":"Writing to a REDCap Project","text":"Manual downloading/uploading might make sense ’re operation . ever stop first time? trouble uploading, consider adding fake patients & measurements download csv. might reveal something didn’t anticipate. aware block matrix format (.e., everything jammed one rectangle.)","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"redcaps-cdis","dir":"Articles","previous_headings":"Part 4 - Next Steps","what":"REDCap’s CDIS","title":"Writing to a REDCap Project","text":"Clinical Data Interoperability Services (CDIS) use FHIR move data institution’s EMR/EHR (eg, Epic, Cerner) REDCap. Research staff control patient records selected eligible. Conceptually ’s similar writing REDCap’s API, much bigger scale. Realistically, takes months get institution’s human layers. established, project populated EMR data much less development time –assuming desired data models corresponds FHIR endpoints.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"notes","dir":"Articles","previous_headings":"","what":"Notes","title":"Writing to a REDCap Project","text":"vignette originally designed 2023 R/Medicine workshop, Using REDCap R Rapidly Produce Biomedical Publications Cleaning Medical Data Raymond R. Balise, Belén Hervera, Daniel Maya, Anna Calderon, Tyler Bartholomew, Stephan Kadauke, João Pedro Carmezim Correia 2024 R/Medicine workshop, REDCap + R: Teaming Tidyverse, Stephan Kadauke. workshop slides 2023 2024. work made possible part NIH grant U54GM104938 Oklahoma Shared Clinical Translational Resource).","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/articles/workflow-write.html","id":"session-information","dir":"Articles","previous_headings":"","what":"Session Information","title":"Writing to a REDCap Project","text":"sake documentation reproducibility, current report rendered following environment. Click line expand.","code":"#> ─ Session info ─────────────────────────────────────────────────────────────── #> setting value #> version R version 4.4.2 (2024-10-31) #> os macOS Sonoma 14.7 #> system aarch64, darwin20 #> ui X11 #> language en #> collate en_US.UTF-8 #> ctype en_US.UTF-8 #> tz UTC #> date 2024-11-06 #> pandoc 3.1.11 @ /usr/local/bin/ (via rmarkdown) #> #> ─ Packages ─────────────────────────────────────────────────────────────────── #> package * version date (UTC) lib source #> bslib 0.8.0 2024-07-29 [1] CRAN (R 4.4.0) #> cachem 1.1.0 2024-05-16 [1] CRAN (R 4.4.0) #> cli 3.6.3 2024-06-21 [1] CRAN (R 4.4.0) #> desc 1.4.3 2023-12-10 [1] CRAN (R 4.4.0) #> digest 0.6.37 2024-08-19 [1] CRAN (R 4.4.1) #> evaluate 1.0.1 2024-10-10 [1] CRAN (R 4.4.1) #> fastmap 1.2.0 2024-05-15 [1] CRAN (R 4.4.0) #> fs 1.6.5 2024-10-30 [1] CRAN (R 4.4.1) #> highr 0.11 2024-05-26 [1] CRAN (R 4.4.0) #> htmltools 0.5.8.1 2024-04-04 [1] CRAN (R 4.4.0) #> jquerylib 0.1.4 2021-04-26 [1] CRAN (R 4.4.0) #> jsonlite 1.8.9 2024-09-20 [1] CRAN (R 4.4.1) #> knitr 1.48 2024-07-07 [1] CRAN (R 4.4.0) #> lifecycle 1.0.4 2023-11-07 [1] CRAN (R 4.4.0) #> pkgdown 2.1.1 2024-09-17 [1] CRAN (R 4.4.1) #> R6 2.5.1 2021-08-19 [1] CRAN (R 4.4.0) #> ragg 1.3.3 2024-09-11 [1] CRAN (R 4.4.1) #> rlang 1.1.4 2024-06-04 [1] CRAN (R 4.4.0) #> rmarkdown 2.29 2024-11-04 [1] CRAN (R 4.4.1) #> sass 0.4.9 2024-03-15 [1] CRAN (R 4.4.0) #> sessioninfo 1.2.2 2021-12-06 [1] CRAN (R 4.4.0) #> systemfonts 1.1.0 2024-05-15 [1] CRAN (R 4.4.0) #> textshaping 0.4.0 2024-05-24 [1] CRAN (R 4.4.0) #> xfun 0.49 2024-10-31 [1] CRAN (R 4.4.1) #> yaml 2.3.10 2024-07-26 [1] CRAN (R 4.4.0) #> #> [1] /Users/runner/work/_temp/Library #> [2] /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/library #> #> ──────────────────────────────────────────────────────────────────────────────"},{"path":"https://ouhscbbmc.github.io/REDCapR/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Beasley. Author, maintainer. David Bard. Contributor. Thomas Wilson. Contributor. John J Aponte. Contributor. Rollie Parrish. Contributor. Benjamin Nutter. Contributor. Andrew Peters. Contributor. Hao Zhu. Contributor. Janosch Linkersdörfer. Contributor. Jonathan Mang. Contributor. Felix Torres. Contributor. Philip Chase. Contributor. Victor Castro. Contributor. Greg Botwin. Contributor. Stephan Kadauke. Contributor. Ezra Porter. Contributor. Matthew Schuelke. Contributor.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Beasley W (2024). REDCapR: Interaction R REDCap. R package version 1.3.0.9000, https://github.com/OuhscBbmc/REDCapR, https://www.ouhsc.edu/bbmc/, https://projectredcap.org, https://ouhscbbmc.github.io/REDCapR/.","code":"@Manual{, title = {REDCapR: Interaction Between R and REDCap}, author = {Will Beasley}, year = {2024}, note = {R package version 1.3.0.9000, https://github.com/OuhscBbmc/REDCapR, https://www.ouhsc.edu/bbmc/, https://projectredcap.org}, url = {https://ouhscbbmc.github.io/REDCapR/}, }"},{"path":"https://ouhscbbmc.github.io/REDCapR/index.html","id":"redcapr-","dir":"","previous_headings":"","what":"Interaction Between R and REDCap","title":"Interaction Between R and REDCap","text":"’ve using R REDCap’s API since 2012 developed REDCapR. encapsulating functions package, replicating 50+ lines code contact REDCap robustly transform returned csv R data.frame; took twice much implement batching. can done one call redcap_read(): redcap_read() function also accepts values subsetting/filtering records fields. two examples; first selects portion rows, second selects portion columns. Documentation additional 20+ functions found ouhscbbmc.github.io/REDCapR/reference. REDCapR package includes SSL certificate retrieved httr::find_cert_bundle(). REDCap server’s identity always verified, unless setting overridden (alternative certificates can also provided). keep maintenance efforts manageable, package implements REDCap API functions requested. ’s feature help projects, please tell us new issue REDCapR’s GitHub repository. troubleshooting document helps diagnose issues API.","code":"ds <- redcap_read(redcap_uri=uri, token=token)$data # Return only records with IDs of 1 and 4 desired_records <- c(1, 4) ds_some_rows <- redcap_read( redcap_uri = uri, token = token, records = desired_records )$data # Return only the fields record_id, name_first, and age desired_fields <- c(\"record_id\", \"name_first\", \"age\") ds_some_fields <- redcap_read( redcap_uri = uri, token = token, fields = desired_fields )$data"},{"path":"https://ouhscbbmc.github.io/REDCapR/index.html","id":"installation-and-documentation","dir":"","previous_headings":"","what":"Installation and Documentation","title":"Interaction Between R and REDCap","text":"release version can installed CRAN. development version can installed GitHub installing remotes package. ouhscbbmc.github.io/REDCapR site describes package functions, includes documents involving basic operations, advanced operations, token security, troubleshooting. Also checkout packages exist communicating REDCap, listed REDCap Tools directory.","code":"install.packages(\"REDCapR\") install.packages(\"remotes\") # Run this line if the 'remotes' package isn't installed already. remotes::install_github(\"OuhscBbmc/REDCapR\")"},{"path":"https://ouhscbbmc.github.io/REDCapR/index.html","id":"collaborative-development","dir":"","previous_headings":"","what":"Collaborative Development","title":"Interaction Between R and REDCap","text":"encourage input collaboration. ’re familiar GitHub R packages, feel free submit pull request. ’d like report bug make suggestion, please create GitHub issue; issues usually good place ask public questions . However, feel free email (wibeasley@hotmail.com). Please note project released Contributor Code Conduct; participating project agree abide terms. starting material described ./documentation--developers/ directory. ’d like thank following developers advice code contributions: Benjamin Nutter, Rollie Parrish, Scott Burns, John Aponte, Andrew Peters, Hao Zhu.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/index.html","id":"funders","dir":"","previous_headings":"","what":"Funders","title":"Interaction Between R and REDCap","text":"Much package developed support needs following projects. appreciate support. (far) primary developers REDCapR external evaluators Oklahoma’s MIECHV program. See preliminary CQI reports (many use REDCapR) https://ouhscbbmc.github.io/MReportingPublic/. OUHSC CCAN Independent Evaluation State Oklahoma Competitive Maternal, Infant, Early Childhood Home Visiting (MIECHV) Project. HRSA/ACF D89MC23154. David Bard, PI, OUHSC; 2011-2015. Independent Evaluation State OK MIECHV Evidence Based Home Visitation Project, NIH-sponsored collaboration OSDH. David Bard, PI, OUHSC; 2015-2017. OSDH ParentPRO Pilot Evaluation, federally-sponsored collaboration OSDH. David Bard, PI, OUHSC; 2015-2017. Title IV-E Waiver Project, HRSA/MCHB-sponsored collaboration OKDHS; David Bard, PI, OUHSC; 2014-2017. Integrative Analysis Longitudinal Studies Aging (IALSA), sponsored NIH 5P01AG043362. Scott Hofer, PI, University Victoria; Beasley, PI site-award, OUHSC; 2013-2018. Oklahoma Shared Clinical Translational Resources, sponsored NIH NIGMS; U54 GM104938. Judith . James, PI, OUHSC; 2013-2018. Oklahoma Shared Clinical Translational Resources, sponsored NIH U54GM104938; 2020-2021. Additional Institutional Support OUHSC Dept Pediatrics; 2013-2021. Thanks, Beasley, David Bard, & Thomas WilsonUniversity Oklahoma Health Sciences Center, Department Pediatrics, Biomedical & Behavioral Research Core.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/REDCapR-package.html","id":null,"dir":"Reference","previous_headings":"","what":"REDCapR: Interaction Between R and REDCap — REDCapR-package","title":"REDCapR: Interaction Between R and REDCap — REDCapR-package","text":"Encapsulates functions streamline calls R REDCap API. REDCap (Research Electronic Data CAPture) web application building managing online surveys databases developed Vanderbilt University. Application Programming Interface (API) offers avenue access modify data programmatically, improving capacity literate reproducible programming. Comprehensive documentation also available https://ouhscbbmc.github.io/REDCapR/. Much package developed support needs following projects. appreciate support. OUHSC CCAN Independent Evaluation State Oklahoma Competitive Maternal, Infant, Early Childhood Home Visiting (MIECHV) Project. HRSA/ACF D89MC23154. David Bard, PI, OUHSC; 2011-2015. Independent Evaluation State OK MIECHV Evidence Based Home Visitation Project, NIH-sponsored collaboration OSDH. David Bard, PI, OUHSC; 2015-2017. OSDH ParentPRO Pilot Evaluation, federally-sponsored collaboration OSDH. David Bard, PI, OUHSC; 2015-2017. Title IV-E Waiver Project, HRSA/MCHB-sponsored collaboration OKDHS; David Bard, PI, OUHSC; 2014-2017. Integrative Analysis Longitudinal Studies Aging (IALSA), sponsored NIH 5P01AG043362. Scott Hofer, PI, University Victoria; Beasley, PI site-award, OUHSC; 2013-2018. Oklahoma Shared Clinical Translational Resources, sponsored NIH NIGMS; U54 GM104938. Judith . James, PI, OUHSC; 2013-2018. Additional Institutional Support OUHSC Dept Pediatrics; 2013-2017.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/REDCapR-package.html","id":"note","dir":"Reference","previous_headings":"","what":"Note","title":"REDCapR: Interaction Between R and REDCap — REDCapR-package","text":"release version available CRAN running install.packages('REDCapR'). recent development version available GitHub running remotes::install_github('OuhscBbmc/REDCapR') (make sure remotes already installed). trouble package, please install development version. solve problem, please create new issue, email . See REDCapR's advanced vignette information examples overriding default SSL options.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/REDCapR-package.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"REDCapR: Interaction Between R and REDCap — REDCapR-package","text":"Maintainer: Beasley wibeasley@hotmail.com (ORCID) contributors: David Bard (ORCID) [contributor] Thomas Wilson [contributor] John J Aponte john.aponte@isglobal.org [contributor] Rollie Parrish rparrish@flightweb.com (ORCID) [contributor] Benjamin Nutter [contributor] Andrew Peters (ORCID) [contributor] Hao Zhu (ORCID) [contributor] Janosch Linkersdörfer (ORCID) [contributor] Jonathan Mang (ORCID) [contributor] Felix Torres fetorres@ucsd.edu [contributor] Philip Chase pbc@ufl.edu (ORCID) [contributor] Victor Castro vcastro@mgh.harvard.edu (ORCID) [contributor] Greg Botwin [contributor] Stephan Kadauke (ORCID) [contributor] Ezra Porter (ORCID) [contributor] Matthew Schuelke matt@themadstatter.com (ORCID) [contributor]","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/REDCapR-package.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"REDCapR: Interaction Between R and REDCap — REDCapR-package","text":"","code":"# \\dontrun{ # Install/update REDCapR with the release version from CRAN. # install.packages('REDCapR') # Install/update REDCapR with the development version from GitHub # install.packages(\"remotes\") # Uncomment if `remotes` isn't installed already. # remotes::install_github('OuhscBbmc/REDCapR') # }"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":null,"dir":"Reference","previous_headings":"","what":"Collapse a vector of values into a single string when necessary — collapse_vector","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"REDCap's API frequently specifies series values separated commas. R world, easier keep values separate elements vector. functions squashes together single character element (presumably right return value passed API)","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"","code":"collapse_vector(elements)"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"elements array values. Can NULL. Required.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"single character element, values separated commas. Can blank. (.e., \"\").","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/collapse_vector.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Collapse a vector of values into a single string when necessary — collapse_vector","text":"","code":"library(REDCapR) # Load the package into the current R session. REDCapR:::collapse_vector(elements = NULL ) #> [1] \"\" REDCapR:::collapse_vector(elements = letters) #> [1] \"a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z\""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":null,"dir":"Reference","previous_headings":"","what":"Collection of REDCap-specific constants — constant","title":"Collection of REDCap-specific constants — constant","text":"Collection constants defined REDCap developers.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Collection of REDCap-specific constants — constant","text":"","code":"constant(name)"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Collection of REDCap-specific constants — constant","text":"name Name constant. Required character.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Collection of REDCap-specific constants — constant","text":"constant's value. Currently single integers, expanded future.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Collection of REDCap-specific constants — constant","text":"Form Completeness current constants relate 'complete' variable end form. form_incomplete: 0L (.e., integer) form_unverified: 1L form_complete: 2L Export Rights See https://-server/redcap/api/help/?content=exp_users. data_export_rights_no_access : 0L data_export_rights_deidentified : 1L data_export_rights_full : 2L Form Rights See https://-server/redcap/api/help/?content=exp_users. order digits may unexpected. form_rights_no_access : 0L form_rights_readonly : 2L form_rights_edit_form : 1L form_rights_edit_survey : 3L Access Rights See https://-server/redcap/api/help/?content=exp_users. access_no : 0L access_yes : 1L add , please edit constant.R GitHub submit pull request. instructions, please see Editing files another user's repository # nolint GitHub documentation.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Collection of REDCap-specific constants — constant","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/constant.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Collection of REDCap-specific constants — constant","text":"","code":"REDCapR::constant(\"form_incomplete\") # Returns 0L #> [1] 0 REDCapR::constant(\"form_unverified\") # Returns 1L #> [1] 1 REDCapR::constant(\"form_complete\" ) # Returns 2L #> [1] 2 REDCapR::constant(\"data_export_rights_no_access\" ) # Returns 0L #> [1] 0 REDCapR::constant(\"data_export_rights_deidentified\") # Returns 1L #> [1] 1 REDCapR::constant(\"data_export_rights_full\" ) # Returns 2L #> [1] 2 REDCapR::constant(\"form_rights_no_access\") # Returns 0L #> [1] 0 REDCapR::constant(\"form_rights_readonly\" ) # Returns 2L --Notice the order #> [1] 2 REDCapR::constant(\"form_rights_edit_form\") # Returns 1L #> [1] 1 REDCapR::constant(\"form_rights_edit_survey\") # Returns 3L #> [1] 3 REDCapR::constant(\"access_no\" ) # Returns 0L #> [1] 0 REDCapR::constant(\"access_yes\") # Returns 1L #> [1] 1 REDCapR::constant(c( \"form_complete\", \"form_complete\", \"form_incomplete\" )) # Returns c(2L, 2L, 0L) #> [1] 2 2 0 REDCapR::constant(c( \"form_rights_no_access\", \"form_rights_readonly\", \"form_rights_edit_form\", \"form_rights_edit_survey\" )) # Returns c(0L, 2L, 1L, 3L) #> [1] 0 2 1 3 constant_to_form_completion( c(0, 2, 1, 2, NA)) #> [1] incomplete complete unverified complete unknown #> Levels: incomplete unverified complete unknown constant_to_form_rights( c(0, 2, 1, 2, NA)) #> [1] no_access readonly edit_form readonly unknown #> Levels: no_access readonly edit_form edit_survey unknown constant_to_export_rights( c(0, 2, 1, 3, NA)) #> [1] no_access rights_full deidentified unknown #> Levels: no_access deidentified rights_full unknown constant_to_access( c(0, 1, 1, 0, NA)) #> [1] no yes yes no unknown #> Levels: no yes unknown # \\dontrun{ # The following line returns an error: # Assertion on 'name' failed: Must be a subset of # {'form_complete','form_incomplete','form_unverified'}, # but is {'bad-name'}. REDCapR::constant(\"bad-name\") # Returns an error #> Error in REDCapR::constant(\"bad-name\"): Assertion on 'name' failed: Must be a subset of {'form_incomplete','form_unverified','form_complete','data_export_rights_no_access','data_export_rights_deidentified','data_export_rights_full','form_rights_no_access','form_rights_readonly','form_rights_edit_form','form_rights_edit_survey','access_no','access_yes'}, but has additional elements {'bad-name'}. REDCapR::constant(c(\"form_complete\", \"bad-name\")) # Returns an error #> Error in REDCapR::constant(c(\"form_complete\", \"bad-name\")): Assertion on 'name' failed: Must be a subset of {'form_incomplete','form_unverified','form_complete','data_export_rights_no_access','data_export_rights_deidentified','data_export_rights_full','form_rights_no_access','form_rights_readonly','form_rights_edit_form','form_rights_edit_survey','access_no','access_yes'}, but has additional elements {'bad-name'}. # }"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":null,"dir":"Reference","previous_headings":"","what":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"function returns base::data.frame() functions use separate long-running read write REDCap calls multiple, smaller REDCap calls. goal (1) reduce chance time-outs, (2) introduce little breaks batches server continually tied .","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"","code":"create_batch_glossary(row_count, batch_size)"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"row_count number records large dataset, split. batch_size maximum number subject records single batch contain.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"Currently, base::data.frame() returned following columns, id: integer uniquely identifies batch, starting 1. start_index: index first row batch. integer. stop_index: index last row batch. integer. id_pretty: character representation id, padded zeros. start_index: character representation start_index, padded zeros. stop_index: character representation stop_index, padded zeros. label: character concatenation id_pretty, start_index, stop_index_pretty.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"function can also assist splitting saving large data frame disk smaller files (.csv). padded columns allow OS sort batches/files sequential order.","code":""},{"path":[]},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/create_batch_glossary.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Creates a dataset that help batching long-running read and writes — create_batch_glossary","text":"","code":"REDCapR::create_batch_glossary(100, 50) #> # A tibble: 2 × 7 #> id start_index stop_index index_pretty start_index_pretty stop_index_pretty #> #> 1 1 1 50 1 001 050 #> 2 2 51 100 2 051 100 #> # ℹ 1 more variable: label REDCapR::create_batch_glossary(100, 25) #> # A tibble: 4 × 7 #> id start_index stop_index index_pretty start_index_pretty stop_index_pretty #> #> 1 1 1 25 1 001 025 #> 2 2 26 50 2 026 050 #> 3 3 51 75 3 051 075 #> 4 4 76 100 4 076 100 #> # ℹ 1 more variable: label REDCapR::create_batch_glossary(100, 3) #> # A tibble: 34 × 7 #> id start_index stop_index index_pretty start_index_pretty #> #> 1 1 1 3 01 001 #> 2 2 4 6 02 004 #> 3 3 7 9 03 007 #> 4 4 10 12 04 010 #> 5 5 13 15 05 013 #> 6 6 16 18 06 016 #> 7 7 19 21 07 019 #> 8 8 22 24 08 022 #> 9 9 25 27 09 025 #> 10 10 28 30 10 028 #> # ℹ 24 more rows #> # ℹ 2 more variables: stop_index_pretty , label REDCapR::create_batch_glossary( 0, 3) #> # A tibble: 0 × 7 #> # ℹ 7 variables: id , start_index , stop_index , #> # index_pretty , start_index_pretty , stop_index_pretty , #> # label d <- data.frame( record_id = 1:100, iv = sample(x=4, size=100, replace=TRUE), dv = rnorm(n=100) ) REDCapR::create_batch_glossary(nrow(d), batch_size=40) #> # A tibble: 3 × 7 #> id start_index stop_index index_pretty start_index_pretty stop_index_pretty #> #> 1 1 1 40 1 001 040 #> 2 2 41 80 2 041 080 #> 3 3 81 100 3 081 100 #> # ℹ 1 more variable: label "},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":null,"dir":"Reference","previous_headings":"","what":"REDCapR internal function for calling the REDCap API — kernel_api","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"function used functions read write values.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"","code":"kernel_api( redcap_uri, post_body, config_options, encoding = \"UTF-8\", content_type = \"text/csv\", handle_httr = NULL, encode_httr = \"form\" )"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"redcap_uri uri/url REDCap server typically formatted \"https://server.org/apps/redcap/api/\". Required. post_body List contents expected REDCap API. Required. config_options list options passed httr::POST(). See details httr::httr_options(). Optional. encoding encoding value passed httr::content(). Defaults 'UTF-8'. content_type MIME value passed httr::content(). Defaults 'text/csv'. handle_httr value passed handle parameter httr::POST(). useful unconventional authentication approaches. NULL institutions. encode_httr value passed encode parameter httr::POST(). Defaults \"form\", appropriate actions. (Currently, exception importing file, uses \"multipart\".)","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"utils::packageVersion.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"API call unsuccessful, value base::package_version(\"0.0.0\") returned. ensures function always return object class base::package_version. guarantees value can always used utils::compareVersion().","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/kernel_api.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"REDCapR internal function for calling the REDCap API — kernel_api","text":"","code":"config_options <- NULL uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" post_body <- list( token = token, content = \"project\", format = \"csv\" ) # \\dontrun{ kernel <- REDCapR:::kernel_api(uri, post_body, config_options) # Consume the results in a few different ways. kernel$result #> Response [https://redcap-dev-2.ouhsc.edu/redcap/api/] #> Date: 2024-11-06 13:22 #> Status: 200 #> Content-Type: text/csv; charset=utf-8 #> Size: 590 B #> project_id,project_title,creation_time,production_time,in_production,project_... #> 33,\"REDCapR: simple\",\"2024-10-10 20:21:18\",,0,English,4,,,,,0,0,0,0,1,0,0,,,,... read.csv(text = kernel$raw_text) #> project_id project_title creation_time production_time in_production #> 1 33 REDCapR: simple 2024-10-10 20:21:18 NA 0 #> project_language purpose purpose_other project_notes custom_record_label #> 1 English 4 NA NA NA #> secondary_unique_field is_longitudinal has_repeating_instruments_or_events #> 1 NA 0 0 #> surveys_enabled scheduling_enabled record_autonumbering_enabled #> 1 0 0 1 #> randomization_enabled ddp_enabled project_irb_number project_grant_number #> 1 0 0 NA NA #> project_pi_firstname project_pi_lastname display_today_now_button #> 1 NA NA 1 #> missing_data_codes external_modules bypass_branching_erase_field_prompt #> 1 NA redcap_entity 0 as.list(read.csv(text = kernel$raw_text)) #> $project_id #> [1] 33 #> #> $project_title #> [1] \"REDCapR: simple\" #> #> $creation_time #> [1] \"2024-10-10 20:21:18\" #> #> $production_time #> [1] NA #> #> $in_production #> [1] 0 #> #> $project_language #> [1] \"English\" #> #> $purpose #> [1] 4 #> #> $purpose_other #> [1] NA #> #> $project_notes #> [1] NA #> #> $custom_record_label #> [1] NA #> #> $secondary_unique_field #> [1] NA #> #> $is_longitudinal #> [1] 0 #> #> $has_repeating_instruments_or_events #> [1] 0 #> #> $surveys_enabled #> [1] 0 #> #> $scheduling_enabled #> [1] 0 #> #> $record_autonumbering_enabled #> [1] 1 #> #> $randomization_enabled #> [1] 0 #> #> $ddp_enabled #> [1] 0 #> #> $project_irb_number #> [1] NA #> #> $project_grant_number #> [1] NA #> #> $project_pi_firstname #> [1] NA #> #> $project_pi_lastname #> [1] NA #> #> $display_today_now_button #> [1] 1 #> #> $missing_data_codes #> [1] NA #> #> $external_modules #> [1] \"redcap_entity\" #> #> $bypass_branching_erase_field_prompt #> [1] 0 #> # }"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":null,"dir":"Reference","previous_headings":"","what":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"collection functions assists handling REDCap project metadata.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"","code":"regex_named_captures(pattern, text, perl = TRUE) checkbox_choices(select_choices)"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"pattern regular expression pattern. Required. text text apply regex . Required. perl Indicates perl-compatible regexps used. Default TRUE. Optional. select_choices text containing choices parsed determine id label values. Required.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"Currently, tibble::tibble() returned row match, column named group within match. retrieve_checkbox_choices() function, columns . id: numeric value assigned choice (data dictionary). label: label assigned choice (data dictionary).","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"regex_named_captures() function general, specific REDCap; accepts arbitrary regular expression. returns tibble::tibble() many columns named matches. checkbox_choices() function specialized, accommodates \"select choices\" single REDCap checkbox group (multiple boxes can selected). returns tibble::tibble() two columns, one numeric id one text label. parse probably fail label contains pipe (.e., |), since delimiter REDCap uses separate choices presented user.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"See official documentation permissible characters checkbox label. bluffing , know located. know, please tell .","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/metadata_utilities.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Manipulate and interpret the metadata of a REDCap project — metadata_utilities","text":"","code":"# The weird ranges are to avoid the pipe character; # PCRE doesn't support character negation. pattern_boxes <- \"(?<=\\\\A| \\\\| )(?\\\\d{1,}), (?[\\x20-\\x7B\\x7D-\\x7E]{1,})(?= \\\\| |\\\\Z)\" choices_1 <- paste0( \"1, American Indian/Alaska Native | \", \"2, Asian | \", \"3, Native Hawaiian or Other Pacific Islander | \", \"4, Black or African American | \", \"5, White | \", \"6, Unknown / Not Reported\" ) # This calls the general function, and requires the correct regex pattern. REDCapR::regex_named_captures(pattern=pattern_boxes, text=choices_1) #> # A tibble: 6 × 2 #> id label #> #> 1 1 American Indian/Alaska Native #> 2 2 Asian #> 3 3 Native Hawaiian or Other Pacific Islander #> 4 4 Black or African American #> 5 5 White #> 6 6 Unknown / Not Reported # This function is designed specifically for the checkbox values. REDCapR::checkbox_choices(select_choices=choices_1) #> # A tibble: 6 × 2 #> id label #> #> 1 1 American Indian/Alaska Native #> 2 2 Asian #> 3 3 Native Hawaiian or Other Pacific Islander #> 4 4 Black or African American #> 5 5 White #> 6 6 Unknown / Not Reported # \\dontrun{ uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" ds_metadata <- redcap_metadata_read(uri, token)$data #> The data dictionary describing 17 fields was read from REDCap in 0.2 seconds. The http status code was 200. choices_2 <- ds_metadata[ds_metadata$field_name == \"race\", ]$select_choices_or_calculations REDCapR::regex_named_captures(pattern = pattern_boxes, text = choices_2) #> # A tibble: 1 × 2 #> id label #> #> 1 \"\" \"\" # } path_3 <- system.file(package = \"REDCapR\", \"test-data/projects/simple/metadata.csv\") ds_metadata_3 <- read.csv(path_3) choices_3 <- ds_metadata_3[ds_metadata_3$field_name==\"race\", \"select_choices_or_calculations\"] REDCapR::regex_named_captures(pattern = pattern_boxes, text = choices_3) #> # A tibble: 6 × 2 #> id label #> #> 1 1 American Indian/Alaska Native #> 2 2 Asian #> 3 3 Native Hawaiian or Other Pacific Islander #> 4 4 Black or African American #> 5 5 White #> 6 6 Unknown / Not Reported"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":null,"dir":"Reference","previous_headings":"","what":"Export Arms — redcap_arm_export","title":"Export Arms — redcap_arm_export","text":"Export Arms REDCap project","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Export Arms — redcap_arm_export","text":"","code":"redcap_arm_export( redcap_uri, token, verbose = TRUE, config_options = NULL, handle_httr = NULL )"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Export Arms — redcap_arm_export","text":"redcap_uri uri/url REDCap server typically formatted \"https://server.org/apps/redcap/api/\". Required. token user-specific string serves password project. Required. verbose boolean value indicating messages printed R console operation. verbose output might contain sensitive information (e.g. PHI), turn output might visible somewhere public. Optional. config_options list options passed httr::POST(). See details httr::httr_options(). Optional. handle_httr value passed handle parameter httr::POST(). useful unconventional authentication approaches. NULL institutions. Optional.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Export Arms — redcap_arm_export","text":"Currently, list returned following elements: has_arms: logical value indicating REDCap project arms (.e., \"TRUE\") classic non-longitudinal project (.e., \"FALSE\"). data: tibble::tibble() one row per arm. columns arm_number (integer) arm_name (human-friendly string). success: boolean value indicating operation apparently successful. status_code: http status code operation. outcome_message: human readable string indicating operation's outcome. elapsed_seconds: duration function. raw_text: operation successful, text returned REDCap. operation successful, raw_text returned empty string save RAM.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Export Arms — redcap_arm_export","text":"official documentation can found 'API Help Page' 'API Examples' pages REDCap wiki (.e., https://community.projectredcap.org/articles/456/api-documentation.html https://community.projectredcap.org/articles/462/api-examples.html). account wiki, please ask campus REDCap administrator send static material.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Export Arms — redcap_arm_export","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_arm_export.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Export Arms — redcap_arm_export","text":"","code":"# \\dontrun{ uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" # Query a classic project with 3 arms token_1 <- \"14817611F9EA1A6E149BBDC37134E8EA\" # arm-multiple-delete result_1 <- REDCapR::redcap_arm_export(redcap_uri=uri, token=token_1) #> The list of arms was retrieved from the REDCap project in 0.2 seconds. The http status code was 200. result_1$has_arms #> [1] TRUE result_1$data #> # A tibble: 3 × 2 #> arm_number arm_name #> #> 1 1 Arm 1 #> 2 2 Arm 2 #> 3 3 Arm 3 # Query a classic project without arms token_2 <- \"F9CBFFF78C3D78F641BAE9623F6B7E6A\" # simple-write result_2 <- REDCapR::redcap_arm_export(redcap_uri=uri, token=token_2) #> A 'classic' REDCap project has no arms. Retrieved in 0.1 seconds. The http status code was 400. result_2$has_arms #> [1] FALSE result_2$data #> # A tibble: 0 × 2 #> # ℹ 2 variables: arm_number , arm_name # }"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":null,"dir":"Reference","previous_headings":"","what":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"Replace non-ASCII characters legal characters cause problems writing REDCap project.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"","code":"redcap_column_sanitize( d, column_names = colnames(d), encoding_initial = \"latin1\", substitution_character = \"?\" )"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"d base::data.frame() tibble::tibble() containing dataset used update REDCap project. Required. column_names array character values indicating names variables sanitize. Optional. encoding_initial array character values indicating names variables sanitize. Optional. substitution_character character value replaces characters unable appropriately matched.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"data frame columns, whose character values sanitized.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"Letters like accented '' replaced plain ''. thin wrapper around base::iconv(). ASCII//TRANSLIT option actual transliteration work. R 3.1.0, OSes use similar, different, versions convert characters. aware case notice OS-dependent differences.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"Beasley","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_column_sanitize.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Sanitize to adhere to REDCap character encoding requirements — redcap_column_sanitize","text":"","code":"# Typical examples are not shown because they require non-ASCII encoding, # which makes the package documentation less portable. dirty <- data.frame( id = 1:3, names = c(\"Ekstr\\xf8m\", \"J\\xf6reskog\", \"bi\\xdfchen Z\\xfcrcher\") ) REDCapR::redcap_column_sanitize(dirty) #> id names #> 1 1 Ekstrom #> 2 2 J\"oreskog #> 3 3 bisschen Z\"urcher"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":null,"dir":"Reference","previous_headings":"","what":"Read data access groups from a REDCap project — redcap_dag_read","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"function reads available data access groups REDCap returns tibble::tibble().","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"","code":"redcap_dag_read( redcap_uri, token, http_response_encoding = \"UTF-8\", locale = readr::default_locale(), verbose = TRUE, config_options = NULL, handle_httr = NULL )"},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"redcap_uri uri/url REDCap server typically formatted \"https://server.org/apps/redcap/api/\". Required. token user-specific string serves password project. Required. http_response_encoding encoding value passed httr::content(). Defaults 'UTF-8'. locale readr::locale() object specify preferences like number, date, time formats. object passed readr::read_csv(). Defaults readr::default_locale(). verbose boolean value indicating messages printed R console operation. verbose output might contain sensitive information (e.g. PHI), turn output might visible somewhere public. Optional. config_options list options passed httr::POST(). See details httr::httr_options(). Optional. handle_httr value passed handle parameter httr::POST(). useful unconventional authentication approaches. NULL institutions. Optional.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"Currently, list returned following elements: data: tibble::tibble() data access groups project. success: boolean value indicating operation apparently successful. status_codes: collection http status codes, separated semicolons. one code batch attempted. outcome_messages: collection human readable strings indicating operations' semicolons. one code batch attempted. unsuccessful operation, contain diagnostic information. elapsed_seconds: duration function.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"references","dir":"Reference","previous_headings":"","what":"References","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"official documentation can found 'API Help Page' 'API Examples' pages REDCap wiki (.e., https://community.projectredcap.org/articles/456/api-documentation.html https://community.projectredcap.org/articles/462/api-examples.html). account wiki, please ask campus REDCap administrator send static material.","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"Jonathan M. Mang","code":""},{"path":"https://ouhscbbmc.github.io/REDCapR/reference/redcap_dag_read.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Read data access groups from a REDCap project — redcap_dag_read","text":"","code":"# \\dontrun{ uri <- \"https://redcap-dev-2.ouhsc.edu/redcap/api/\" token <- \"9A068C425B1341D69E83064A2D273A70\" REDCapR::redcap_dag_read(redcap_uri=uri, token=token)$data #> 2 data access groups were read from REDCap in 0.3 seconds. The http status code was 200. #> # A tibble: 2 × 3 #> data_access_group_name unique_group_name data_access_group_id #> 