-
Notifications
You must be signed in to change notification settings - Fork 1
Merlin Native Functions
This is a reference of the builtin functions that can be used in Merlin scripts. For general info on scripting in ESMira, see the Scripting page. For a reference of the Merlin language, see the Merlin Language Reference.
getQuestionnaireVar(variableName)
Takes in a variableName string or array of strings. This function will then look through the current questionnaire for items of that name and return their current state as a string. If an array is passed for variableName this function will return an array of strings with the current values for all passed variable/item names.
The function will return a none value for failing lookups. I.e., it will return none if a single item lookup fails, or have none values for any failing item lookups in an array. If the value is unset (i.e., the participant has not yet answered the item), the value will also be returned as none.
Note that this function can only report the value at the time of the script's execution. This means that in a context like a relevance-script items on the same page (or subsequent pages) as the item the script is attached to will not yet be set when the script runs. Only use this function for accessing items from previous pages that have already been filled out.
getQuestionnaireVarAlternative(variableName, alternativeKey)
Takes in a variableName string and a alternativeKey string or array of strings. Similar to getQuestionnaireVar this function will look through the current questionnaire for items with the name passed into variableName, and try to access one or more alternative values with the provided keys. Alternative values are additional values that are provided by some items, e.g., the state of the individual answer options for a multiple choice items. Alternative items and their keys are marked by a ~ in the varible names of the dataset (with the part before the ~ signifying the variableName and the part after the altentativeKey).
This function will return a none for failing lookups, i.e., for variableNames or alternativeKeys not present in the questionnaire or item respectively.
Note that this function can only report the value at the time of the script's execution. This means that in a context like a relevance-script items on the same page (or subsequent pages) as the item the script is attached to will not yet be set when the script runs. Only use this function for accessing items from previous pages that have already been filled out.
setVirtualItem(itemName, value)
This function sets the value of a virtual item. Virtual items can be created in the "Create sumscores" panel and are intended to be set programmatically via this function, e.g., to calculate the mean of several other items.
day()
Returns the current day of the study since joining it. On the day the study is joined this function will return 0, on the next (i.e., the first full day) it will return 1, and so on. If the calculation fails this function will return none.
triggerQuestionnaire(questionnaireId, message, timeout)
This function will trigger an invitation to the questionnaire with the specified internal questionnaireId (requires the value of the internalId field in the study source code). The notification will be displayed immediately, and will show the message specified in message. If a positive numeric value is passed for timeout the invitation will time out after that amount of minutes, otherwise it will stay active indefinitely.
This function returns 1 if the operation succeeds, and 0 if it encounters an error.
Note
Currently it is not possible to trigger a delayed questionnaire, e.g., a follow-up questionnaire scheduled 15 minutes after filling out a primary questionnaire. Such functionality is planned for future iterations of ESMira/Merlin. For now, use the trigger panel within the study edit options.
triggerNotification(message)
This function will trigger a notification with the text passed in message. It will return 1 if it succeeds, and 0 if it encounters an error. Notifications will be sent immediately.
triggerMessage(message)
This function will trigger a new message within the anonymous message system, containing the text passed into message. The triggered message will appear to come from the researcher. Messages will be sent immediately.
This function will return 1 if it succeeds, and 0 if it encounters an error.
Note
If you need to notify yourself (instead of creating a message for the participant), use the log() function.
log(message)
This function will send a log to the server, containing the specified message. This can be used to inform yourself of noteworthy events. E.g., if a participant has filled out a final questionnaire, or if a participant showed a response pattern that is immediately relevant for you.
reverse(variables, min, max)
This function tries to revert the values of the variable or variables passed in as variables, with the specified min and max values. This can be used to invert reverse-coded items, e.g., on a Likert-scale.
If a single value is passed in the function returns that value reversed, if an array is passed in, the function returns an array with all values reversed. In case the function encounters non-numeric values it returns variables unchanged.
Note: Likert-scales and single choice items start at 1 in ESMira, Visual analogue scales start at 0.
sum(arr)
Takes in an array and returns the sum of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none.
mean(arr)
Takes in an array and returns the mean of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none.
max(arr)
Takes in an array and returns the maximum of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none.
min(arr)
Takes in an array and returns the minimum of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none.
var(arr)
Takes in an array and returns the variance of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none. Will also return none if the array contains less than 2 elements.
sd(arr)
Takes in an array and returns the standard deviation of its elements. If the value passed in is not an array, the function will return the value unchanged. If any values in the array are not numbers, the function will return none. Will also return none if the array contains less than 2 elements.
random(from, to)
Returns a random number between from and to (inclusive). If a non-integer value is given for either from or to, this function returns none.
any(arr)
Checks if any array elements are truthy. Returns 1 if at least one element is truthy, returns 0 otherwise. If the argument is anything other than an array, this function will return the argument unchanged.
size(arr)
Returns the number of members of an array or object. If the passed value is a none value, this function returns 0. If the passed value is a string or a number, this function returns 1.
filterNone(arr)
Filters none values from an array. If an array is passed in, this function returns a copy of the array without none values. E.g., the input [1, none, 2, 3, none, 4] would return [1, 2, 3, 4]. If any other type is passed in, the function returns the argument unchanged.
lang()
Returns the currently used language code.
Note
It is not possible to localize scripts, i.e., provide different scripts for different language versions of a study. Thus, if you use text scripts in a localized study, you may want to use the lang() function to create the correctly localized string within your script.