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

First, install Docker Desktop.

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.

In some versions of Ubuntu, you do not need to install docker. If anything fails, installing Docker desktop could help. Alternatively, maybe you need docker as non-root user?, but be careful, as this leaves your system more vulnerable.

  • 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.