trial_survey_multi_select: Specify a survey page with multiple selection items

In djnavarro/jaysire: Build jsPsych Experiments in R

Description

The trial_survey_multi_select function is used to display a survey page with one or more multiple selection questions

Usage

trial_survey_multi_select(
  questions,
  preamble = "",
  randomize_question_order = FALSE,
  button_label = "Continue",
  required_message = "You must choose at least one response for this question",
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

Arguments

questions	A question or list of questions
preamble	Text to appear above the questions
randomize_question_order	Should order be randomised?
button_label	Text for the continue button
required_message	Message to display if required response is not given.
post_trial_gap	The gap in milliseconds between the current trial and the next trial. If NULL, there will be no gap.
on_finish	A javascript callback function to execute when the trial finishes
on_load	A javascript callback function to execute when the trial begins, before any loading has occurred
data	An object containing additional data to store for the trial

Details

The trial_survey_multi_select function creates a trial that displays a set of questions with multiple selection responses.

Survey construction

There are five arguments that are relevant to the survey itself:

• The main argument is questions, which can and can either consist of a single question object generated by question_multi or a list of such objects. The multiple choice items are laid out as a set of check boxes with labels specified when calling question_multi, and the participant can select as many boxes as they like. See the documentation for the question function for details of what this entails.

• The preamble argument is used to specify introductory text that appears about the survey page. It accepts HTML markup and so can be used quite flexibly.

• The required_message parameter specifies the text of the message to be displayed if a participant attempts to move to the next trial without answering a required question.

• The randomize_question_order argument is a logical value that indicates whether or not the survey items should appear in a random order.

• The button_label specifies text to appear on the button displayed at the bottom of the page, and which the participant must click before moving on to the next trial.

Other behaviour

Like all functions in the trial_ family it contains four additional arguments:

• The post_trial_gap argument is a numeric value specifying the length of the pause between the current trial ending and the next one beginning. This parameter overrides any default values defined using the build_experiment function, and a blank screen is displayed during this gap period.

• The on_load and on_finish arguments can be used to specify javascript functions that will execute before the trial begins or after it ends. The javascript code can be written manually and inserted *as* javascript by using the insert_javascript function. However, the fn_ family of functions supplies a variety of functions that may be useful in many cases.

• The data argument can be used to insert custom data values into the jsPsych data storage for this trial

Data

When this function is called from R it returns the trial object that will later be inserted into the experiment when build_experiment is called. However, when the trial runs as part of the experiment it returns values that are recorded in the jsPsych data store and eventually form part of the data set for the experiment.

The data recorded by this trial is as follows:

• The responses value is a an array containing all selected choices in JSON format for each question. The encoded object will have a separate variable for the response to each question, with the first question in the trial being recorded in Q0, the second in Q1, and so on. The responses are recorded as the name of the option label. If the name parameter is defined for the question, then the response will use the value of name as the key for the response in the responses object.

• The rt value is the response time in milliseconds for the subject to make a response. The time is measured from when the questions first appear on the screen until the subject's response.

• The question_order value is a string in JSON format containing an array with the order of questions. For example [2,0,1] would indicate that the first question was trial.questions[2] (the third item in the questions parameter), the second question was trial.questions[0], and the final question was trial.questions[1].

In addition, it records default variables that are recorded by all trials:

• trial_type is a string that records the name of the plugin used to run the trial.

• trial_index is a number that records the index of the current trial across the whole experiment.

• time_elapsed counts the number of milliseconds since the start of the experiment when the trial ended.

• internal_node_id is a string identifier for the current "node" in the timeline.

Value

Functions with a trial_ prefix always return a "trial" object. A trial object is simply a list containing the input arguments, with NULL elements removed. Logical values in the input (TRUE and FALSE) are transformed to character vectors "true" and "false" and are specified to be objects of class "json", ensuring that they will be written to file as the javascript logicals, true and false.

See Also

Survey page trials are constructed using the trial_survey_text, trial_survey_likert, trial_survey_multi_choice and trial_survey_multi_select functions. Individual questions for survey trials can be specified using question_text, question_likert and question_multi.

djnavarro/jaysire documentation built on April 12, 2021, 4:25 a.m.