*! version 1.06 Felix Schmieding 19/07/2021

Title

kobo2stata -- Create labelled Stata datasets from KoboToolbox

Syntax

kobo2stata
using
filename,
xlsform(xlsfile)
[options]

Mandatory items

using filename Name and location of the .xlsx file
that contains the Kobo raw data.

xlsform(xlsfile) Name and location of the .xls file
that contains Kobo's XLSForm. This file must contain a 'survey' and a 'choices' tab.

Options

surveylabel(columnheader) Header of the column in the XLSForm's
'survey' tab that contains the applicable variable labels.
Specifying this item is optional - if nothing is specified, 'label' is assumed.

choiceslabel(columnheader) Header of the column in the XLSForm's
'choices' tab that contains the applicable value labels.
Specifying this item is optional - if nothing is specified, 'label' is assumed.

dropnotes Drop variables identified as 'note'-type in the XLSForm (this type of variable
contains no data).

usenotsave This will load the imported dataset into Stata‘s active memory rather
than saving to drive. Please note this option is not recommended for (hierarchical)
Kobo datasets with multiple tabs in the raw data file - for these, only the last tab would be
loaded to memory.

Description

kobo2stata combines the information contained in the raw data file and the
XLSForm, and creates labelled Stata datasets. The main focus is on applying the variable labels
and value labels in the XLSForm to the data. There are also some secondary functions, e.g. the removal of HTML tags from labels.
Please read the important remarks below on generating the input files in KoboToolbox.

Important remarks on generating input files in KoboToolbox

For kobo2stata to work properly, the two input files - i.e. the data file and XLSForm -
must be exported from KoboToolbox as follows:

o For the raw data file, go to Kobo's 'Downloads' and then 'Data' section,
then select export type 'XLS' and value/header format 'XML values and headers'.
Deactivate the 'include groups in headers' checkbox.
Then click 'export' and save the .xlsx file that is generated.

o For the XLSForm, go to Kobo's 'Downloads' and then 'Form' section,
then select the '...' symbol at the top right ("more actions"), and select 'Download XLS'.

Further remarks

Kobo2stata will only consider numeric values found in the "name" column of your XLSForm's choices tab.
String values will be ignored, and will result in missing value labels for single-choice variables, and missing
variable labels as well as missing value labels for multiple-choice binary variables.

Kobo2stata creates the Stata datasets in the same location as the original raw data file (except if the 'usenotsave' option is specified, in which case no dataset is saved).

Kobo2stata can handle raw Kobo datasets with hierarchical data / multiple tabs.
No restructuring or merging is carried out, kobo2stata will create the same
number of Stata datasets as there are tabs in the .xlsx file.

The surveylabel() and choiceslabel() options allow the user to specify the
relevant label columns in the XLSForm's 'survey' and 'choices' tabs, respectively.
By default, Kobo uses the column header 'label', and this is what kobo2stata assumes if the
options are not specified by the user. However, some Kobo applications - in particular multilingual ones,
may use other headers (e.g. 'Label:English').

Kobo allows non-exclusive numeric values in value labels, but Stata does not.
For example, answer choices "0-red", "0-blue", "0-green", "1-yellow" (such non-exclusive codes are sometimes applied in multiple-choice exams,
where all incorrect answers carry a value of zero). While all different answer choices
will be displayed separately in Kobo, Stata cannot differentiate between the different types of zeroes.
Hence, if your XLSForm's choices tab contains non-exclusive values for a given label set, your Stata dataset will contain only the last
label found for the duplicate value (i.e. in the above example, all zeroes would be labelled "green").

Kobo puts no length limitations on variable names and value label names, but Stata limits them to 32 characters.
Any variable names or value label names with more than 32 characters in your Kobo data
(or more than 29-30 characters in the case of select_multiple items) will remain
unlabelled in the Stata dataset created.

Examples

Create Stata dataset(s) from a raw dataset and accompanying XLSForm:

. kobo2stata using "C:/mydata/kobosurveydata.xlsx", xlsform("C:/mydata/aDyQEvcRVs9re5L.xls")

Same as above, but with non-standard column headers specified in the XLSForm:

. kobo2stata using "C:/mydata/kobosurveydata.xlsx", xlsform("C:/mydata/aDyQEvcRVs9re5L.xls")
surveylabel("Label::English") choiceslabel("Label::English")

Author

Felix Schmieding

For questions or suggestions, e-mail kobo2stata@gmail.com

(v1.06)