Functions to access respondents' answers
answer
Signature: answer(question_id, [item_id], [stimulus_id])
Example: answer(1559253)
Returns the responses in the question specified by question_id.
If several options in a multiple choice or dropdown question are selected, the function will return a concatenated string separated by commas.
If a write-in item was selected, the respondent’s input is returned.
item_id is an optional input to retrieve answers to an item in the question. Using item_id with a ranking question returns the rank of the item. If the item was not ranked, undefined is returned.
If the question was not shown to the respondent or not answered by the respondent, the function will return undefined.
answered
This function checks if the respondent answered a particular question. It returns TRUE or FALSE. If the question was not shown to the respondent, then the function returns FALSE.
Usage: answered(question_id, [stimulus_id]), where
question_idis the ID of the question;stimulus_idis the ID of the stimulus in the monadic block. If a question was inside a monadic block, but the stimulus ID is not specified, then the function returnsTRUEif it was answered for any stimulus in the block.
The function is applicable to all types of questions. There are some special cases:
- For intro questions, the function returns
TRUEif the question was shown, andFALSEif it was not shown. - Some questions where answer is forced (such as Van Westendorp) will generally be answered as long as they were shown.
shown
This function checks if the respondent saw a particular question. It returns TRUE or FALSE.
Usage: shown(question_id, [item_id], [stimulus_id]), where
question_idis the ID of the question;item_idis the ID of the item in the question (only applicable for questions with items, such as multiple choice or ranking questions). If an item ID is not specified, the function returnsTRUEif the respondent saw the question, andFALSEif they did not see the question.stimulus_idis the ID of the stimulus in the monadic block. If a question was inside a monadic block, but the stimulus ID is not specified, then the function returnsTRUEif it was shown for any stimulus in the block.
Examples:
shown(1559253)returnsTRUEif the respondent saw any item in the question with ID1559253, andFALSEif they did not see any item in the question.shown(1559253, 12345)returnsTRUEif the respondent saw the item with ID12345in the question with ID1559253, andFALSEif they did not see this item.shown(1559253, , 54321)returnsTRUEif the respondent saw the question with ID1559253for the stimulus with ID54321, andFALSEif they did not see in the question for this stimulus.shown(1559253, 12345, 54321)returnsTRUEif the respondent saw the item with ID12345in the question with ID1559253for the stimulus with ID54321, andFALSEif they did not see this item in the question for this stimulus.
The function is applicable to all types of questions, including survey flow controls.
bottom and top
Signature: bottom(question_id, limit, [stimulus_id]) and top(question_id, limit, [stimulus_id])
Example: bottom(1549283, 2)
Returns the N items the respondent placed at the bottom or top of the list in the ranking question specified by question_id. N is determined by limit.
If the question was not shown to the respondent, the function will return undefined.
count
Signature: count(question_id, [stimulus_id])
Example: count(1559253)
Returns the number of choices selected by respondents in the question specified by question_id. Function only works with multiple choice and dropdown menu questions.
If the question was not shown to the respondent, the function will return undefined.
vwAnswer
Signature: vwAnswer(question_id, [item], [stimulus_id])
Example: vwAnswer(12345, "too_high")
Returns the response to a specific item in a Van Westendorp question. The item parameter must be "too_low" (the too-cheap price), "cheap" (the good-value price), "expensive" (the expensive price), or "too_high" (the too-expensive price). Returns "no" if the qualifying question was answered as “no”.
The output will always be a string. The prices will be returned in the formatting specified in the question (e.g. "$ 3.00" rather than 3).
If the question was not shown to the respondent, the function will return undefined.
npsStatus
Signature: npsStatus(question_id, [stimulus_id])
Example: npsStatus(1557233)
Returns the net promoter status for Net Promoter Score questions. The returned value is a string that can be only “Detractor”, “Neutral”, or “Promoter”. Specify question using question_id.
If the question was not shown to the respondent, the function will return undefined.
answerType
Signature: answerType(question_id, [stimulus_id])
Example: answerType(1557232)
Returns the answer type of a calculated variable. The returned value is a string that can be only “number”, “string”, “boolean”, or “undefined”. Specify question using question_id.
If the question was not shown to the respondent, the function will return undefined.
sequentialNumber
Signature: sequentialNumber(question_id, [item_id])
Example: sequentialNumber(198653, 12345)
Returns the participant’s sequential number assigned during survey completion for the quota check question specified by question_id.
Not yet implemented: This function can reference a quota check located later in the survey or one that was not shown.
Not yet implemented: gridAnswer
Signature: gridAnswer(question_id, row_item_id, column_item_id)
Example: gridAnswer(1559253, 12345, 54321)
Returns the response to a specific cell in a matrix grid question. The cell is determined by the row item specified by row_item_id and the column item specified by column_item_id.
The output will depend on the type of the matrix:
- For Likert scale, semantic differential, multiple choice, and categorisation matrix grid types: the function returns Boolean values (
TRUEorFALSE) indicating whether the respondent selected the cell. - For ranking, it will return a number indicating the rank assigned to the cell. If the cell was not ranked,
undefinedis returned. - For constant sum or number input matrix grid types, it will return the respondent’s input in the cell (a number). If the cell was not filled in,
undefinedis returned. - For short input matrix grid type, it will return the respondent’s input in the cell (a string). If the cell was not filled in,
undefinedis returned.
If the question was not shown to the respondent, the function will return undefined.
The use of stimulus_id
stimulus_id is an optional input in the functions listed above. It helps retrieve answers to a particular stimulus in a monadic block.
If you refer to a question that is inside the monadic block but omit the stimulus_id input, the functions will return results for the “first” stimulus of the block. It could be either the first stimulus shown to the respondent or the first stimulus in the order specified in the experiment’s settings.
If you specify stimulus_id for a question that is outside of a monadic block, the functions will return undefined.
If you specify an incorrect value for stimulus_id for a question that is inside of a monadic block, the functions will return undefined.
Special behaviours by question type
| Question type | answer | answered | shown |
|---|---|---|---|
| Image heatmap | Always returns undefined | Standard behaviour | Standard behaviour |
| Text highlighter | Always returns undefined | Standard behaviour | Standard behaviour |
| Matrix grid | Always returns undefined. Use gridAnswer instead | Standard behaviour | Standard behaviour |
Gender and age
For the gender and age question type, the following rules apply:
| Arguments | answer | answered or shown (same behaviour for both) |
|---|---|---|
answer(123) | Returns a string Gender, age (e.g. "Male, 25") | Returns TRUE if the respondent answered this question or if values were taken a previous survey or their panel provider; FALSE otherwise |
answer(123, {Age item}) | Returns a string with the respondent’s age (e.g. "25") | Always returns undefined |
answer(123, {Male item}) | Returns the string "Male" if the respondent is male, and an empty string otherwise | Always returns undefined |
answer(123, {Female item}) | Returns the string "Female" if the respondent is female, and an empty string otherwise | Always returns undefined |
answer(123, {Other item}) | Returns the string "Other" if the respondent is of another gender, and an empty string otherwise | Always returns undefined |
If you want to get just the gender, you should use the formula concat(answer(123, {Male item}), answer(123, {Female item}), answer(123, {Other item})).