Difference between revisions of "Ietestform"

Jump to: navigation, search
Line 29: Line 29:
 
There are two tests in '''ietestform''' related to this.
 
There are two tests in '''ietestform''' related to this.
  
===== All Non-Note Fields Required =====
+
===== '''All Non-Note Fields Required''' =====
 
This test tests that all fields that is not of type ''Note'' (see the other Required Column test below) has the value "Yes" in the required column. This test writes a list to the report for all fields that are not required and not of type note.
 
This test tests that all fields that is not of type ''Note'' (see the other Required Column test below) has the value "Yes" in the required column. This test writes a list to the report for all fields that are not required and not of type note.
  
 
Even for questions where it is sometimes expected that there is no answer to be recorded, it is much better practice to have a answer option that represents "No Answer" rather than leaving the field unanswered.
 
Even for questions where it is sometimes expected that there is no answer to be recorded, it is much better practice to have a answer option that represents "No Answer" rather than leaving the field unanswered.
  
'''Acceptable Exceptions:'''
+
''Acceptable Exceptions:''
 
* Fields that require the GPS function on the device. GPS locations are sometimes difficult to collect for some devices in some contexts. This should be tested before and during the pilot and if it seems as if it will be difficult, then it is ok to make these field types not required.
 
* Fields that require the GPS function on the device. GPS locations are sometimes difficult to collect for some devices in some contexts. This should be tested before and during the pilot and if it seems as if it will be difficult, then it is ok to make these field types not required.
  
