-
Notifications
You must be signed in to change notification settings - Fork 27
Exporting Data From REDCap
Using the redcapAPI package can make exporting your data extremely simple with as few as two lines of code
rcon <- redcapConnection(url=[YOUR_URL], token=[YOUR_TOKEN])
myData <- exportRecords(rcon)
If desired, you can also pursue a more complex download that customizes the data to your needs. Such customizations include specifying the records, fields, forms, or events you download; whether or not to export field labels; and whether your data should be converted into factors, dates, or times.
Subsets of the data may be drawn by passing vectors to the records, fields, forms, and events arguments. Instead of exporting the complete data set (default behavior), you instead receive the data as outlined in those arguments.
The fields and forms argument work together using an OR condition. Specifically, if you request one field name that is in Form_A but only request Form_B, the export you receive will contain the one field from Form_A in addition to every field from Form_B.
Starting in REDCap 6.0, the record ID is not automatically exported in all situations. In particular, if any forms are named, the API will not return the study ID unless explicitly requested. Thus, it is good habit to always specify the study ID if you are specifying any forms.
Starting in REDCap 6.0, the exportReports function is available. This may be an easier way to export subsets of data than defining the subset in the exportRecords call.
Setting the labels argument to true will return the field labels in addition to the field names. Labels are attached to vectors in the data frame as an attribute using the label function from the Hmisc package.
Checkbox variables, if returned as factors, may be returned with values set as "Checked/Unchecked" or by setting the checkboxLabels argument to TRUE, may be returned as the label for that checkbox. For example, if a project has a checkbox field "Preferred Colors" with options "Red" and "Blue", and a particular record has checked Red and unchecked Blue, the field will return:
- when checkboxLabel = FALSE, preferred_color___red = "Checked", preferred_color___blue = "Unchecked"
- when checkboxLabel = TRUE, preferred_color___red = "Red", preferred_color___blue = ""
The checkboxLabels argument is only applicable when factors=TRUE.
Note: The checkboxLabels argument mimics the behavior of the exportCheckboxLabels parameter of the API. The API parameter wasn't introduced until REDCap 6.0, but the behavior exists in the redcapAPI version for all versions of REDCap. This is possible because labels are pulled from the meta data, not from the API.
Also, while the API supports an option to have the REDCap event labels returned, this is not supported in the redcapAPI package. If the event labels (instead of the unique event names) are required, they may be obtained by merging with the table from exportEvents.