trial_audio_slider_response: Specify an audio trial with slider bar response
In djnavarro/jaysire: Build jsPsych Experiments in R

Description Usage Arguments Details Value See Also

View source: R/trial_audio_slider_response.R

The trial_audio_slider_response function is used to play an audio stimulus and collect a response using a slider bar.

trial_audio_slider_response(
  stimulus,
  labels = c("0%", "25%", "50%", "75%", "100%"),
  button_label = "Continue",
  min = 0,
  max = 100,
  start = 50,
  step = 1,
  slider_width = NULL,
  require_movement = FALSE,
  prompt = NULL,
  trial_ends_after_audio = FALSE,
  trial_duration = NULL,
  response_ends_trial = TRUE,
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

`stimulus`	Path to the audio file to be played
`labels`	Labels displayed at equidistant locations on the slider.
`button_label`	Label placed on the "continue" button
`min`	Minimum value of the slider
`max`	Maximum value of the slider
`start`	Initial value of the slider
`step`	Step size of the slider
`slider_width`	Horizontal width of the slider (defaults to display width)
`require_movement`	Does the user need to move the slider before clicking the continue button?
`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).
`trial_ends_after_audio`	If TRUE the trial will end as soon as the audio file finishes playing.
`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_audio_button_response 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). It plays audio files and records responses generated with a slider bar.

Stimulus display

If the browser supports it, audio files are played using the WebAudio API. This allows for reasonably precise timing of the playback. The timing of responses generated is measured against the WebAudio specific clock, improving the measurement of response times. If the browser does not support the WebAudio API, then the audio file is played with HTML5 audio.

Response mechanism

Participant responses for this trial type are collected using a slider bar that the participant can move using the mouse. Once the participant is happy with this positioning they can click a button at the bottom of the page to move on to the next trial. This response method can be customised in several ways depending on the following arguments:

The min and max arguments are numeric values that specify the minimum value (leftmost point on the slider) and the maximum value (rightmost point on the slider) that a participant can respond with.
The start parameter is a numeric value that indicates where the value of the the slider is initially position. By default this is set to the middle of the scale, but there are many cases where it may be sensible to have the slider bar start at one end of the scale.
The movement of the slider is discretised, and the granularity of this movement can be customised using the step parameter. This should be a numeric value that specifies the smallest possible increment that the participant can move the slider in either direction.
The text labels displayed below the slider bar can also be customised by specifying the labels parameter. This argument should be a character vector that contains the labels to be displaed. Labels will be displayed at equally spaced intervals along the slider, though it is possible to include blank labels to create the impression of unequal spacing if that is required.
The slider_width controls the horizontal width of the slider bar: the default value of NULL creates a slider that occupies 100% of the width of the jsPsych display. Note that this may not be 100% of the screen width.
To ensure that participants do engage with the slider, it is possible to set require_movement = TRUE which forces the participant to move the slider at least once in order to be permitted to move onto the next trial.
The button_label argument specifies the text displayed on the button that participants click to move to the next trial.

Other behaviour

As is the case for most trial_ functions there is a prompt argument, a string that specifies additional text that is displayed on screen during the trial. The value of prompt can contain HTML markup, allowing it to be used quite flexibly if needed.

The trial can end when the subject responds (response_ends_trial = TRUE), when the audio file has finished playing (trial_ends_after_audio = TRUE), or if the subject has failed to respond within a fixed length of time (specified using the trial_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 response is the numeric value of the slider bar.

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.