metaDataMethods() R function from [redcapAPI]

Export and Import the Project Meta Data (Data Dictionary)

These methods provide the user access to a REDCap project's data dictionary. The data dictionary may be exported or altered via the import.


exportMetaData(rcon, ...)

importMetaData(rcon, data, ...)

## S3 method for class 'redcapApiConnection'
exportMetaData(rcon, fields = character(0), forms = character(0), ...)

## S3 method for class 'redcapApiConnection'
importMetaData(
  rcon,
  data,
  ...,
  field_types = REDCAP_METADATA_FIELDTYPE,
  validation_types = REDCAP_METADATA_VALIDATION_TYPE
)

Arguments

rcon: A redcapConnection object.
fields: character vector of field names for which the metadata is to be retrieved.
forms: character vector of forms for which the metadata is to be retrieved. If a form name is given, all of the fields on that form will be returned, regardless of whether it is included in fields or not. Form names should match those in the second column of the data dictionary, and not the display names shown on the web interface.
data: data.frame with the Meta Data to import.
...: Arguments to pass to other methods
field_types: character giving the acceptable field types when validating the field_type column. This
validation_types: character giving the acceptable values for the text_validation_or_show_slider_number column.

Returns

exportMetaData returns a data frame. Not all 18 (or more) columns are documented here, but the most commonly used within redcapAPI are (these may appear in a different order in the data frame):



`field_name`	The name of a field in the project.
`filed_label`	The human-readable form of the field name.
`form_name`	The name of the form on which the field is found.
`field_type`	One of two fields used to determine how a field is transformed into an R object.
`select_choices_or_calculations`	The second field used to determine how a field is translated into an R object.
`text_validation_type_or_show_slider_number`	Describes how fields are validated. For slider fields, it gives the limits and center point to display.
`field_annotation`	Contains annotations such as units of measures. Also contains action tags.

importMetaData invisibly returns the number of fields that were imported.

Details

When importing meta data, the following conditions apply:

Field names may start with a letter, have any number of letters, numbers, or underscores, and end in either a letter or a number. All letters must be lowercase (the function will coerce them to lower before checking for duplicate field names).

Form names may start with a letter, have any number of letters, numbers, or underscores, and end in either a letter or a number. All letters must be lowercase (the function will coerce them to lower before checking for duplicate field names).

Field types may be one of REDCAP_METADATA_FIELDTYPE. In the event that a new field type is added to REDCap and redcapAPI is not yet updated, the user may add additional values via c(REDCAP_METADATA_FIELDTYPE, "new_type").

Validation types may be one of REDCAP_METADATA_VALIDATION_TYPE or NA. As with field types, additional values can be appended if necessary. Only fields that have a field type of "text" or "slider" should have a validation type. "slider" fields should be either NA

(do not display the selected number) or "number".

For multiple choice fields, the selection choices take the format of "code1, label1 | ... | coden, labeln". For slider fields, the format is "left_value | mid_value | right_value". Any of those values may be an empty character, but the two pipes are required, nonetheless.

For calculated fields, the values in "select_choices_or_calculations"

are currently unvalidated.

All of the values between brackets in the branching logic must be either a field name or an existing unique event name (such as "event_1_arm_1")

Functions

exportMetaData(): Export the Meta Data (Data Dictionary) of a REDCap Project
importMetaData(): Import New Meta Data (Data Dictionary) Definitions

Examples


## Not run:

unlockREDCap(connections = c(rcon = "project_alias"), 
             url = "your_redcap_url", 
             keyring = "API_KEYs", 
             envir = globalenv())

# Export the MetaData from REDCap
exportMetaData(rcon)

# Export MetaData for select fields only (returns two rows)
exportMetaData(rcon, 
               fields = c("dropdown_test", "radio_test"))

# Export MetaData for select forms
exportMetaData(rcon, 
               forms = c("first_form", "second_form"))
               
# MetaData my be exported for a combination of fields and forms
exportMetaData(rcon, 
               fields = c("dropdown_test", "radio_test"), 
               forms = c("first_form", "second_form"))
               
# Alter and import new MetaData (change the record ID label)
Meta <- exportMetaData(rcon)

Meta$field_label[1] <- "A better description of the Record ID"
importMetaData(rcon, 
               data = Meta)
## End(Not run)

metaDataMethods function