%%capture
%%R
records <- redcap_read_oneshot(
redcap_uri = url,
token = token
)$data8 Records
8.1 Exporting Raw Data
redcap_read_oneshot()
export_records()
records = project.export_records(format_type='df') #all records with raw data values
records.head(10)| redcap_repeat_instrument | redcap_repeat_instance | first_name | last_name | phone_num | zip_code | dob | age | ethnicity | race | ... | cc_phone | cc_email | close_contacts_complete | supervisor_name | supervisor_email | work_inperson_yesno | work_date | work_contagious | work_contagious_calc | work_information_complete | ||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| record_id | redcap_event_name | |||||||||||||||||||||
| 1 | personal_info_arm_1 | NaN | NaN | John | Doe | (999) 999-9999 | 98105.0 | 2006-04-11 | 18.0 | 1.0 | 4.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| notifications_arm_1 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | Boss | NaN | 0.0 | NaN | 0.0 | NaN | 2.0 | |
| case_intake_arm_1 | NaN | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| notifications_arm_1 | close_contacts | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| notifications_arm_1 | close_contacts | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| 2 | personal_info_arm_1 | NaN | NaN | Jane | Doe | (999) 999-9999 | 98105.0 | 1994-06-29 | 29.0 | 0.0 | 5.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| notifications_arm_1 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | Boss | fake_email@gmail.com | 1.0 | 2023-10-10 | 1.0 | NaN | 2.0 | |
| case_intake_arm_1 | NaN | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| case_intake_arm_1 | NaN | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | |
| notifications_arm_1 | close_contacts | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
10 rows × 46 columns
When format_type = 'df', there is a multi-index automatically assigned including record_id and redcap_event_name.
It is not recommended to use the index automatically asigned upon export as it is not always correct. In this case, record_id, redcap_event_name, redcap_repeat_instrument, and redcap_repeat_instance combined define the unique key for this data frame. The user should asign their own index accordingly; best practice is to add is to use the reset_index() method on the data export to use the row number as the index.
Exporting as a CSV or JSON creates the index using the row number.
8.2 Exporting Labeled Data & Headers
The raw_or_label parameter exports raw or labeled choice values (i.e. ‘male’ instead of ‘1’), while the raw_or_label_headers parameter exports raw or labeled variable names (i.e. shows the actual prompt/question instead of the raw variable name).
%%capture
%%R
data_labeled <- redcap_read_oneshot(
redcap_uri = url,
token = token,
raw_or_label = "label",
raw_or_label_headers = "label")$data
data_labeled = project.export_records(raw_or_label='label', format_type='df').reset_index()
data_labeled.head(10)| record_id | redcap_event_name | redcap_repeat_instrument | redcap_repeat_instance | first_name | last_name | phone_num | zip_code | dob | age | ... | cc_phone | cc_email | close_contacts_complete | supervisor_name | supervisor_email | work_inperson_yesno | work_date | work_contagious | work_contagious_calc | work_information_complete | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 1 | Personal Info | NaN | NaN | John | Doe | (999) 999-9999 | 98105.0 | 2006-04-11 | 18.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 1 | 1 | Notifications | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | Boss | NaN | No | NaN | No | NaN | Complete |
| 2 | 1 | Case Intake | NaN | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 3 | 1 | Notifications | Close Contacts | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | Complete | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 4 | 1 | Notifications | Close Contacts | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | Complete | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 5 | 2 | Personal Info | NaN | NaN | Jane | Doe | (999) 999-9999 | 98105.0 | 1994-06-29 | 29.0 | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 6 | 2 | Notifications | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | Boss | fake_email@gmail.com | Yes | 2023-10-10 | Yes | NaN | Complete |
| 7 | 2 | Case Intake | NaN | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 8 | 2 | Case Intake | NaN | 2.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
| 9 | 2 | Notifications | Close Contacts | 1.0 | NaN | NaN | NaN | NaN | NaN | NaN | ... | (999) 999-9999 | fake_email@gmail.com | Complete | NaN | NaN | NaN | NaN | NaN | NaN | NaN |
10 rows × 48 columns
Note: Exporting labeled headers only works when format_type='csv'.
8.3 Export Data In Batches (REDCapR Only)
redcap_read() is almost the same as redcap_read_oneshot(). The only difference is that redcap_read() retrieves the data in quantified batches or rows, and then combines the batches to return a single data set. This function may be more appropriate than redcap_read_oneshot() when exporting large datasets that could tie up the server. (Source)
%%capture
%%R
batched_export <- redcap_read(
redcap_uri = url,
token = token,
batch_size = 50L
)$dataIn this example, the batch size was set to 50 records. The default is 100 records. The data exported using this method has the exact same format as the data exported using redcap_read_oneshot.
8.4 Exporting The Next Available Record ID
When a project is set up in REDCap it has auto-numbering for records enabled by default. This allows a new and unique record_id to be automatically assigned every time you enter a new record within REDCap. Before importing new records via API, you may want to know what the next available Record ID is to ensure you are assigning new Record IDs to these new records before import (rather than overwriting an existing record).
This function is more important if using REDCapR because PyCap has a way to auto-number records on import.
%%capture --no-stdout
%%R
next_record <- redcap_next_free_record_name(
redcap_uri = url,
token = token,
verbose = TRUE,
config_options = NULL)
next_record[1] "7"project.generate_next_record_name()'7'Note: If Data Access Groups (DAGs) are used in the REDCap project, this method accounts for the special formatting of the record name for users in DAGs, where the unique auto-assigned DAG number is a prefix to the actual record_id (i.e. <DAG_ID>_<record_id>). A user assigned to a DAG with ID 1732 that already has 3 existing records will return ‘1732-4’ as the next available record.