1. REDCap and DDI Exporting Data and Metadata with the API Larry Hoyle and Ada Van Roekel Institute for Policy & Social Research University of Kansas Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 1

2. REDCap Consortium http://project-redcap.org/ http://project-redcap.org/ Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 2

3. REDCap Citation Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 3

4. REDCap as an Environment Secure Web based Build and manage online surveys and databases – Online Designer – Excel template file Exports to SPSS, SAS, Stata, and R Project management features – Calendar, scheduling, email notices, reporting, triggers, longitudinal studies, rights and permissions Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 4

5. R Function REDCapAPI_ToDDI <- function(secret_token ="", # the token for the user&project DDIinstanceFile="", # the output DDI file EchoDDI=FALSE, # if TRUE, print the generated DDI to the console IncludeData=TRUE, # if TRUE, include PhysicalRecordSegment and output StudyTitle="Study Title goes here", # the title of the study agency="example.org", # the agency responsible for the data organizationSchemeNameText="Org scheme", # the name for the # Organization Scheme organizationNameText="Organization name", # the organization name CurrentVersion="1.0.0", # the default current version number EmbargoEndDateValue="2112-01-01T01:01:01" # a dateTime at which the embargo on Personally Identifiable data will expire ) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 5

6. Test – DDI to Colectica Express Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 6

7. Test – Data into SAS Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 7

8. Start Screen Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 8

9. Online Designer – Project Setup Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 9

10. Project Setup (continued) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 10

11. Online Designer – Question Sequence Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 11 DDI

12. NADDI Pre-Conference Survey Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 12

13. Interest in This Presentation Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 13

14. Individual Question Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 14 DDI Categories Codes Questions Variables Name Label Representation StatementItem

15. Field Types Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 15 Representation And Layout Can imply multiple automatic variables

16. Branching Conditional execution of one question and its header and footer Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 16

17. Events Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 17

18. Event to Instrument Mappings Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 18

19. Data entry management - subject Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 19

20. All records Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 20

21. Exporting from REDCap Interactive – Forms metadata – Data API – Forms metadata – Data – Users (this is researchers, not respondents) – Events – Form-Event Mappings Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 21

22. Exporting Metadata (Codebook) - GUI Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 22 Note the multiple forms

23. REDCap API – export form-event mappings Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 23

24. XML – Form Event Mapping 1 initial_data_arm_1 prescreening_survey participant_info_ survey w eek_1_arm_1 participant_ morale_questionnaire week_2_arm_1 participant_morale_questionnaire week_3_arm_1 participant_morale_questionnaire week_4_arm _1 participant_morale_qu estionnaire final_data_arm_1 compl etion_data Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 24

25. HTML form to Test API Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 25 /api/" method="POST" name="form1" target="_blank" id="form1"> Token is specific to project and authorized person <input type="text" name="token" id="token" />

26. Data - Records_flat as csv Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 26

27. Records – Flat (all forms in one table) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 27 prescreening _survey participant_info_ survey participant_morale_ questionnaire

28. FormEventMapping Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 28

29. Records - EAV Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 29 More machine actionable?

30. Metadata (Codebook) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 30

31. Users Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 31

32. Events Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 32

33. Example R code (from REDCap Documentation) # Load needed libraries # --> NOTE: RCurl is dependent on bitops library(bitops) library(RCurl) library(Hmisc) library(xtable) # Set secret token specific to your REDCap project secret_token = 'YOUR_API_TOKEN' # Set the url to the api (ex. https://YOUR_REDCAP_INSTALLATION/api/) api_url = 'YOUR_API_URL/' curl_handle = getCurlHandle() curlSetOpt(ssl.verifypeer = FALSE, curl = curl_handle) y <- postForm( api_url, token = secret_token, content = ' formEventMapping ', format = ' csv ', curl = curl_handle) x <- read.table(file = textConnection(y), header = TRUE, sep = ",", na.strings = "", stringsAsFactors = FALSE) rm(secret_token, y) x Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 33

34. REDCAP TO DDI An R program uses the API to pull available data and metadata and writes a DDI 3.1 file. Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 34

35. One Row, CSV File (Excel Template) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 35 Variable / Field Name Form Name Section Header Field Type Field Label Choices, Calculations, OR Slider Labels Field Note Text Validation Type OR Show Slider Number Text Validation Min Text Validation Max Identifier? Branching Logic (Show field only if...) Required Field? Custom Alignment Question Number (surveys only) Matrix Group Name TASK From: One row per question (with Header and Note) To: Hierarchical DDI structure

36. Example: text field containing a number Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 36 Field Type: text Text Validation Type OR Show Slider Number: number Extrema

37. Example: text field containing a number Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 37

38. DDI – Question w/ Numeric Domain Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 38

39. Section Header – in same row as data field Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 39

40. Example: coded variable w/ radio buttons Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 40

41. REDCap Code and Category Strings Repeat Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 41 In DDI, only one Code and Category Scheme to be used by reference

42. Lots of References Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 42 Note: the program generates random style UUIDs

43. DateTime fields Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 43 Text Validation Type OR Show Slider Number: date_ymd

44. Sliders Return a value between 0 and 100 End and mid points labeled Optionally display the numeric value How to represent? – Numeric – Categories for some values (0, 50, 100)? Recorded in the NumericDomain Description Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 44

45. Slider as Numeric question/variable Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 45 This Description added to the NumericDomain REDCap Field Type: slider. NOTE: This question has a minimum of 0 and a maximum of 100. The end and middle points were labeled as: 0, You can provide labels above the slider | 50, Middle label | 100, Right-hand label

46. Could be Slider as Coded variable Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 46 This Description added to the CodeDomain REDCap Field Type: slider. NOTE: The REDCap slider field returns a numeric value between 0 and 100, but may have labels for the end and mid points.

47. CSV values for a conditional question Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 47 The header and note will also be displayed conditionally The Question and surrounding text will appear when this REDCap expression is true hidden_branch,survey,"Section Header immediately before question hidden_branch ",text,"HIDDEN QUESTION: This question will only appear when you select the second option of the question immediately above.",,"A Field Note for a hidden question",,undefined,undefined,,"[radio_branch] = ""2""",,,, Branching Logic (Show field only if...) [radio_branch] = "2"

48. ControlConstruct chain to build the Instrument Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 48 DDI d:StatementItem DDI d:QuestionConstruct DDI d:StatementItem DDI d:Sequence DDI d:IfThenElse DDI d:Sequence (master sequence) DDI d:Instrument

49. More complex Instrument issues REDCap can set an option that ends the session upon entry of a particular value (a "stop action") – This could be represented with IfThenElse of a Sequence Not done in this version REDCap has a Matrix Group construct – This is partly a layout issue but could be better documented with a sub-sequence than in this version of the program Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 49

50. Data Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 50 Some automatic variables One row per participant event

51. Data - Paradata Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 51 Some paradata "0, Incomplete | 1, Unverified | 2, Complete"

52. Data Multiple Forms Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 52 Data from form 1 participant_info_survey Same variable in two forms has to have different name Data from form 2 participant_morale_questionnaire

53. Data Multiple Forms Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 53 Data from form 1 participant_info_survey Multiple Instruments in DDI Data from form 2 participant_morale_questionnaire

54. R Function REDCapAPI_ToDDI <- function(secret_token ="", # the token for the user&project DDIinstanceFile="", # the output DDI file EchoDDI=FALSE, # if TRUE, print the generated DDI to the console IncludeData=TRUE, # if TRUE, include PhysicalRecordSegment and output StudyTitle="Study Title goes here", # the title of the study agency="example.org", # the agency responsible for the data organizationSchemeNameText="Org scheme", # the name for the # Organization Scheme organizationNameText="Organization name", # the organization name CurrentVersion="1.0.0", # the default current version number EmbargoEndDateValue="2112-01-01T01:01:01" # a dateTime at which the embargo on Personally Identifiable data will expire ) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 54

55. Test – DDI to Colectica Express Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 55

56. Test – Data into SAS Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 56

57. DDI TO REDCAP Going the other way – defining a REDCap survey by transforming a DDI 3.1 file to a REDCap csv template. Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 57

58. Hierarchical DDI to one row per Question REDCap uses Code/Category schemes by repetition instead of by reference DDI Instruments may be much more complex than a simple sequence with a conditional display of a question. – Combining REDCap calculated fields with conditional display might allow Loop, RepeatUntil etc. function. – Parsing Instrument and ControlConstructs not done in this version. E.g. no Section Headers or Field Notes Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 58

59. Hierarchical DDI to one row per Question URNs not evaluated Coded questions treated as "radio" fields. "checkbox" (multiple response) – multiple variables not generated – placed note in CodeDomain Description (not machine actionable) – treated as radio Calculated fields not generated – Could look for d:ComputationItem Would require parsing arbitrary programming code and generating REDCap syntax Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 59

60. ISSUES The metadata models for REDCap and DDI are not exactly the same. Where do they not match up? Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 60

61. Issues Full DDI complexity not representable in REDCap REDCap co-mingles layout with content metadata dropdown, radio, slider, - checkbox REDCap field type of “file” – file upload action REDCap export does not include project management features that it has (email triggers, scheduling. No perfect place for that in DDI? DDI 3.1 doesn’t handle numeric variables with some labeled values well (like slider fields) Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 61

62. Issues REDCap allows minimum and maximum for DateTime types DDI allows multiple low, high pairs for numeric variables – REDCap has just one pair REDCap can mark a Question as "required" REDCap can mark a Question as having personally identifiable information. REDCap – Some metadata only exportable through the API, some not at all Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 62

63. Issues DDI 3.1 has no Description for a QuestionItem, no good place to put notes about display options ResourcePackage vs. Studyunit – Where do Questions, Variables, Categories, Codes go? – Used ResourcePackage (more compatible with Colectica, which I used for validation) REDCap doesn’t separate question and variable – same question in two different forms is two entities Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 63

64. REDCap Events Issues Does anything in DDI represents the scheduling of forms by events in a machine actionable way? The element in each may indicate the events for which the instrument is used Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 64

65. Contact Larry Hoyle Senior Scientist Institute for Policy & Social Research, University of Kansas 1541 Lilac Lane, Blake 607 Lawrence, KS 66045-3129 LarryHoyle@ku.edu http://www.ipsr.ku.edu Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 65

66. R DETAILS Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 66

67. Used R XML Package Used the R package "XML" – http://cran.r-project.org/web/packages/XML/XML.pdf http://cran.r-project.org/web/packages/XML/XML.pdf Author Duncan Temple Lang Maintainer Duncan Temple Lang Title Tools for parsing and generating XML within R and S- Plus. Depends R (>= 1.2.0), methods, utils Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 67

68. R tools, Redcap to DDI Used Hash Tree representation: xmlHashTree() – Allowed non-sequential addition to elements Fixed framework added first and then elements extended – CategorySchemes – CodeScheme – VariableSchemes – QuestionScheme – ControlConstructs and Instrument Hash table to find the index number of the code and category schemes Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 68

69. R tools, DDI to Redcap Used internal tree representation from reading DDI with xmlTreeParse() Built code and category string in REDCap format e.g. 1, bad, or worse | 2, good, or better Built a URN like string for complete category identifiers – used this as a hash key to the category value Did the same for CodeSchemes with the value being the REDCap code and category string Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 69

70. Acknowledgements Synthetic study data were collected and managed using REDCap electronic data capture tools hosted at The University of Kansas. 1 REDCap (Research Electronic Data Capture) is a secure, web-based application designed to support data capture for research studies, providing: 1) an intuitive interface for validated data entry; 2) audit trails for tracking data manipulation and export procedures; 3) automated export procedures for seamless data downloads to common statistical packages; and 4) procedures for importing data from external sources. 1 Paul A. Harris, Robert Taylor, Robert Thielke, Jonathon Payne, Nathaniel Gonzalez, Jose G. Conde, Research electronic data capture (REDCap) - A metadata-driven methodology and workflow process for providing translational research informatics support, J Biomed Inform. 2009 Apr;42(2):377-81. Revised 2/17/2013 NADDI 2013, Hoyle & Van Roekel, REDCap and DDI 70