REDCap Converter

redcap_to_rios

Converts a REDCap Data Dictionary in csv format to a RIOS Instrument, Form, and CalculationSet into a dictionary.

The instrument id, version, and title must be provided as arguments on the command line as they are not in the CSV file.

As for CalculationSet, if there are no calculations in the input, no CalculationSet data will be created.

Since there are restrictions on RIOS Identifiers, the program converts all internal values to valid identifiers. See help(rios.conversion.redcap.to_rios.Csv2OrderedDict.get_name) for details. This mangling of the input identifiers may break expressions or cause other errors so it is strongly recommended to begin with valid RIOS identifiers for all page, form, matrix, and field names, as well as all internal enumeration values.

Sliders are converted to a simple float input field with min=0.0 and max=100.0. Any slider labels are ignored.

Two input formats are accepted. The first uses these input fields:

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
Matrix Ranking?
Field Annotation

  • Variable / Field Name is mapped to Field Object id.

  • Form Name is mapped to the RIOS page ID.

  • When Section Header is present, an additional “text” element is included in the form.

  • Field Type and Text Validation Type ... determine the RIOS type. “dropdown” and “radio” map to an enumeration, and “checkbox” maps to an enumeration set.

  • Field Label is mapped to Question Object text.

  • Various spellings for the Choices / Calculations field have been encountered, so any field name starting with “Choices” and containing “Calc” is taken to be this field.

    When this field contains choices it is a pipe delimited string of comma seperated tuples: id, value. The value is what is displayed to the user, and the id is what is stored in the database when the user selects the value.

  • Field Note is mapped to Question Object help.

  • Text Validation Max and Min are mapped to a suitable Bound Constraint Object as the “range” of an appropriate RIOS Type Object.

  • Identifier? is mapped to Field Object identifiable.

  • REDCap displays a field if its “Branching Logic” expression is True. In RIOS, the field is disabled if the expression is False. Arbitrarily, this converter outputs “disable” instead of “hide” as the action for this event.

  • Required Field is mapped to Field Object required.

  • Matrix Group Name is mapped to the Field Object id of a matrix field.

  • The following fields: Custom Alignment, Question Number (Show field only if...), Matrix Ranking?, and Field Annotation are completely ignored.

Entries with the same Form Name or Matrix Group Name must appear consecutively.

The second format uses these input fields:

fieldID
text
help
error
enumeration_type
data_type
repeating_group_name
page

  • fieldID is mapped to Field Object id.

  • text is mapped to Question Object text.

  • help is mapped to Question Object help.

  • enumeration_type selects “enumeration” or “enumerationSet”.

  • data_type determines the RIOS type. When enumeration_type is set, this field contains a JSON string which encodes an object whose “Choices” attribute is an array of single item dictionaries. For each (key, value) item, the key is the identifier and the value is displayed to the user.

    The array of choices will be presented to the user in order of dictionary key.

  • repeating_group_name is ignored.

  • page is mapped to the RIOS page id. As a convenience, “page_0” is assigned if this field is left blank.

Entries with the same page must appear consecutively.

rios_to_redcap

Converts a RIOS Instrument, Form, and optional CalculationSet to a REDCap Data Dictionary.

The first format is used for output because it supports calculations, branching logic, and matrices, as well as the “required” and “identifiable” field attributes.

Cavaets

  • Function names, variable references, and operators in REXL expressions are converted to REDCap; however the truth value of the REXL expression used for “Branching Logic” has NOT been negated. This must be done manually.
  • RIOS calculations are associated with an assessment and are not directly connected to a form. Consequently all of the calculations are appended to the last page of the REDCap Data Dictionary.
  • The only RIOS matrices which can be converted to REDCap have exactly one question column. This column must be an enumeration or enumerationSet.

Expressions

Expressions are converted to lowercase and to PEXL.

So for example in REDCap suppose A and B are form fields and C is a calculation field:

SUM([A], [B], [C]) <> 1

is converted to RIOS as:

rios.conversion.math.sum_(assessment["a"], assessment["b"], calculations["c"]) != 1

REDCap expressions support a collection of math and date functions.

min, max, and abs are available directly in Python, sqrt is in the Python math library, and the following have implementations in rios.conversion:

datediff
mean
median
round
rounddown
roundup
stdev
sum

If your expressions reference any of these functions then include rios.conversion as a dependency for your project.

Matrices

REDCap matrices of R rows by C columns become a RIOS matrix of R rows by 1 column. The single column is an enumeration (or enumeration set) of C values.