Using the ODK Expression Assistant

What does this app do?

The Open Data Kit (ODK) Code Assistant app is designed to make it easier for researchers to work with ODK syntax (in particular on the SurveyCTO platform). ODK is a powerful tool for creating surveys and collecting data, but the syntax can sometimes be time-consuming and confusing for users. The ODK Assistant app allows you to translate natural language into ODK syntax, specifically for the relevance, calculation, and constraint columns. It also allows you to translate ODK syntax back into natural language or ask questions about what a specific syntax means and whether it is correct.

An example going from natural language to ODK syntax:

• Input “Calculate the average of fields income1 to income3”
• Output: “(${income1} + ${income2} + ${income3}) div 3”

An exmaple from ODK syntax to natural language:

• Input: “What does this syntax mean: regex(.,’RW[0-9]{5}’)?”
• Output: “The ODK expression ‘regex(.,’RW[0-9]{5}’)’ is a regular expression that matches any input that starts with ‘RW’ and has exactly 5 digits after it. The expression is used to validate the input and ensure that it follows the specified pattern.”.

Using this app can save you time and effort when working with ODK, as you don’t have to spend as much time referencing fields with brackets and dollar signs, double-checking the order of items in functions or remembering what goes in to a regex or date function. It can also be helpful for learning how to write ODK code, as you can see how your natural language instructions are translated into the required syntax. Instructions like summing multiple fields or taking the average of many fields can be particularly time-consuming to write out, but with the ODK Assistant app, you can simply input your instructions in natural language and let the app handle the rest. Overall, the ODK Assistant app is a valuable tool for anyone working with ODK and looking to streamline their workflow.

What do I need to know about the input and the output of this app?

The ODK Code Assistant app is designed to translate natural language instructions into ODK syntax and vice versa. The input for this app is either natural language text or ODK syntax for the calculation, relevance or calculation fields. The output will be text in the opposite format, either ODK syntax or natural language, depending on the input. You can then copy and paste the output text into your SurveyCTO form.

It’s important to note that in order for the app to understand your instructions properly and translate them accurately, your input should be as “ODK-ish” as possible. This means that when you are referencing a field, you should be explicit about it (e.g. “constrain to field age greater than 18”). When you are referencing a repeat field or a function, it’s helpful to be explicit about that as well (e.g. “a comma separated list of the repeat field test if age is greater than 18”). As a result, this app may be more suitable for users who are already familiar with ODK and its syntax. However, it can also be a useful tool for users who are still learning ODK and want to see how their natural language instructions are translated into the required syntax.

Note that the app is trained to work in English. It performs a bit less well in other languages for now, but we’re working on it.

Some examples

Here are some examples of when the app comes into its own:

Example 1: Short instructions, long code

• Input: The max of fields age1-age10 is bigger or equal to 10 and the selected value for gender is female
• Output: max(${age1}, ${age2}, ${age3}, ${age4}, ${age5}, ${age6}, ${age7}, ${age8}, ${age9}, ${age10})=10 and selected(${gender}, ‘female’)

Example 2: In general, instructions with many references

• Input: Coalesce the fields income, loan, sad, happy, weather, sun and rain
• Output: coalesce(${income}, ${loan}, ${sad}, ${happy}, ${weather}, ${sun}, ${rain})

Example 3: Regex syntax (even though the app will still make some mistakes for unseen combinations)

• Input: The entry is an email
• Output: regex(., ‘[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}’)

Example 4: Dates and time (even though the app will still make some mistakes for unseen combinations)

• Input: The time should be between 8am and 5pm
• Output: (int(int(decimal-time(.)*1440) div 1.44) div 1000) >= 0.33647222222 and (int(int(decimal-time(.)*1440) div 1.44) div 1000) <= 0.85327777777

Example 5: Complex or unusual syntax

• Input: The label of the choice selected for job_status
• Output: choice-label(${job_status}, ${job_status})