R/trial_survey_multi_select.R
trial_survey_multi_select.Rd
The trial_survey_multi_select
function is used to display a
survey page with one or more multiple selection questions
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 )
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 |
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
.
The trial_survey_multi_select
function creates a trial that displays
a set of questions with multiple selection responses.
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.
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
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.
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
.