trial_html_button_response: Specify an HTML trial with button response
In djnavarro/jaysire: Build jsPsych Experiments in R

Description Usage Arguments Details Value See Also

View source: R/trial_html_button_response.R

The trial_html_button_response function is used to display an HTML stimulus and collect a response using on screen buttons.

trial_html_button_response(
  stimulus,
  choices = c("button 0", "button 1", "button 2"),
  button_html = NULL,
  margin_vertical = "0px",
  margin_horizontal = "8px",
  prompt = NULL,
  stimulus_duration = NULL,
  trial_duration = NULL,
  response_ends_trial = TRUE,
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

`stimulus`	The HTML content to be displayed.
`choices`	Labels for the buttons. Each element of the character vector will generate a different button.
`button_html`	A template of HTML for generating the button elements (see details)
`margin_vertical`	Vertical margin of the buttons
`margin_horizontal`	Horizontal margin of the buttons
`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).
`stimulus_duration`	How long to show the stimulus, in milliseconds. If NULL, then the stimulus will be shown until the subject makes a response
`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.
`response_ends_trial`	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.
`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

The trial_html_button_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 HTML and records responses generated with a button click.

Stimulus display

The stimulus argument is a string specifying the text to be displayed as the stimulus. It can include HTML markup, meaning that it can be used to any stimulus that can be specified using HTML. It remains on screen for a length of time corresponding to the stimulus_duration parameter in milliseconds (or indefinitely if the parameter is NULL).

Response mechanism

The response buttons can be customized using HTML formatting, via the button_html argument. This argument allows the user to specify an HTML used to generating the button elements. If this argument is a vector of the same length as choices then the i-th element of button_html will be used to define the i-th response button. If button_html is a single string then the same template will be applied to every button. The templating is defined using a special string "%choice%" that will be replaced by the corresponding element of the choices vector. By default the jsPsych library creates an HTML button of class "jspsych-btn" and the styling is governed by the corresponding CSS.

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

Other behaviour

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 (stimulus_duration) argument.

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 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.
The button_pressed variable is a numeric value indicating which button was pressed. The first button in the choices array is recorded as value 0, the second is value 1, and so on.
The stimulus variable records the HTML content 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.

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.

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 trial_image_button_response, trial_image_keyboard_response, trial_image_slider_response, trial_audio_button_response, trial_audio_keyboard_response, trial_audio_slider_response, trial_video_button_response, trial_video_keyboard_response, trial_video_slider_response, trial_html_button_response, trial_html_keyboard_response and trial_html_slider_response.