Additional Details on Certain Functions
POPUP
Returns the HTML for a JavaScript pop-up. The HTML file that contains the text to be shown in the popup (File.htm) is assumed to be in the graphics folder. Or, the HTML file can be elsewhere if referenced with the full http:// path.
The format is:
PopUp("Link Text", "File.htm", Width, Height)
Example 1:
Assume that you have saved an HTML file containing the help in the study graphics folder. The text below is placed within the question text, such as within Header 1 or Header 2.
[% PopUp("Click Here for Survey Help", "SurveyHelp.htm", 500, 500) %]
When the survey is run, the above function displays a link that the respondent may click to launch a popup window containing the information in SurveyHelp.htm.
The respondent can retire the popup window and return to the survey by clicking the "X" in the upper-right corner of the popup window.
Example 2:
In this example, we reference an HTML page not in the graphics folder, but somewhere else on your web site. To do this, we include the full URL path to the HTML file.
[% PopUp("Click Here for Survey Help", "http://www.mysurvey.com/mystudy/help/SurveyHelp.htm", 500, 500) %]
Example 3:
In this example, we replace the "Click Here for Survey Help" text with a graphic.
[% PopUp("<img src=' " & GraphicsPath() & "help.jpg' alt=' ' border='0'>", "Help.htm", 500, 500) %]
This function formats numbers with thousands separators, decimal separators, and decimal places. The format is:
FormatNumber (Number, ThousandsSeparator, DecimalSeparator, #DecimalPlaces)
The ThousandsSeparator and DecimalSeparator are enclosed in double-quotes. For example, to make the ThousandsSeparator a comma, you should specify "," as the argument.
Example 1: In the US, the value 7123456 would be formatted as 7,123,456.00. The following script formats this value to US standards:
FormatNumber(7123456, ",", ".", 2)
Example 2: In Germany, the value 7123456 would be formatted as 7.123.456,00. The following script formats this value to German standards:
FormatNumber(7123456, ".", ",", 2)
Example 3: In most cases, you'll be formatting a value contained in a variable (such as a question asked earlier in the survey):
FormatNumber(Q28, ",", ".", 0)
Technical notes: DecimalPlaces can be replaced by a variable that returns a value. Thousands separators and decimal separators can be replaced by a variable that returns text.
If you use ACA's "Strict" importance function, we do not assume that importance is defined simply by computing the range from the most and least preferred levels within an attribute. We refer to the spread in utility between this respondent's prior best and worst levels (as specified in the attribute a priori order, or by the respondent in the ACARAT questions). If the best minus worst utility is negative, we set the range equal to zero. Strict importance keeps virtually unimportant attributes that potentially have reversals (out-of-order utilities) from getting inflated importance weights. It reduces the effect of random error on importance calculations.
Consider the following part-worth utilities:
$10 1.45
$15 1.50
$20 0.75
$25 0.50
Under standard importance calculations, we take the full spread in utilities for this attribute (1.50 - 0.50 = 1). With Strict importance, we take the spread in importance between the prior best and worst levels (1.45 - 0.50 = 0.95).
As another example, consider the following part-worth utilities:
Has widget "A" 0.20
No widget "A" 0.30
If having widget "A" is expected to be preferred to not having widget "A," based on prior rank-order (or from the respondent's ACARAT question), these utilities suggest a "reversal." The standard importance calculation takes the full range of 0.10 into the computation. Strict importance recognizes this as a reversal and sets the importance equal to 0 for this attribute. We assume that the reversal is due to this attribute having virtually no importance, with random error overcoming any correct signal from the respondent regarding their true preference for levels within this attribute.
Note: this function only applies within the ACA questionnaire. The utilities report in the market simulator uses the standard definition of attribute importance.
PageTime(StartPage, EndPage) returns a value (in seconds) between StartPage and EndPage. EndPage is optional. If no EndPage is supplied, PageTime returns the total time spent on StartPage.
You can specify integers as arguments (the page number for the current question is shown at the bottom of the Write Questionnaire dialog when you highlight any question on the list). For example, you may also use: [%PageTime(PageNumber()-3, PageNumber())%] to return the time spent on the previous three pages, without worrying about hardcoding integer values. You might apply that script within a skip pattern to display a warning message if a respondent answered the previous pages too quickly.
If you check the Save Respondent Time per Page setting in the Survey Settings | Advanced tab dialog, the time for each page (in seconds) is stored in the database with variable naming convention sys_pagetime_#, where # is the page number. When you export the data, you can export these variables and they appear in the export list below any constructed list items.
If the respondent backs up and re-answers a page (using Lighthouse Studio's Previous button), new time spent answering that page will be added to the previous time recorded. If respondents use the Back button on the browser to re-answer a page, the total time spent on the re-answered page may not be accounted for correctly.
This function returns HTML for a radio button, for use within Free Format questions. When Graphical Select buttons are enabled under the Survey Settings, General Settings tab, the HTML required for displaying graphical radio buttons is relatively complex. The RadioSelect function returns the HTML necessary for displaying regular or graphical select questions.
The syntax for this instruction is:
RadioSelect(QuestionName, Value)
Where QuestionName is the full QuestionName + Variable extension for a Free Format variable; and Value is the numeric (or text) value that is stored when the respondent clicks this particular radio button. Example:
<table>
<tr class="click-able">
<td class="input_cell">
[%RadioSelect(freeformat_radio, 1)%]
</td>
<td>
ResponseOption_1
</td>
</tr>
<tr class="click-able">
<td class="input_cell">
[%RadioSelect(freeformat_radio, 2)%]
</td>
<td>
ResponseOption_2
</td>
</tr>
<tr class="click-able">
<td class="input_cell">
[%RadioSelect(freeformat_radio, 3)%]
</td>
<td>
ResponseOption_3
</td>
</tr>
</table>
In the example above, the Free Format variable is named freeformat_radio. The RadioSelect instruction (highlighted in blue above) is called for each of the three response options (radio buttons) and the appropriate value is saved into the database for each option. The HTML needed for showing Graphical Radio buttons is supplied when the survey runs on the server.
Notice that we've declared classes "click-able" and "input_cell" within the <tr> and <td> tags. This makes the graphical select feature and the highlight text feature (when respondents mouse-over the response item text) work.
This function returns HTML for a checkbox, for use within Free Format questions. When Graphical Select buttons are enabled under the Survey Settings, General Settings tab, the HTML required for displaying graphical radio buttons and checkboxes is relatively complex. The CheckSelect function makes the Free Format question appear and function like the other Select-type questions in your questionnaire.
The syntax for this instruction is:
CheckSelect(QuestionName, Value)
Where QuestionName is the full QuestionName + Variable extension for a Free Format variable; and Value is the numeric value associated with each item in the checkbox question. Example:
<table>
<tr class="click-able">
<td class="input_cell">
[%CheckSelect(freeformat_check, 1)%]
</td>
<td>
ResponseOption_1
</td>
</tr>
<tr class="click-able">
<td class="input_cell">
[%CheckSelect(freeformat_check, 2)%]
</td>
<td>
ResponseOption_2
</td>
</tr>
<tr class="click-able">
<td class="input_cell">
[%CheckSelect(freeformat_check, 3)%]
</td>
<td>
ResponseOption_3
</td>
</tr>
</table>
In the example above, the Free Format variable is named freeformat_check. The CheckSelect instruction (highlighted in blue above) is called for each of the three response options (check boxes). The CheckSelect instruction will return HTML that declares the variables freeformat_check_1, freeformat_check_2, and freeformat_check_3, and sets all variables equal to 1 if selected, and 0 otherwise. The HTML needed for showing Graphical Checkboxes is supplied (if needed) when the survey runs on the server.
Notice that we've declared classes "click-able" and "input_cell" within the <tr> and <td> tags. This makes the graphical select feature and the highlight text feature (when respondents mouse-over the response item text) work.
Returns a grayed out box displaying the total of all questions beginning with FirstQuestionName and ending with LastQuestionName.
The syntax for this instruction is:
DisplayTotal (FirstQuestionName , LastQuestionName, Width)
The FirstQuestionName and LastQuestionName question names need to have the same base question names with a starting number at the end of FirstQuestionName and a last question number at the end of LastQuestionName. DisplayTotal will sum the values for all question names in between.
For example:
[%DisplayTotal (Num1, Num5, 5) %]
will display the total of Num1 + Num2 + Num3 + Num4 + Num5. Notice that all question names must contain the same base name, in this case "Num".
DisplayTotal is useful when using Free Format questions to implement custom constant sum CBC questions. May also be used for non-CBC questions.
ToolTip ("LinkText", "HelpText", Width, Height)
Creates a tool tip for "LinkText". When the respondent moves their mouse over the top of this text a box will be displayed with "HelpText" in it.
ToolTip(LinkText, HelpText)
ToolTip(LinkText, HelpText, Width, Height)
Example:
[%ToolTip("Product A", "This product has some great features!", 100, 50)%]
Another way to create a tool tip without using a Sawtooth Script function is to add the "tool_tip_link" class to your HTML. Then enter the tool tip text as the value for the "title" attribute. For example:
<span class="tool_tip_link" title="This product has some great features!">Product A</span>
If you want to use your own custom HTML (to include images etc.) to create a tool tip simply place HTML similar to the example below in your survey. Make sure you include the "tool_tip_link" and "tool_tip_text" classes. The HTML containing the "tool_tip_text" class must immediately follow the "tool_tip_link" HTML.
<span class="tool_tip_link">Car XYZ</span>
<div class="tool_tip_text" style="max-width: none;">
<img src="[%GraphicsPath()%]car_pic.jpg" alt="" border="0">
<br>This is an "awesome" car!
</div>
In the example above there is an optional "max-width: none;". This is best used if you want the width of the tool tip to be determined by the content inside of the tool tip.
Warning: Do not place your Tooltip code within a <p> </p> tag! The tooltip help text will not display.
SetValue (QuestionName, Value)
SetValue() allows you to save values to existing variables in the database (it does not create new variables on the fly within the database). For example:
[%SetValue(Q1, 5) %]
sets the value for Q1 to 5 in the database.
Currently we do not have a place in the Lighthouse Studio interface where you can specify variable names. You could use an existing question in the question list (such as a Free Format hidden variable). But, we suggest you use Link Variables (located in the Questionnaire Access window) to set up variables that can be used by SetValue(). For example you could create a link variable named "age". You could then set the value for "age" to 45 midway through the survey using the following command:
[%SetValue(age, 45) %]
To retrieve the value for age at a point later in the questionnaire you can use:
[%GetValue(age) %]
which returns the current value for age stored in the database.
(AIELoopList, ANELoopList, AIGLoopList, AILLoopList)
Loops ask a question or series of questions for each element of a given list (either predefined or constructed). LoopList functions operate on this list.
Example:
Consider a numeric question (TIMESBOUGHT) involved in a loop named BRANDLOOP, where we ask how many times each brand has been purchased in the last month.. The loop is based on list BRANDLIST, containing the full list of brands in the study.
Here is the question text for the TIMESBOUGHT question (for example, in Header 1):
How many times have you purchased [%LoopLabel()%] in the last month?
For each brand, the brand name appears in place of [%LoopLabel()%]. The question is asked multiple times, for each member in BRANDLIST.
Suppose we want to add any brand to a new list that has been bought at least twice (those with TIMESBOUGHT>1). Within the List Manager, we can create a new constructed list, adding elements to that list based on the TIMESBOUGHT question that is within the loop. The parent list for this constructed list (BRANDSBOUGHTLIST) needs to be the same parent list that is specified for the Loop List. The following :
AIGLoopList(BRANDLIST, TIMESBOUGHT, 1)
Suppose a particular respondent sees the following brands and answers as follows for each:
Brands |
TimesBought |
Snickers |
3 |
Mounds |
0 |
Reese's |
2 |
M&M's |
1 |
The final constructed list (BRANDSBOUGHTLIST) for this respondent will contain elements "Snickers, Reese's" (because the respondent has indicated that each of those is purchased at least twice).
BanditMaxDiff (MaxDiffExerciseName, Items, NumThompsonItems)
This function uses Thompson Sampling to select items from the parent list of a MaxDiff exercise named MaxDiffExerciseName.
Items is the number of items from the parent list to be added to the constructed list to be shown to a single respondent in the bandit MaxDiff exercise. In most cases we recommend that Items match the total number of items included in the constructed list. For studies involving 30 items or more, it is typical to add (draw) 30 items. Depending on the number of total items in your bandit MaxDiff study, we recommend the following Items and approaches:
Total Items in Bandit MaxDiff Study |
#Items (to show each respondent) |
Recommended Strategy: |
30 or fewer |
Equal to total number of items in study |
Boosted Bandit MaxDiff strategy, where each person sees each item in the study at least 1x, but the more preferred items are oversampled |
31+ |
30 |
Either standard strategy (each of the 30 selected items is shown an equal number of times for a respondent), or Boosted Bandit MaxDiff strategy. |
The BanditMaxDiff function adds items to the constructed list in priority order according to their expected preference as drawn using Thompson Sampling. For example, consider a bandit MaxDiff study in which 30 items from a total of 100 items are to be selected for each respondent to evaluate. Using the prior means (from counting) and variances, we employ Thompson Sampling to draw 30 items from the 100 to show the respondent, where the first item has the highest expectation of preference, the 2nd item has the second highest expectation of preference, etc.
NumThompsonItems is the number of items drawn using Thompson Sampling and should be an integer from 1 to Items. By default (if this argument is missing), we select 5/6 of the Items using Thompson Sampling and the remaining 1/6 of the items are chosen among the items seen fewest times by previous respondents. For example, consider a bandit MaxDiff study involving 100 items, where for each respondent we want to show 30 of the 100 items (Items=30). If the last argument, NumThompsonItems, is left blank, then 5/6 or 25 of the 30 items will be drawn for each respondent using Thompson Sampling and the remaining 5 items will be drawn from among the 100 items seen fewest times by previous respondents. Stated another way, if Items=30, leaving NumThompsonItems blank is equivalent to specifying BanditMaxDiff (MaxDiffExercise, 30, 25).
NumThompsonItems |
Description |
Low |
1/2 of the items selected onto the constructed list are determined by Thompson Sampling; the remainder are selected among the items seen the fewest number of times by previous respondents |
Somewhat Low |
2/3 of the items selected onto the constructed list are determined by Thompson Sampling; the remainder are selected among the items seen the fewest number of times by previous respondents |
Moderate |
3/4 of the items selected onto the constructed list are determined by Thompson Sampling; the remainder are selected among the items seen the fewest number of times by previous respondents |
Moderately Aggressive (default) |
5/6 of the items selected onto the constructed list are determined by Thompson Sampling; the remainder are selected among the items seen the fewest number of times by previous respondents |
Aggressive |
9/10 of the items selected onto the constructed list are determined by Thompson Sampling; the remainder are selected among the items seen the fewest number of times by previous respondents |
Why pick a different level of adaptivity than the default? If you want a less aggressive approach that strikes a closer compromise between standard level-balanced MaxDiff (where each item is sampled equally) and bandit MaxDiff (which oversamples most preferred items), you should employ a low level of adaptivity.
If your only goal is to identify the top few items for the sample and your sampling scheme ensures that the first respondents should be not systematically different from the last respondents, you should employ the highest level of adaptivity.
Some functions in Sawtooth Script only work if used in certain locations. For example CBCCurrentTask() must be used inside of a CBC question. Unlike other Sawtooth Script functions these "Location Specific Functions" cannot be combined with other Sawtooth Script. For example [%CBCCurrentTask() + 1%] will not work.
