surveycto-form-reader

SurveyCTO Form Reader

Purpose

This skill lets you parse a SurveyCTO/ODK form definition spreadsheet (.xlsx) into plain-text CSVs you can read, and gives you the domain knowledge to understand the form's structure, variables, skip logic, choice lists, and repeat groups. With this understanding you can:

• Summarize the survey instrument (sections, field counts, flow)
• Generate codebooks / data dictionaries
• Write analysis code (Stata, Python) using correct variable names and value labels
• Build data cleaning and high-frequency check scripts informed by form logic
• Explain what specific variables mean, including their skip conditions

Step 1: Parse the form definition

The form .xlsx cannot be read directly. Run the parser script:

python3 /path/to/this/skill/scripts/parse_form.py "<path_to_form.xlsx>" --outdir /tmp/form_parsed

This produces CSV files in the output directory:

• survey.csv — all fields, groups, and their properties
• choices.csv — all choice lists with list_name, value, label
• settings.csv — form title, form ID, default language, version
• summary.txt — a human-readable overview of the form

Read summary.txt first for a quick overview, then consult the CSVs as needed for details.

If the script is not at the expected path (e.g., the user installed the skill elsewhere), look for parse_form.py inside a scripts/ folder adjacent to this SKILL.md.

Step 2: Understand the form structure

After parsing, read references/surveycto-form-spec.md (adjacent to this SKILL.md) to understand how to interpret the parsed data. Key concepts:

• survey sheet: each row is a field. The type column determines what kind of field it is. The name column is the variable name in exported data. label is the question text. relevance is skip logic. constraint restricts valid entries.
• choices sheet: defines value labels for select_one and select_multiple fields. Linked by list_name.
• Groups: begin group / end group rows define sections. begin repeat / end repeat define roster/loop structures.
• Field types: text, integer, decimal, select_one listname, select_multiple listname, date, datetime, geopoint, calculate, note, and more.