*! version 2.0 24APR2020, developed by William Blackmon (wblackmon@poverty-action.org)

help for sctorezone

Title

sctorezone -- shifts time zones of SurveyCTO datetime and time
fields.

Syntax

sctorezone
shift [if] [in]
, force [only(varlist) | exclude(varlist)]

The shift parameters indicates how much to shift your datetime and/or time fields.
Shift can be formatted for manual or automatic re-zoning:

- Manual: set the number of hours to shift datetime and time
variables forwards (+) or backwards (-). For example, sctorezone +5.5, force
or sctorezone -3, force.

- Automatic: include a calculate field
in your form design that calculates
the data collector’s time zone at the start time of the survey: format-date-time($, '%Y-%b-%e %H:%M:%S').
When exporting data, this field won’t be shifted because all calculate fields are considered strings or numbers,
not datetime or time fields,
regardless of their content. You can then use this calculate field in the command to shift all datetime and time
fields to the same time zone of the data collector’s device, e.g., sctorezone starttime_calculate, force.
This command will calculate the difference between the exported starttime and starttime_calculate fields,
and shift time zones accordingly.

* only(varlist) shift time zone only() for these variables.

* exclude(varlist) shift time zone for all datetime and time
variables, except for these variables.

* force the force option is required as a reminder that
data in time and datetime variables will be overwritten.

The force option is required. Either only() or
exclude() may be included, or neither.

Description

SurveyCTO exports datetime and time fields relative to the
time zone of the exporting computer,
not the time zone of the data-collection device. sctorezone is a great tool
to shift these fields back to the time zone where the data was collected. This command
changes the time zones of datetime fields formatted according to the
SurveyCTO .do file template,
i.e., in %tc format, and time fields using SurveyCTO standard format (e.g. "12:34:56 PM").
Unless the only or exclude option is specified, all variables in %tc format
and all string variables following SurveyCTO's standard time format will be
shifted.

Options

force is required as a reminder that data in time and datetime variables
will be overwritten.

only(varlist) specifies that the time zone should only be shifted for
datetime and time variables included in the varlist.

exclude(varlist) specifies that the time zone should be shifted for
all datetime and time variables except for those included in the varlist.

If only is specified, exclude cannot be specified. If neither are specified,
all time and datetime variables will be shifted.

Examples

Example 1

sctorezone -3, only(starttime) force

In this example, sctorezone manually shifts (only) the variable starttime backward three hours.

Example 2

sctorezone +5.5, exclude(timefield) force

In this example, sctorezone manually shifts (only) all datetime and time variables forward five and a half hours,
excluding the variable named "timefield".

Example 3

sctorezone starttime_calculate, force

In this example, sctorezone automatically shift times of all datetime and time
variables according to the string variable starttime_calculate, which is a SurveyCTO
calculate field with the following calculation expression:
format-date-time($, '%Y-%b-%e %H:%M:%S').

Author

This command was developed by William Blackmon (wblackmon@poverty-action.org), Research Manager at IPA. You
can see this command's repository on Github.