===== No Note Fields Required =====
+
===== '''No Note Fields Required'' =====
 
For fields of type note there is no way to record data, and there is therefore no way to pass a required note field. If this happens in the field there is no way to pass this field, and therefore no way to complete and submit the data. See the exception below for a use case when this is a feature important to use for data quality reasons. This test writes a list to the report of all required note fields.
 
For fields of type note there is no way to record data, and there is therefore no way to pass a required note field. If this happens in the field there is no way to pass this field, and therefore no way to complete and submit the data. See the exception below for a use case when this is a feature important to use for data quality reasons. This test writes a list to the report of all required note fields.
  
'''Acceptable Exceptions:'''
+
''Acceptable Exceptions:''
 
* This impassable note field has one very useful intended use case which is forcing the enumerator to go back and change something that is not correct. For example, enumerators are often asked to enter respondent IDs twice to be extra careful that there is no typo in the ID. If those two note fields are <cod>id1</code> and <cod>id2</code> then there can be a ''required'' note field that has the relevance expression <cod>${id1} != ${id2}</code>. The same functionality could have been achieved using the constraint field when the ID is re-entered, but the label in the note can be made more informative than the constraint message, and when the conditional test is more difficult than just testing that two fields are identical, then this method is easier intermediate calculate fields can be used.
 
* This impassable note field has one very useful intended use case which is forcing the enumerator to go back and change something that is not correct. For example, enumerators are often asked to enter respondent IDs twice to be extra careful that there is no typo in the ID. If those two note fields are <cod>id1</code> and <cod>id2</code> then there can be a ''required'' note field that has the relevance expression <cod>${id1} != ${id2}</code>. The same functionality could have been achieved using the constraint field when the ID is re-entered, but the label in the note can be made more informative than the constraint message, and when the conditional test is more difficult than just testing that two fields are identical, then this method is easier intermediate calculate fields can be used.
  

Revision as of 18:59, 6 December 2018

ietestform is a Stata command used to test ODK based SurveySCTO forms before they are used in the field. SurveyCTO's server has a test feature that tests the ODK syntax of the form. This command is not meant as a substitute to that test, but a complement as it test for constraints specific to Stata and that the best practices used at DIME are followed.

This article is meant to describe use cases, work flow and the reasoning used when developing the commands. For instructions on how to use the command specifically in Stata and for a complete list of the options available, see the help files by typing help ietestform in Stata. This command is a part of the package iefieldkit, to install all the commands in this package including this command, type ssc install iefieldkit in Stata.

Intended use cases

This command is intended to be used after it is tested on SurveyCTO's server to make sure that there is no syntax errors in the form, but before it is used in the field. This command writes a report that outputs the results of several tests (the tests are described below). The report is in csv-format so it can be viewed in Excel and is raw text so it can be tracked in versioning control frameworks like GitHub.

This command has many different tests but only some of them are direct errors. The tests that are not errors are meant to highlight things that experienced ODK coders in SurvyeCTO usually looking for to spot errors. Sometimes these things are not errors, but actually the best way to code something, but make sure that you understand all cases listed in the report, and why they are potentially a bad practice.

If you are not sure why something was listed, then read the explanations of each test below. If you think that the command incorrectly catches cases in your SurveyCTO form then please report that here.

Instructions

These instructions are meant to help you understand how to use the command. For technical instructions on how to implement the command in Stata see the help files by typing help ietestform in Stata.

This command is very simple to use in Stata, you only need to specify your SurveyCTO form and where on your computer you want the command to write the report.

ietestform, form("$projectfolder/questionnaire.xls") report("$outputfolder/form_report")

Explanation of tests used in this command

ietestform only outputs results form tests that identified an error or a potential bad practice. If a test does not find anything, the test is not at all mentioned in the report.


Coding Practices

This section describes tests related to best practices on how to use and how to not use the ODK programming to ensure a good work flow in the form. Note that these tests does not test if the ODK syntax is valid since this command is intended to be usedafter the form has passed SurveyCTO's ODK syntax tester. This tests that the form uses ODK programming in a way that follows best practices that avoids errors in the field and help ensure high data quality.

Required Column

The required column make sure that the enumerator cannot proceed before a response have been filled in for that field. This is a great feature as it prevents incomplete forms to be submitted, and it helps making sure that enumerators fill in the forms in the right order. A field that is required can not be passed until data has been recorded for it.

There are two tests in ietestform related to this.

All Non-Note Fields Required

This test tests that all fields that is not of type Note (see the other Required Column test below) has the value "Yes" in the required column. This test writes a list to the report for all fields that are not required and not of type note.

Even for questions where it is sometimes expected that there is no answer to be recorded, it is much better practice to have a answer option that represents "No Answer" rather than leaving the field unanswered.

Acceptable Exceptions:

  • Fields that require the GPS function on the device. GPS locations are sometimes difficult to collect for some devices in some contexts. This should be tested before and during the pilot and if it seems as if it will be difficult, then it is ok to make these field types not required.
'No Note Fields Required

For fields of type note there is no way to record data, and there is therefore no way to pass a required note field. If this happens in the field there is no way to pass this field, and therefore no way to complete and submit the data. See the exception below for a use case when this is a feature important to use for data quality reasons. This test writes a list to the report of all required note fields.

Acceptable Exceptions:

  • This impassable note field has one very useful intended use case which is forcing the enumerator to go back and change something that is not correct. For example, enumerators are often asked to enter respondent IDs twice to be extra careful that there is no typo in the ID. If those two note fields are <cod>id1 and <cod>id2 then there can be a required note field that has the relevance expression <cod>${id1} != ${id2}. The same functionality could have been achieved using the constraint field when the ID is re-entered, but the label in the note can be made more informative than the constraint message, and when the conditional test is more difficult than just testing that two fields are identical, then this method is easier intermediate calculate fields can be used.

Numeric Ranges

Match _begin/_end

For this reasons the command also tests that all _end fields also have a field name. This is not required in ODK.


Naming and Labeling Practices

Field Name Length

Repeat Group Field Name Length

Repeat Group Name Conflict

Stata Labels Columns

Explanation of using language as label column

Survey Sheet
Choice Sheet

Choice Lists

Value/Name Numeric

Duplicated List Codes

Duplicated List Labels

Unused Lists

Missing Labels

Labels With No Value/Name

Back to Parent

This article is part of the topic ietoolkit