brendenandoseh-code/cepa-household-survey-odk

ODK/XLSForm instrument and submission-cleaning pipeline for a community health survey originally run on paper in Lesotho. Consent gating, cross-field constraints, tested Python cleaner. # CEPA Household Survey — ODK/XLSForm instrument and cleaning pipeline A digitised version of a community health survey I designed and ran on paper as a Peace Corps Volunteer in Lesotho, rebuilt as an ODK XLSForm with the submission-cleaning pipeline that should have gone with it. **What is here** | File | What it is | |---|---| | `build_xlsform.py` | Source of truth for the form. Generates the XLSForm workbook. | | `cepa_household_survey.xlsx` | The XLSForm itself — `survey`, `choices`, `settings` sheets. | | `cepa_household_survey.xml` | The compiled ODK form, produced by pyxform. | | `clean_submissions.py` | Reads an ODK Central CSV export, validates it, and produces analysis-ready output. | | `test_clean_submissions.py` | Tests asserting numerical behaviour of the cleaner. | | `data/sample_submissions.csv` | **Synthetic** submissions used to demonstrate the pipeline. | ## Why I built it In 2024 I ran a 16-household structured community health survey in Ha Monyake, Mohale's Hoek District, as the community-entry assessment for my Peace Corps assignment. It was done on paper and tallied by hand into a table. The findings held up — 7 of 16 households had a member living with HIV, 4 of 16 were single-parent households, 7 of 16 included someone aged 65 or over, and the infrastructure gaps residents named (electricity, water, roads) became the evidence base for a funded community intervention. What it did not have was a data pipeline. Paper forms mean no constraint enforcement at the point of collection, no audit trail, and a transcription step where errors enter silently. This repository is that survey rebuilt the way I would build it now. ## The form `build_xlsform.py` is the source of truth rather than the spreadsheet, because an `.xlsx` is a zip archive and reviewing a diff of one is guesswork. The script writes the workbook; pyxform compiles it. The instrument follows the original paper survey. Every question and every answer option comes from the questio …