R/trial_categorize_image.R
trial_categorize_image.RdThe trial_categorize_image function is used to display
an image stimulus, collect a categorization response with the
keyboard, and provide feedback.
trial_categorize_image( stimulus, key_answer, choices = respond_any_key(), text_answer = "", correct_text = "Correct", incorrect_text = "Wrong", prompt = NULL, force_correct_button_press = FALSE, show_stim_with_feedback = TRUE, show_feedback_on_timeout = FALSE, timeout_message = "Please respond faster", stimulus_duration = NULL, feedback_duration = 2000, trial_duration = NULL, post_trial_gap = 0, on_finish = NULL, on_load = NULL, data = NULL )
| stimulus | The path to the image file to be displayed. |
|---|---|
| key_answer | The numeric key code indicating the correct response |
| choices | A character vector of keycodes (either numeric values or the characters themselves). Alternatively, respond_any_key() and respond_no_key() can be used |
| text_answer | A label associated with the correct answer |
| correct_text | Text to display when correct answer given ('%ANS%' substitutes text_answer) |
| incorrect_text | Text to display when wrong answer given ('%ANS%' substitutes text_answer) |
| prompt | A string (may contain HTML) that will be displayed below the stimulus, intended as a reminder about the actions to take (e.g., which key to press). |
| force_correct_button_press | If TRUE the correct button must be pressed after feedback in order to advance |
| show_stim_with_feedback | If TRUE the stimulus image will be displayed as part of the feedback. Otherwise only text is shown |
| show_feedback_on_timeout | If TRUE the "wrong answer" feedback will be presented on timeout. If FALSE, a timeout message is shown |
| timeout_message | The message to show on a timeout non-response |
| stimulus_duration | How long to show the stimulus, in milliseconds. If NULL, then the stimulus will be shown until the subject makes a response |
| feedback_duration | How long to show the feedback, in milliseconds |
| trial_duration | How long to wait for a response before ending trial in milliseconds. If NULL, the trial will wait indefinitely. If no response is made before the deadline is reached, the response will be recorded as NULL. |
| 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_categorize_image function is used to show an image object on the screen.
The subject responds by pressing a key. Feedback indicating the correctness
of the response is given.
For trials that display an image, the stimulus argument is a string that
specifies the path to the image file. More precisely, it must specify the path to
where the image file will be located at the time the experiment runs. Typically,
if an experiment is deployed using the build_experiment() function
all resource files will be stored in a "resource" folder, and the images will
be copied to the "image" subfolder. So if the image to be displayed is a file
called "picture.png", the stimulus path on a Mac or Linux machine would
likely be "resource/image/picture.png". Note that this path is specified relative
to the location of the primary experiment file "image.html". To make this a little
easier, the insert_resource() function can be used to construct
resource paths automatically. In the example above,
stimulus = insert_resource("picture.png") would suffice.
For this kind of trial, participants can make a response by pressing a key,
and the choices argument is used to control which keys will register
a valid response. The default value choices = respond_any_key()
is to allow the participant to press any key to register their response.
Alternatively it is possible to set choices = respond_no_key(),
which prevents all keys from registering a response: this can be useful if
the trial is designed to run for a fixed duration, regardless of what the
participant presses.
In many situations it is preferable to require the participant to respond
using specific keys (e.g., for a binary choice tasks, it may be desirable to
require participants to press F for one response or J for the other). This
can be achieved in two ways. One possibility is to use a character vector
as input (e.g., choices = c("f","j")). The other is to use the
numeric code that specifies the desired key in javascript, which in this
case would be choices = c(70, 74). To make it a little easier to
work with numeric codes, the jaysire package includes the
keycode() function to make it easier to convert from one format
to the other.
In a categorisation trial, there is always presumed to be a "correct" response for any given stimulus, and the participant is presented with feedback after the response is given. This feedback can be customised in several ways:
The key_answer argument specifies the numeric keycode
that corresponds to the correct response for the current trial.
The correct_text and incorrect_text arguments are used to
customise the feedback text that is presented to the participant after a
response is given. In both cases, there is a special value "%ANS%" that
can be used, and will be substituted with the value of text_answer.
For example if we set text_answer = "WUG", we could then set
correct_text = "Correct! This is a %ANS%" and
incorrect_text = "Wrong. This is a %ANS%". This functionality can be
particularly useful if the values of text_answer and stimulus
are specified using timeline variables (see insert_variable() and
set_variables()).
The force_correct_button_press argument is a logical variable.
If set to TRUE the participant cannot move forward to the next trial
until the correct response is given.
When show_stim_with_feedback = TRUE, the stimulus remains
on screen while the feedback is presented. If it is set to FALSE the
stimulus is not visible.
Sometimes a categorisation trial has a deadline, specified by the value
of trial_duration. If a response is not given by that time, the trial
ends. Optionally, a feedback screen can be presented whenever this occurs,
by setting show_feedback_on_timeout = FALSE, and the text of this
feedback is specified by using the timeout_message argument.
The prompt argument is used to specify text that remains on screen while
the animation displays. The intended use is to remind participants of the
valid response keys, but it allows HTML markup to be included and so can be
used for more general purposes.
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 stimulus value is the path to the image file.
The key_press
value indicates which key the subject pressed. The value is the numeric key
code corresponding to the subject's response.
The rt value is the
response time in milliseconds for the subject to make a response. The time is
measured from when the stimulus first appears on the screen until the subject's
response.
The correct value is true if the subject got the correct answer,
false otherwise.
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.
There are three types of categorization trial, corresponding to the
trial_categorize_animation,
trial_categorize_html and
trial_categorize_image functions.