-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathConfigure-forms.Rmd
182 lines (92 loc) · 14.9 KB
/
Configure-forms.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
---
title: "Configure forms"
---
```{r options_communes, include=FALSE}
source("options_communes.R")
```
<div class="important">
Configure forms can be done both through the Kobobuilder interface or within Excel.
using kobobuilder comes with Risk when the form is complex.
The second options is preferred as it allows for more controls.
</div>
## XLSFORM
The form needs to be defined using the xlsform format.
XLSFORM is a form standard created to help simplify the authoring of forms in Excel. Authoring is done in a human readable format using a familiar tool that almost everyone knows - Excel. XLSFORMs provide a practical standard for sharing and collaborating on authoring forms. They are simple to get started with but allow for the authoring of complex forms by someone familiar with the syntax described below.
The XLSFORM is then converted to an X-Form, a popular open form standard, that allows you to author a form with complex functionality like skip logic in a consistent way across a number of web and mobile data collection platforms.
The documentation on xlsform is [here](http://xlsform.org/). The same format is actually used by multiple data collection technological platform such as [kobotoolbox](http://www.kobotoolbox.org/)(the platform used by UNHCR on [http://kobo.unhcr.org](http://kobo.unhcr.org)), [OpenDataKit](https://opendatakit.org/) or [ONA](https://ona.io).
## Some tips
Good questionnaire design can save hours at latter stage for the person that will need to analyse the data.... do invest enough time for this step and allow for peer review before starting the [testing phase](s://unhcr.github.io/Integrated-framework-household-survey/Pre-test-Phase.html) !!
### Manage your xls form
* Make sure your file is saved in the .xls format and contains no spaces or special characters (‘‐’ and ‘_’ are allowed).
* Make sure that your column headers are in lowercase (i.e. “label” or “name”, not “Label” or “Name”)
* Make sure that your sheet names are appropriately named (i.e. “survey” not “Sheet 1”, “Survey” or “surveys”)
* Make sure that the question names are unique and do not contain spaces or special characters (‘‐’ and ‘_’ are allowed).
* By the end of the coding sessions, there will be several versions of the MS Xls files. It is crucial to separate each according to versions and also to make sure the names do not in clude any spaces or begin with numbers or special characters.
### Variable Encoding
* The "name" column must be within 32 characters, cannot begin with a number or any special character and cannot contain any spaces in between; otherwise ODK Validate will issue an error. The longer your name is and the more time you will have to spend searching for what that specific variable or choice is in your database. Also, Kobo doesn’t accept answer choice names that contain more than 32 characters and question/ variable names no longer than 30 characters
* Please use a short meaningfull name for your variable rather than a code like Q1 or Q2. The name should mean something to you and should be clear as to what it refers to.
* Having a consistent and harmonised naming system throughout your survey, with descriptive/meaningful and easy to remember names for your variables/questions and choices, will allow you to quickly find the variable(s) to be modified. On the contrary, should you have a non-harmonised naming system with names that are non-descriptive, it will take you much more time than expected to find the variables of interest and to modify them.
* In order to anticipate the analysis with a statistical package like [koboloadeR](https://unhcr.github.io/koboloadeR/docs/), limit variable names lenght to 12 characters and do not start a variable name with a number.
* Avoid underscores («_») in the technical name of the variable. It can sometimes be recognised as a «separator» by certain statistical packages. Do not hesitate to rather use the «camelCase» (consists on writing a group of words in lowercase with the first letter of the lined words in uppercase).
* Name should not contain any spaces, accentuation (“à è ô”) or special characters (“+”, “%”, “&”,“(“, “/”, etc.).
* Names should not start with a number: You can use numbers in your names, but rather at the end or in the middle of your name so that it is instantly clearer as to what information it refers to.
More tips on variable name encoding are available [here](https://www.dropbox.com/s/em0s143xniqvc7j/Recommendations%20for%20the%20naming%20of%20questions%20variables%20and%20answer%20choices_EN_1802.pdf?dl=0)
### Labeling questions
* Numbering questions does not provide added value -- during data entry enumerator are forced to respect the order any way. In addition, if you start numbering questions, any change in the questionnaire will then require to renumber all questions.
It's a good example of something that was important when people were using paper form but has no reason to be used anymore when moving to digital data collection.
* Quick translation can be done with [Google translate](https://translate.google.com/). Obviously the resulting translation needs to be carefully reviewed but it save the time to retype the whole text and does not prevent from the [translation review described here](https://unhcr.github.io/Integrated-framework-household-survey/Guidelines-for-Customisation.html#translation). It's also a good way to test the simplicity of the sentence used for the questions: if the artificial intelligence from Google translate can not decipher the questions, it means that it will be also probably difficult for the respondant. One test to confirm the question phrasing can also to translate and re-translate back in the original language in order to see if the meaning of the question is preserved.
* When there's a question like _first reason, second reason, third reason_ or _first source of income, second soure of income, third source of income_, the bad practise is actually to have 3 separate select_one questions: aka _first reason_ - then _second reason_, then _thirst reason_ -- First, from a cognitive point of view, respondents will have a hard time to rank among more than 5 options, second when recorded through 3 distinct variables, data will need a lot of coding to reshape the data in way where the analysis will make sense...
-- here the 2 options are either:
* select_multiple with a constraint count on the number of modality you can select "<code>not(count-selected(.) < 4</code>" --- often it's simpler as very likely the ranking between options will be difficult to analyse
* or go for a rating [likert]( https://unhcr.github.io/Integrated-framework-household-survey/Module-questions.html#question-design) questions for each options -- and then the ranking will be performed during the analysis through the sum of the rates for each respondent.
### Questionnaire structure
* All "begin group" types must have a corresponding "end group". It is advised to name each of the begin group and end group "name" as well as "label" columns for easy identification of where a group starts and ends, e.g. "type– begingroup. Name – grp_agri_aman. Label – Aman Rice. T ype – end group. Name – endgrp_agri_aman. Label – no labels are required as this won't show up in the form.
* There can be a mother group with several child groups within, however each group essentially works like brackets which open, can remain open, close or close at the end. It can get rather complicated once several questions within a group are to be skipped.
* DO NOT LEAVE A SPACE AFTER your "type" or "name" variables, e.g. "end group ". It is an invisible error that will cause the form to malfunction.
* It is a good practice to keep naming the questions "label" as “Name of Household Head... Age of Respondent...Please specify what you mean by "Other"...and so on”. The same can be done for "name" variables but one must remember that they cannot start with an uppercase letter, e.g. “name_hhh” is allowed.
### Make your questionnaire smart
* Use hints as much as possible - a good example is to recall to your enumerator how to proceed with select question for instance two options are possible :
* Read the list and select all (or only the right) answers
* Do not read the list - wait for the answer to select the right answer(s)
* The "note" and "calculate" type of questions can be really handy and must be used whenever there is a reason to check back with data entered previously. E.g. "type – calculate, name – calc_loan, calculation - ${loan_1}+{loan_2}+{loan_3}" with "type – note, name – chk_total_loan , label – Your breakdown of total loans ${loan_1} and ${loan_2} and ${loan_3} add up to ${calc_loan}. Please make sure they are equal to the amount entered before as total loan ${totalloan}.
* Systematically add constraint to your numeric questions: age can not be negative or bigger than 120. Add also constraint on linked values: for instance if you know the number of children in a family, the number of boys can not be bigger than the total number of children. Do not forget to add __constraint_message__ to help your enumerator to fix the issue!
* When you do a calculation, __beware of zero__ : To convert empty values to zero, use either the coalesce() function or the if() function. See the form logic functions reference below. "+ ‐ *" correspond to add, subtract, and multiply. Division however, is special, and you need to use the word “div” to do division.
* The best types of constraint and relevance are usually the simplest. When typing the binding guidelines (http://opendatakit.org/help/form - design/binding/) can simplify the entire line of code. Also this is the most interesting and perhaps challenging part of writing questionnaires. Users are free to develop their own lines of code and put them to the test. For any help the Google ODK groups are more than sufficient.
* If the questions need to be translated into a local language, the input must be in __Unicode__. Also it is imperative to make sure that questions in the base language are translated with the meaning intact. Difference in interpretation can cause severe errors in the quality of the data.
* Systematically add the metadata field: type: 'start', 'end', 'today', 'deviceid', 'imei', 'phonenumber'
* To record __admin level__, use [cascading drop down lists](http://xlsform.org/en/#cascading-selects). Note that this does not work well whem more than 500 options. In this case, one option is to use select_external : http://xlsform.org/en/#external-selects but this will work only if data collection is done with Android client (not the web client).
* Record correctly registration case number using a regex constraint where caret is the [ASCII special character](https://en.wikipedia.org/wiki/Caret):
* for case number: "<code>regex(.,'caret[0-9]{3}-[0-9]{2}[C][0-9]{5}$') </code>"
* and for Individual number "<code>regex(.,'caret[0-9]{3}-[0-9]{2}[I][0-9]{5}$')</code>"
* Record case number using bar code scanner whenever possible - rather than manual data entry.
* Add constraint on email validation through the same regex: "<code>regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}')</code>". This can be more specific if a specific email domain is expected.
* Calculate years from date (age from date of birth) "<code>round((decimal-date-time(${today}) - decimal-date-time(${dob})) div 365.24, 0)</code>".
* Validate past date (constraint) "<code>decimal-date-time(.)<decimal-date-time(${today})</code>".
* Use "or_other" whenever you have a select_one or select_multiple questions that may have additional modalities that you can not anticipate
* If you have a select_multiple question with one modalites being "None of the options mentionned here", use a contraint to ensure that respondant will not select this options with other: "<code>not(count-selected(.) > 1 and selected(., 'no'))</code>"
* Review the __appearance__ [options](http://xlsform.org/en/#appearance) : Beware some options (like ) are only for web client while other (like "quick") are only for the android client.
### Keep your xlsform legible
* It is possible to separate different sections of the questionnaire using different cell colours. It does not make a difference for ODK, but makes the form much more navigable.
* In the same idea, in Excel, freeze the top row cell and add automatic filters to quickly navigate through your questions (survey) and answers (choices).
* In the choices sheet, a gap or (blank row) can be left after each set of answers. Again, it doe s not make a difference for ODK but makes it much easier for navigation.
### Validate & Deploy the form
* kobotoolbox has some built-in __validation check & debugging check__ when a xlsform is uploaded. Sometimes better validation / debugging support can be obtained by other online validator such as [https://opendatakit.org/xlsform/](https://opendatakit.org/xlsform/)
* For review purpose, you may find usefull to have a beautifull transcript in word of your xlsfrom using [PPP for Open Data Kit](http://ppp.pma2020.org/)
* Note for field deployment: if possible, users must try and keep a copy/image of the entire " ODK " folder inside the memory of the tablet and save it elsewhere for later reference. If planning requires users to clear out " ODK " and re insert a questionnaire for easy tracking, then this step becomes very a vital safe guard.
* one point is also that as for dataviz, good questionnaire are the result of multiple persons looking at it -- hence the importance of peer review -- peer review is different from testing - it requires people with expertise in questionnaire design to review - this is among the support than can be requestioned from regional offices.
## Additional tips
Additional tutorials and tips can be found through the following links:
* [Open data kit Form Logic](https://docs.opendatakit.org/form-logic/)
* [Open data kit Form operator functions](https://docs.opendatakit.org/form-operators-functions/)
* [Open data kit Form design guides](https://opendatakit.org/help/form-design/)
* [Open data kit work around](https://opendatakit.org/help/form-design/workarounds/)
* [Other training guides](https://opendatakit.org/help/training-guides/)
* [Tips from the Mobile Data Collection Toolkit](https://www.mdc-toolkit.org/design-your-forms/)
* [Advanced XLSFORM coding tips #1](http://blog.cartong.org/2015/08/11/advanced-xls-forms-coding-1/)
* [Advanced XLSFORM coding tips #2](http://blog.cartong.org/2015/08/21/advanced-xls-forms-coding-2/)
* [ACF XLSFORM coding tips](https://odk.acf-e.org/odk/LinkedDocuments/Annex%204%20ODK%20ACF-E%20How%20to%20author%20surveys%20for%20ODK.pdf)
## Support Forum
When faced with specific challenges, multiple online forums can be consulted (as xlsform is used on different platform):
* [Forum for Kobotoolbox](http://support.kobotoolbox.org/)
* [Forum for OpenDataKit](https://forum.opendatakit.org/)