Timer variables (r9)

The create timers tag (also known as timers) creates a variable that tracks the amount of time elapsed within specific sections of a survey. create timers is applicable to start group or define chapters widgets and can extend to all named and nested groups in a survey if it is used with the set defaults widget. create timers accepts 'y'/'n' input.

The named timer tag serves a similar purpose, but permits users to assign custom names like "SCREENING" to timers within groups. Unlike create timers, the named timer tag is only applicable to start group widgets. 

Syntax

create timers accepts 'y' input for "yes" and 'n' for "no." Conversely, the named timers tag cannot accept 'y'/'n' input. Instead, provide a custom name using alphanumerics or underscores; spaces are not permitted. 

See the syntax examples below. Note, timers is an alias for create timers, and anywhere the tag is written, timers could be used in its place.

# With 'set defaults' widget
set defaults
create timers: y

# With 'define chapters' widget
define chapters
create timers: y
S. Section S
A. Section A
D. Section D, etc.

# With 'start group' widget
start group: GROUP_NAME
create timers: y

# Creating and naming a timer with 'start group' widget
start group: GROUP_NAME
named timer: GROUP_NAME_time 

# Overriding a timer established with 'set defaults'
start group: GROUP_NAME
create timers: n

Time calculations

Rules regarding when a timer will pause are similar to the system variable elapsed. If the respondent switches to a different tab, the timer pauses. There's also a general timeout to pause timing when a respondent's computer is inactive for 5+ minutes.

Users should note that the placement of the create timers tag impacts in how elapsed time is recorded.

• Adding create timers: y on a chapter links a timer to every page that has a data field (question, table, etc.) in that chapter. Pages without any fields, such as those with only text, will not be timed.
• Adding create timers: y on a group links a timer to every page in the group, regardless of whether it contains a question or table, including pages with only text.

The named timer tag, which is only placed on a group, also links a timer to every page in the group.

Examples

Here are a few examples to expand on the syntax shown above. Reminder, anywhere the create timers tag is written, timers could be used in its place.

Establishing timers with defaults

To establish timers for all chapters and groups in a survey, add the create timers tag to the set defaults widget.

set defaults
create timers: y

Establishing timers on chapter definition

Timers can be created for all named chapters and subchapters by placing create timers: y on the define chapters widget.

define chapters
timers: y
S. Screener Questions 
D. Demographic Questions
A. Main Survey Questions

Applying timers directly to a group

The start group widget can accept either the create timers tag or the named timer tag. While the named timer tag allows for custom names that can be unrelated to the group name, it's recommended to align the timer name with the group name for clarity in data and reports.

start group: SCREENER
named timer: SCREENER_time

1. Want to take a survey?
type: radio
1. Yes
2. No {term:y}

end group: SCREENER

Data

When create timers or named timer tags have been applied to a survey, timer variables will be created in the reporting field tree, under System fields > Section Times. Timers created with create timers: y will be assigned the name "CHAPTERID_timer," where "CHAPTERID" would be replaced with the chapter or group name as defined in the survey code. For example, chapters B and C below create timers named 'B_timer' and 'C_timer', respectively. Meanwhile, timers created with named timer will display the name exactly as it is programmed. For example, named timer: DeepDive would create a timer named 'DeepDive' in the reports. 

Timers created with the create timers tag are presented first in the reporting field tree, and group timers created with named timer are placed afterwards. Using the code example below, notice the 'DeepDive' named timer is placed on Q20, before chapter C. However, this data field is stored after the chapter timers, as shown in the image below.

define chapters
create timers: y
B. Brands
C. Demos

10. a question
chapter: B
type: radio
1. yes

startgroup: Q20TOQ30
named timer: DeepDive

20. a question
type: radio
1. yes

endgroup: Q20TOQ30

30. a question
chapter: C
type: radio
1. yes

Also, if create timers is present on define chapters and the named timer tag is also used for a group that has a chapter tag, both timers will track time and be in the reporting tree.