Skip to content

Home

Jump to bottom
iabaako edited this page Apr 26, 2021 · 19 revisions

Overview

ipacheckscto is a Stata Module designed to check your SurveyCTO XLS form for common programming errors and best practices and outputs a list of issues and recommendations on the Stata result window with an option to export to an excel file. The SurveyCTO server and the desktop application already have built-in form validation tools that check XLS forms for syntax errors in forms. ipacheckscto compliments these tools by running additional test for the following:

  • common programming errors
  • IPA recommended practices

ipacheckscto should therefore be used only after the form validating the XLS form through the server or the desktop application.

NB: Not all issues flagged by ipacheckscto will require correction. Review the output carefully and decide if you need to make any changes to your form.

Software Requirements

ipacheckscto makes extensive use of Stata. Some parts of the program are also heavily dependent on Stata’s excel modules in order to create output files that are easy to use and disseminate. The excel modules are only available in Stata 14 or later and therefore requires that the user has Stata 14.0 or later installed on their machine prior to running ipacheckscto. IPA employees with older versions of Stata should contact IT for access to a newer version.

Installation

ipacheckscto is collated and distributed as a Stata package through github. You can install ipacheckscto directly from github by running the following line of code in your command line or by using a do-file:

net install ipacheckscto, all replace from("https://raw.githubusercontent.com/PovertyAction/ipacheckscto/master/ado")

ipacheckscto package file includes the following files:

  • ipacheckscto.ado – Stata program file
  • ipacheckscto.sthlp – Stata helpfile
  • ipacheckscto.dlg – Stata dialog file

Syntax

help ipacheckscto

using options

outfile(filename) Specifies the output path and filename for exporting results into excel. The filename must include the extension .xls or .xlsx.

If outfile() is not specified, results will be displayed in the Stata result window only.

other(integer) Specifies the integer value for other specify option. If this option is specified, ipacheckscto will flag select_one/select_multiple fields which

  • use other specify option in their choice list but are missing a child other specify field;
  • have a child other specify field but appears after the child other specify field;
  • use the or_other syntax. for instance select_one fruits or_other

If other() option is not specified, ipacheckscto will only check for or_other syntax.

dontknow(integer) Specifies the integer value for don't know option. If specified, ipacheckscto will flag;

  • select_one/select_multiple fields which use choices list that does not include a don't know option;
  • integer/decimal/text fields that do not accept don't know values

If dontknow() option is not specified, ipacheckscto will skip the don't know entirely.

refuse(integer) Specifies the integer value for refuses to answer option. If specified, ipacheckscto will flag;

  • select_one/select_multiple fields which use choices list that does not include a refuses to answer option;
  • integer/decimal/text fields that do not accept refuses to answer values

If refuse() option is not specified, ipacheckscto will skip the refuse check entirely.

Example

Check a SurveyCTO XLS form and display results on Stata window.

ipacheckscto using "C:\Users\Documents\Bontanga Baseline.xlsx“

Check a SurveyCTO XLS form and display results on Stata window. Include checks for other specify with the value of -666

ipacheckscto using "C:\Users\Documents\Bontanga Baseline.xlsx", other(-666)

Check a SurveyCTO XLS form and display results on Stata window. Include checks for other specify (-666), dontknow(-999) and refuse to answer (-888).

ipacheckscto using "C:\Users\Documents\Bontanga Baseline.xlsx", other(-666) dontknow(-999) refuse(-888)

Check a SurveyCTO XLS form and display results on Stata window. Include checks for other specify (-666), dontknow(-999) and refuse to answer (-888). Export results to excel file "C:\Users\Documents\output\botanga_baseline_check.xlsx"

ipacheckscto using "C:\Users\Documents\Bontanga Baseline.xlsx", other(-666) dontknow(-999) refuse(-888) outfile("C:\Users\Documents\output\botanga_baseline_check.xlsx")

Dialog box

Get the dialog box by typing db ipacheckscto in the Stata command window:

examples

