trial_image_keyboard_response function is used to display
an image stimulus and collect a response using a key press.
trial_image_keyboard_response( stimulus, stimulus_height = NULL, stimulus_width = NULL, maintain_aspect_ratio = TRUE, choices = respond_any_key(), prompt = NULL, stimulus_duration = NULL, trial_duration = NULL, response_ends_trial = TRUE, post_trial_gap = 0, on_finish = NULL, on_load = NULL, data = NULL )
The path of the image file to be displayed.
Set the height of the image in pixels. If NULL, then the image will display at its natural height.
Set the width of the image in pixels. If NULL, then the image will display at its natural width.
If setting only the width or only the height and this parameter is TRUE, then the other dimension will be scaled to maintain the image's aspect ratio.
A character vector of keycodes (either numeric values or the characters themselves). Alternatively, respond_any_key() and respond_no_key() can be used
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).
How long to show the stimulus, in milliseconds. If NULL, then the stimulus will be shown until the subject makes a response
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.
If TRUE, then the trial will end when a response is made (or the trial_duration expires). If FALSE, the trial continues until the deadline expires.
The gap in milliseconds between the current trial and the next trial. If NULL, there will be no gap.
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 (
FALSE) are transformed to character vectors
and are specified to be objects of class "json", ensuring that they will be
trial_image_keyboard_response function belongs to the "stimulus-response"
family of trials, all of which display a stimulus of a particular type (image,
audio, video or HTML) and collect responses using a particular mechanism
(button, keyboard or slider).
This one displays an image and records responses generated with a key press.
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
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
insert_resource() function can be used to construct
resource paths automatically. In the example above,
stimulus = insert_resource("picture.png") would suffice.
Other aspects to the stimulus display can be controlled with other arguments.
stimulus_width arguments can be used to
manually control the image display size by specifying the height/width in
pixels. If only one of these two arguments is specified, but the
maintain_aspect_ratio value is set to
TRUE, the other dimension
of the image will automatically be scaled appropriately.
The length of time that the image remains on screen can also be customised
by setting the
stimulus_duration argument: this should be a numeric
value indicating the number of milliseconds before the image disappears.
Alternatively, a value of
NULL (the default) ensures that the image
remains visible until the trial ends.
For this kind of trial, participants can make a response by pressing a key,
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
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
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.
Depending on parameter settings, the trial can end when the subject responds
response_ends_trial = TRUE), or after a fixed amount of time
(specified using the
trial_duration argument) has elapsed. The length
of time that the stimulus remains visible can also be customized using the
Like all functions in the
trial_ family it contains four additional
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.
on_finish arguments can be used to
fn_ family of functions supplies a variety of functions that may
be useful in many cases.
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
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:
rt value is the response time in milliseconds taken for the
user to make a response. The time is measured from when the stimulus first
appears on the screen until the response.
corresponding to the response.
stimulus variable records the path to the image that was
displayed on this trial.
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.
Within the "stimulus-response" family of trials, there are four types of
stimuli (image, audio, video and HTML) and three types of response options
(button, keyboard, slider). The corresponding functions are