4  jsPsychMonkeys

jsPsychMonkeys: Release Monkeys to a jsPsych experiment using the R package {targets}, docker and {RSelenium}.

In brief

With jsPsychMonkeys you can:

  • Simulate participants online and offline

  • Simulate participants sequentially and in parallel

  • Ask your Monkeys to take pictures of each screen of the protocol

  • Make the behavior of the Monkeys reproducible setting a random seed associated with their unique id

  • Store logs of the process, including console logs with errors

  • Watch your participants randomly click things in VNC (you will need to install realvnc)

See QuickGuide for basic instructions.

Setup

You may need to install some system libraries first:

  • sudo apt install libssl-dev libcurl4-openssl-dev libxml2-dev docker
  • If the Monkeys do their work but no csv’s appear, make sure your the docker user has write access to the ~/Downloads folder.
  • Install docker desktop
  • Update wsl (in a command prompt): wsl - update

4.1 How to simulate participants

If you are on Windows, make sure Docker Desktop is open and running before releasing the monkeys.

To run a monkey locally:

jsPsychMonkeys::release_the_monkeys(uid = 1, 
                                    local_folder_tasks = "~/Downloads/protocol999/")

To run a monkey on a server:

jsPsychMonkeys::release_the_monkeys(uid = 1, 
                                    server_folder_tasks = "999", 
                                    credentials_folder = "~/.vault/")

credentials_folder must contain SERVER_PATH.R and .credentials. See below for the expected content of those files.

4.2 Parameters available

There are a few parameters for jsPsychMonkeys::release_the_monkeys() that can be useful:

  • uid_URL = TRUE: The uid is passed in the URL (e.g. &uid=1)

  • local_folder_tasks = rep("Downloads/tests/test_prototol", 25): Passing a vector of multiple protocols will make the Monkeys to complete all of them.

  • times_repeat_protocol: How many times a monkey should complete the same protocol (useful for longitudinal protocols or to speed up things)

  • time_to_sleep_before_repeating_protocol: How many seconds to wait before reattempting to complete the protocol

  • keep_alive = TRUE Keep the docker container alive after completing the tasks

  • DEBUG = TRUE Activate DEBUG mode. Lot’s of stuff will show up in the console.

  • open_VNC = TRUE Activate DEBUG mode and open a VNC container to see the Monkeys’ progress.

  • screenshot = TRUE The Monkeys will take a picture of all the pages they see. The .png files are stored in outputs/screenshots

  • debug_file = TRUE Activate DEBUG mode and store all the console output in the outputs/log

  • big_container = TRUE Sets the Shared memory size (/dev/shm) to 2 gigabytes. This is useful to avoid long/complex protocols to crash

  • disable_web_security = TRUE If you are running a local protocol that loads external files (e.g. consent form in a html file), you may need this. Only works with Google Chrome.

  • console_logs = TRUE Store the browser’s console logs. Only works with Google Chrome

  • forced_random_wait = TRUE Will wait a randomly sampled number of seconds on page 4

  • forced_seed = 11 Set a random seed so the Monkeys’ behavior will be fully reproducible

  • forced_refresh = 20 Refresh browser in page 20 (if TRUE is given, it will refresh in a randomly sampled page)

  • sequential_parallel Choose between sequential, the default, or parallel

  • number_of_cores Number of cores for parallel monkeys. The default is half of the available cores

4.2.1 Parameters details

  • local_folder_tasks: If the folder is not accessible to Docker (anything outside the Download folder), jsPsychMonkeys will create a copy of the protocol in Downloads/JSPSYCH/

4.3 Release a horde of Monkeys!

If you want a horde of Monkeys, you can set up sequential_parallel = "parallel" and choose how many monkeys will run in parallel with number_of_cores:

jsPsychMonkeys::release_the_monkeys(uid = "1", 
                                    local_folder_tasks = "~/Downloads/protocol999/",
                                    sequential_parallel = "parallel",
                                    number_of_cores = 4)

10 Monkeys completing a protocol in parallel:

4.4 Issues

If the setup configuration steps didn’t work… You may need to do one of the things below:

  • Switch to Ubuntu :-)

  • Run participants manually

4.5 Technical aspects

4.5.1 Launch Monkeys on a server

You will need two files for the configuration in the hidden and NOT SHARED .vault/ folder:

  • .vault/SERVER_PATH.R: contains the path where the protocols are located in your server: server_path = "http://URL_OF_YOUR_SERVER/PROTOCOLS_GENERAL_FOLDER/"

  • .vault/.credentials: contains a list with the user and password for the server:

list(IP = "IP ADDRESS OF SERVER",
     main_FOLDER = "/MAIN/FOLDER/AND/PATH/TO/FILES/IN/THE/SERVER/",
     user = "YOUR SERVER USERNAME",
     password = "YOUR VERY STRONG SERVER PASSWORD")

With the server_folder_tasks you will set the sub-folder where the protocol is located. In the example below the Monkeys would go to, http://URL_OF_YOUR_SERVER/PROTOCOLS_GENERAL_FOLDER/999

4.5.2 Alternatives

Since jsPsych 7.1 there is a simulation mode available, which should be much faster than the good ol’ Monkeys. Once we migrate to jsPSych 7.x, we may retire this section.