Check a SurveyCTO XLS form and display results in Stata results window. Include checks for other specify (-666), dontknow(-999) and refuse to answer (-888).

Check a SurveyCTO XLS form and export results to "C:/.

Check a SurveyCTO XLS form and export results to "C:/. Include checks for other specify (-666), dontknow(-999) and refuse to answer (-888).

Workflow

While using ipacheckscto the programmer may need to run ipacheckscto multiple times on their instrument. The diagram below shows a suggested workflow for programming in SurveyCTO.

  1. Get the XLS version of SurveyCTO form: Most programmers already program their survey in excel and already have the XLS form. If the XLS form is on google sheets then you will need to download it in .xlsx format. You may also download an XLS form from the server if you used the online form editor.

  2. Upload your XLS form to a SurveyCTO server or run it through the validate form tool on SurveyCTO Desktop application to verify and correct any syntax issues.

You can skip this step if you already downloaded your form from the server.

  1. Run ipacheckscto and review results carefully. Make any necessary adjustments to your form.

Repeat steps 2 and 3 until you are satisfied with the status of your form.

  1. Download the form onto the collect app for bench testing/piloting.

Checks

Check 0. summary The summary results/sheet shows information about the XLS form as well as a summary of the results from the various checks. In the `output()` sheet, the sheet "summary" contains the result of this check.

Form Details:

The form details section of the summary sheet shows basic information about the XLS form that was checked. This include:

Filename: Actual filename of the XLS form that was checked

Form Title: This is the title of your form. The form title is under the column “form_title” in the “settings” sheet of the XLS form.

Form ID: This is the unique ID that will identify the form. The form ID is under the column “form_id” in the “settings” sheet of the XLS form.

Form Definition Version: This is the version number of the form, which you must increase each time you modify an existing form. If you started with a form template or with one of the sample forms, then this is determined by a formula and is therefore automatic: so may not necessarily match the version number on the server.

**Number of Languages: This is the number of languages in the XLS form. This number is determined by counting the number of label columns in the “survey” sheet of the XLS form.

Default Language: This is the name of the language associated with labels, images, and other content when no other language is specified. Form Encrypted:** This indicates “Yes” if the form data is encrypted using the SurveyCTO encryption keys and “No” if otherwise. IPA requires that all SurveyCTO forms be encrypted.

Number of Publishable Fields: This indicates the number of fields marked as publishable in the XLS form if the XLS form is encrypted. This is left blank if the XLS form is not encrypted.

Submission URL: This is the submission URL to use when submitting encrypted forms. The form will not accept form submissions if it is uploaded to a server that is different from what is indicated in the “submission_url” URL column of the “settings” sheet. The SurveyCTO server debug tool does not detect this discrepancy. However, enumerators may not be able to submit data from this form to our server and will continually get a prompt to re-enter the password whenever they try to submit the form.

Check summary:

The check summary section of “summary” sheet indicate the results of each check. The results are color coded based on the following general rules:

  • issues identified [#FFB6C1] – This indicates that the specified check was run, and a certain number of issues were identified in the XLS form.
  • no issues identified [#90EE90] – This indicates that the specified check was no issues were identified in the XLS form.
  • check was skipped [#FFFFE0] – This indicates that the specified check was skipped because it was not applicable to the XLS form. This only applies to checks 7, 8 and 9.

list of checks

check description
1. recommended fields Display status of recommended/meta-data fields in XLS form
2. field names Flag issues in field names
3. disabled, read only Flag fields that are disabled or marked as read only
4. field requirements Flag fields with various requirement issues
5. constraint Flag fields with constraint issues
6. other specify Flag issues with other specify
7. dont know, refuse Flag field that do not allow for don't know and refuse to answer
8. group names Flag groups with mismatch in group names at begin & end
9. repeat fields Flag illegal use of repeat fields
10. choices Flag duplicates or missing values/labels in choices
Check 1. recommend fields Checks SurveyCTO XLS form for IPA recommended fields and shows the results in the “1. recommended fields” sheet. This sheet includes “required” and “recommended” sections.
Clone this wiki locally