Export the metadata (as a data dictionary) of a REDCap project
as a tibble::tibble()
. Each row in the data dictionary corresponds to
one field in the project's dataset.
redcap_metadata_read(
redcap_uri,
token,
forms = NULL,
fields = NULL,
verbose = TRUE,
config_options = NULL,
handle_httr = NULL
)
The uri/url of the REDCap server typically formatted as "https://server.org/apps/redcap/api/". Required.
The user-specific string that serves as the password for a project. Required.
An array, where each element corresponds to the REDCap form of the desired fields. Optional.
An array, where each element corresponds to a desired project field. Optional.
A boolean value indicating if message
s should be printed
to the R console during the operation. The verbose output might contain
sensitive information (e.g. PHI), so turn this off if the output might
be visible somewhere public. Optional.
A list of options passed to httr::POST()
.
See details at httr::httr_options()
. Optional.
The value passed to the handle
parameter of
httr::POST()
.
This is useful for only unconventional authentication approaches. It
should be NULL
for most institutions. Optional.
Currently, a list is returned with the following elements:
data
: An R tibble::tibble()
of the desired fields (as rows).
success
: A boolean value indicating if the operation was apparently
successful.
status_codes
: A collection of
http status codes,
separated by semicolons. There is one code for each batch attempted.
outcome_messages
: A collection of human readable strings indicating the
operations' semicolons. There is one code for each batch attempted. In an
unsuccessful operation, it should contain diagnostic information.
forms_collapsed
: The desired records IDs, collapsed into a single
string, separated by commas.
fields_collapsed
: The desired field names, collapsed into a single
string, separated by commas.
elapsed_seconds
: The duration of the function.
The official documentation can be found on the 'API Help Page' and 'API Examples' pages on the REDCap wiki (i.e., https://community.projectredcap.org/articles/456/api-documentation.html and https://community.projectredcap.org/articles/462/api-examples.html). If you do not have an account for the wiki, please ask your campus REDCap administrator to send you the static material.
# \dontrun{
uri <- "https://bbmc.ouhsc.edu/redcap/api/"
# A simple project (pid 153)
token <- "9A81268476645C4E5F03428B8AC3AA7B"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 17 fields was read from REDCap in 0.1 seconds. The http status code was 200.
#> $data
#> # A tibble: 17 × 18
#> field_name form_…¹ secti…² field…³ field…⁴ selec…⁵ field…⁶ text_…⁷ text_…⁸
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 record_id demogr… NA text Study … NA NA NA NA
#> 2 name_first demogr… Contac… text First … NA NA NA NA
#> 3 name_last demogr… NA text Last N… NA NA NA NA
#> 4 address demogr… NA notes Street… NA NA NA NA
#> 5 telephone demogr… NA text Phone … NA Includ… phone NA
#> 6 email demogr… NA text E-mail NA NA email NA
#> 7 dob demogr… NA text Date o… NA NA date_y… NA
#> 8 age demogr… NA text Age (y… NA NA NA NA
#> 9 sex demogr… NA radio Gender 0, Fem… NA NA NA
#> 10 height health NA text Height… NA NA number 130
#> 11 weight health NA text Weight… NA NA integer 35
#> 12 bmi health NA calc BMI round(… NA NA NA
#> 13 comments health Genera… notes Commen… NA NA NA NA
#> 14 mugshot health NA file Mugshot NA NA NA NA
#> 15 race race_a… NA checkb… Race (… 1, Ame… NA NA NA
#> 16 ethnicity race_a… NA radio Ethnic… 0, Unk… NA NA NA
#> 17 interpreter_… race_a… NA truefa… Are in… NA NA NA NA
#> # … with 9 more variables: text_validation_max <chr>, identifier <chr>,
#> # branching_logic <chr>, required_field <chr>, custom_alignment <chr>,
#> # question_number <chr>, matrix_group_name <chr>, matrix_ranking <chr>,
#> # field_annotation <chr>, and abbreviated variable names ¹form_name,
#> # ²section_header, ³field_type, ⁴field_label,
#> # ⁵select_choices_or_calculations, ⁶field_note,
#> # ⁷text_validation_type_or_show_slider_number, ⁸text_validation_min
#>
#> $success
#> [1] TRUE
#>
#> $status_code
#> [1] 200
#>
#> $outcome_message
#> [1] "The data dictionary describing 17 fields was read from REDCap in 0.1 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.1349728
#>
#> $raw_text
#> [1] ""
#>
# A longitudinal project (pid 212)
token <- "0434F0E9CF53ED0587847AB6E51DE762"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 95 fields was read from REDCap in 0.1 seconds. The http status code was 200.
#> $data
#> # A tibble: 95 × 18
#> field_name form_…¹ secti…² field…³ field…⁴ selec…⁵ field…⁶ text_…⁷ text_…⁸
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 study_id demogr… NA text Study … NA NA NA NA
#> 2 date_enrolled demogr… Consen… text Date s… NA YYYY-M… date_y… NA
#> 3 patient_docu… demogr… NA file Upload… NA NA NA NA
#> 4 first_name demogr… Contac… text First … NA NA NA NA
#> 5 last_name demogr… NA text Last N… NA NA NA NA
#> 6 telephone_1 demogr… NA text Phone … NA Includ… phone NA
#> 7 email demogr… NA text E-mail NA NA email NA
#> 8 dob demogr… NA text Date o… NA NA date_y… NA
#> 9 age demogr… NA calc Age (y… roundd… NA NA NA
#> 10 ethnicity demogr… NA radio Ethnic… 0, His… NA NA NA
#> # … with 85 more rows, 9 more variables: text_validation_max <chr>,
#> # identifier <chr>, branching_logic <chr>, required_field <chr>,
#> # custom_alignment <chr>, question_number <chr>, matrix_group_name <chr>,
#> # matrix_ranking <chr>, field_annotation <chr>, and abbreviated variable
#> # names ¹form_name, ²section_header, ³field_type, ⁴field_label,
#> # ⁵select_choices_or_calculations, ⁶field_note,
#> # ⁷text_validation_type_or_show_slider_number, ⁸text_validation_min
#>
#> $success
#> [1] TRUE
#>
#> $status_code
#> [1] 200
#>
#> $outcome_message
#> [1] "The data dictionary describing 95 fields was read from REDCap in 0.1 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.1465471
#>
#> $raw_text
#> [1] ""
#>
# A repeating measures (pid 3181)
token <- "22C3FF1C8B08899FB6F86D91D874A159"
REDCapR::redcap_metadata_read(redcap_uri=uri, token=token)
#> The data dictionary describing 8 fields was read from REDCap in 0.1 seconds. The http status code was 200.
#> $data
#> # A tibble: 8 × 18
#> field_name form_name secti…¹ field…² field…³ selec…⁴ field…⁵ text_…⁶ text_…⁷
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 record_id intake NA text Record… NA NA NA NA
#> 2 height intake NA text patien… NA NA number… 1
#> 3 weight intake NA text patien… NA NA number… 1
#> 4 bmi intake NA text patien… NA NA number… 0
#> 5 sbp blood_pres… NA text systol… NA NA number 1
#> 6 dbp blood_pres… NA text diasto… NA NA number 1
#> 7 lab laboratory NA text lab va… NA NA NA NA
#> 8 conc laboratory NA text concen… NA NA NA NA
#> # … with 9 more variables: text_validation_max <chr>, identifier <chr>,
#> # branching_logic <chr>, required_field <chr>, custom_alignment <chr>,
#> # question_number <chr>, matrix_group_name <chr>, matrix_ranking <chr>,
#> # field_annotation <chr>, and abbreviated variable names ¹section_header,
#> # ²field_type, ³field_label, ⁴select_choices_or_calculations, ⁵field_note,
#> # ⁶text_validation_type_or_show_slider_number, ⁷text_validation_min
#>
#> $success
#> [1] TRUE
#>
#> $status_code
#> [1] 200
#>
#> $outcome_message
#> [1] "The data dictionary describing 8 fields was read from REDCap in 0.1 seconds. The http status code was 200."
#>
#> $forms_collapsed
#> [1] ""
#>
#> $fields_collapsed
#> [1] ""
#>
#> $elapsed_seconds
#> [1] 0.132216
#>
#> $raw_text
#> [1] ""
#>
# }