trial_categorize_animation: Specify a categorization trial with an animated stimulus
In djnavarro/jaysire: Build jsPsych Experiments in R

Description Usage Arguments Details Value See Also

View source: R/trial_categorize_animation.R

The trial_categorize_animation function is used to display a sequence of images at a fixed rate, collect a categorization response with the keyboard, and provide feedback.

trial_categorize_animation(
  stimuli,
  key_answer,
  choices = respond_any_key(),
  text_answer = "",
  correct_text = "Correct",
  incorrect_text = "Wrong",
  frame_time = 500,
  sequence_reps = 1,
  allow_response_before_complete = FALSE,
  prompt = NULL,
  feedback_duration = 2000,
  post_trial_gap = 0,
  on_finish = NULL,
  on_load = NULL,
  data = NULL
)

`stimuli`	Character vector of paths to image files
`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)
`frame_time`	How long to display each image, in milliseconds
`sequence_reps`	How many times to show the entire sequence
`allow_response_before_complete`	If TRUE the user can respond before the animation sequence finishes
`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).
`feedback_duration`	How long to show the feedback, in milliseconds
`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_categorize_animation function is used to show a sequence of images at a specified frame rate. The subject responds by pressing a key. Feedback indicating the correctness of the response is given.

Stimulus display

The stimulus argument should be a vector of paths to the image files, one per frame. The file paths should refer to the locations of the image files at the time the experiment is *deployed*, so it is often convenient to use the insert_resource function to construct these file paths automatically. The images will be displayed in the order that they appear in the stimulus vector.

The behaviour of an animation trial can be customised in various ways. The frame_time parameter specifies the length of time (in milliseconds) that each image stays on screen. The sequence_reps argument specifies the number of times the sequence repeats.

Response mechanism

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.

If allow_response_before_correct = TRUE the participant is permitted to make a response before the stimulus display completes.

Feedback

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 feedback_duration argument specifies the length of time the feedback is displayed, in milliseconds.

Other behaviour

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

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 stimulus value is a JSON encoded representation of the array of stimuli displayed in the trial.
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.

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.

There are three types of categorization trial, corresponding to the trial_categorize_animation, trial_categorize_html and trial_categorize_image functions.

djnavarro/jaysire documentation built on April 12, 2021, 4:25 a.m.