*! version 1.0 11feb2025

Title

surveyspan -- Analyze and monitor survey timing metrics

Syntax

surveyspan startvar endvar [if] [in] [, options]

Main
generate(newvar) create new variable for calculated durations

mintime(#) specify minimum acceptable duration in minutes

maxtime(#) specify maximum acceptable duration in minutes

cutoff(#) specify hour cutoff for after-hours flags (default: 17)

groupvar(varname) generate Excel report grouped by specified variable

outfile(filename) specify name for Excel output file (requires groupvar)

Description

surveyspan is an R-class command that analyzes timestamp metadata from field surveys to monitor data collection quality and identify timing issues. It processes start and end times in standard XLSForm format (YYYY-MM-DDThh:mm:ss) as used by KoboToolbox, SurveyCTO, and ODK. The command automatically handles common data issues such as single-digit days in timestamps and negative durations, excluding invalid timestamps.

Time variables must exist in the dataset and be string type. The command will exit with error if:

- Time variables are not found in dataset

- Time variables are not string type and in the standard timestamp format

- Cutoff hour is not between 0 and 23

- Mintime or maxtime are negative

As its core function, the command calculates survey durations and flags potential issues such as rushed interviews or after-hours data collection. Generated duration variables are automatically labeled with "end_time - start_time".

When groupvar is specified, it creates an Excel workbook (sheet "Summary Stats") with comprehensive statistics including mean durations, excluded observations, and various quality indicators by the specified groupvar (date, region, enumerator id etc.).

Options

Main

generate(newvar) saves calculated durations to the specified new variable.

mintime(#) specifies the minimum acceptable survey duration in minutes. Surveys below this threshold are flagged.

maxtime(#) specifies the maximum acceptable survey duration in minutes. Surveys above this threshold are excluded from calculations.

cutoff(#) specifies the hour (in 24-hour format) after which surveys are flagged as after-hours. Default is 17 (5 PM). If the end time occurs after the specified cutoff hour (default: 17), the interview is flagged as an after-hours survey. These flagged surveys can be reviewed in the optional Excel output.

groupvar(varname) generates detailed Excel reports grouped by the specified variable. The report includes: - Mean and median survey durations - Number of excluded observations - Proportion of surveys flagged as after-hours - Count of surveys below the minimum time threshold and so on.

Examples

Setup example dataset:

clear

set obs 100

00:00" in 1/20"'

00:00" in 21/40"'

00:00" in 41/60"'

00:00" in 61/80"'

00:00" in 81/100"'

05:00" in 1/10"'

30:00" in 11/30"'

08:00" in 31/50"'

45:00" in 51/70"'

03:00" in 71/100"'

gen enum_id = ceil(_n/20)

gen region = ceil(_n/50)

Basic use:

surveyspan starttime endtime

Save durations to new variable:

surveyspan starttime endtime, generate(survey_length)

Set timing thresholds:

surveyspan starttime endtime, mintime(10) maxtime(120)

Analysis by enumerator:

surveyspan starttime endtime, groupvar(enum_id)

Comprehensive analysis:

surveyspan starttime endtime, generate(interview_duration) cutoff(18) mintime(15) groupvar(enum_id)

Stored results

surveyspan stores the following in r():

Scalars

r(total_obs) number of observations available

r(used_obs) number of observations with valid durations

r(mean) mean survey duration

r(median) median survey duration

r(sd) standard deviation of survey duration

r(within_sd_pct) percentage of observations within one standard deviation of mean

r(aft_cutoff_count) number of surveys after cutoff

r(aft_cutoff_pct) percentage of surveys after cutoff

Authors

Kabira Namit

World Bank

knamit@worldbank.org

Ketki Samel

Centre for Effective Governance of Indian States

ketkisamel1@gmail.com

Acknowledgments

Special thanks to Zaeen de Souza who always has brilliant suggestions and advice regarding nascent Stata modules and is also the one who suggested the Excel output option and the reporting of the standard deviation numbers for surveyspan, and also to Prabhmeet Kaur for testing and reviewing surveyspan.

For updates and bug reports, please email: knamit@worldbank.org