Build the experiment files

Source: R/build_experiment.R

Build the experiment files

build_experiment(
  timeline,
  path,
  experiment_folder = "experiment",
  data_folder = "data",
  experiment_title = NULL,
  jsPsych_path = file.path(system.file("extdata", "jsPsych", package = "jaysire")),
  resources = NULL,
  columns = NULL,
  ...
)

Arguments

timeline

A timeline object
path

A string specifying the path in which to build the experiment
experiment_folder

A string specifying the experiment subfolder
data_folder

A string specifying the data subfolder
experiment_title

A string specifying the title of the experiment
jsPsych_path

A string specifying the path to jsPsych
resources

A tibble specifying how to construct resource files, or NULL
columns

Additional data values (constants) to store
...

Arguments to pass to jsPsych.init()

Value

Invisibly returns NULL

Details

The build_experiment() function is used to build the actual jsPsych experiment from the abstract description contained in the timeline argument. The input for the timeline argument should be a timeline constructed using build_timeline() and the path argument should specify the path to the folder in which the experiment files should be created. If the experiment needs to rely on resource files (e.g., images, audio files etc) then the resources argument should be a tibble containing the information needed to copy those files to the appropriate location. The easiest way to do so is by using the build_resources() function: see the documentation for that function for a more detailed description of what this tibble should contain.

When called, the build_experiment() function writes all the experiment files, compiled to javascript and HTML. The file structure it creates is as follows. Within the path folder are two subfolders, data_folder and experiment_folder (named "data" and "experiment" by default). The data_folder folder is empty, but intended to serve as a location to which data files can be written. The experiment_folder folder contains the "index.html" file, which is the primary source file for the experiment page, and an "experiment.js" file that specifies the jsPsych timeline and calls the jsPsych.init() javascript function that starts the experiment running. It also contains a "resource" folder with other necessary files (see build_resources() for detail). If specified, experiment_title will set the name of the experiment as the title of the HTML file in "index.html". jsPsych_path is a string that specifies the path to jsPsych.

Because build_experiment() creates the call to jsPsych.init(), it can also be used to specify any parameters that the user may wish to pass to that function via the .... There are quite a number of parameters you can specify this way:

  • display_element is a string specifying the ID of an HTML element to display the experiment in. If left blank, jsPsych will use the <body> element to display content. All keyboard event listeners are bound to this element. In order for a keyboard event to be detected, this element must have focus (be the last thing that the subject clicked on).

  • on_finish is a javascript function that executes when the experiment ends. It can be constructed manually using insert_javascript(), but in many cases there is a jaysire function that will create the appropriate function for you. For example, if you want the data to be saved locally at the end of the experiment you can set on_finish = save_locally(), whereas if you want the data to be saved to the Google Datastore you can set on_finish = save_googlecloud().

  • on_trial_start is a javascript function that executes when a trial begins.

  • on_trial_finish is a javascript function that executes when a trial ends.

  • on_data_update is a javascript function that executes every time data is stored within the jsPsych internal storage.

  • on_interaction_data_update is a javascript function that executes every time a new interaction event occurs. Interaction events include clicking on a different window (blur), returning to the experiment window (focus), entering full screen mode (fullscreenenter), and exiting full screen mode (fullscreenexit).

  • on_close is a javascript function that executes when the user leaves the page. This can be used, for example, to ensure that data are saved before the page is closed.

  • exclusions is used to specify restrictions on the browser the subject can use to complete the experiment. See list of options below.

  • show_progress_bar is a javascript logical value. If true, then a progress bar is shown at the top of the page.

  • message_progress_bar is a string containing a message to display next to the progress bar. The default is 'Completion Progress'.

  • auto_update_progress_bar is a javascript logical value. If true, then the progress bar at the top of the page will automatically update as every top-level timeline or trial is completed.

  • show_preload_progress_bar is a javascript logical value. If true, then a progress bar is displayed while media files are automatically preloaded.

  • preload_audio is a javascript array of audio files to preload before starting the experiment.

  • preload_images is a javascript array of image files to preload before starting the experiment.

  • preload_video is a javascript array of video files to preload before starting the experiment.

  • max_load_time is a numeric value specifying the maximum number of milliseconds to wait for content to preload. If the wait time is exceeded an error message is displayed and the experiment stops. The default value is 60 seconds.

  • max_preload_attempts is numeric value specifying the maximum number of attempts to preload each file in case of an error. The default value is 10. There is a small delay of 200ms between each attempt.

  • use_webaudio is a javascript logical. If false, then jsPsych will not attempt to use the WebAudio API for audio playback. Instead, HTML5 Audio objects will be used. The WebAudio API offers more precise control over the timing of audio events, and should be used when possible. The default value is true.

  • default_iti is a numeric value setting the default inter-trial interval in milliseeconds. The default value if none is specified is 0.

  • experiment_width is a numeric value setting the desired width of the jsPsych container in pixels. If left undefined, the width will be 100% of the display element. Usually this is the <body> element, and the width will be 100% of the screen size.

Note: as of the current writing not all of these have been tested (even informally) through jaysire. Please report any unexpected behaviour by opening an issue on the GitHub page.