Additional Details on Certain Functions

Top  Previous  Next

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) %]

 

 


FormatNumber

 

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.

 


Strict Importance

 

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 his/her 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

 

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.

 


RadioSelect

 

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="clickable">

<td class="input_cell">

[%RadioSelect(freeformat_radio, 1)%]

</td>

<td>

ResponseOption_1

</td>

</tr>

<tr class="clickable">

<td class="input_cell">

[%RadioSelect(freeformat_radio, 2)%]

</td>

<td>

ResponseOption_2

</td>

</tr>

<tr class="clickable">

<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 "clickable" 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.

 

 


CheckSelect

 

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="clickable">

<td class="input_cell">

[%CheckSelect(freeformat_check, 1)%]

</td>

<td>

ResponseOption_1

</td>

</tr>

<tr class="clickable">

<td class="input_cell">

[%CheckSelect(freeformat_check, 2)%]

</td>

<td>

ResponseOption_2

</td>

</tr>

<tr class="clickable">

<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 "clickable" 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.

 


DisplayTotal

 

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 when including an image.

 

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 Pass-In Fields (located in the Start question) to set up variables that can be used by SetValue().  For example you could create a Pass-In field 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.

 


LoopList Functions

(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).

 

Page link: http://www.sawtoothsoftware.com/help/lighthouse-studio/manual/index.html?hid_web_additionaldetails.html