jsPsych experiments

How to create and run jsPsych experiments in the lab via the lab's web server

Prerequisites

You will need:

• Docker desktop to test your experiments locally

• A text editor — I like Visual Studio Code — to edit your experiment code

• TablePlus to view your development database

Initial setup

If this is your first time running a jsPsych experiment in the lab, OR your first time working with the new web server, follow these initial steps to get setup to create your experiments and post the to the web server.

Video tutorial of initial setup process

Clone your experiments repo

Each grad student in the lab has access to a repository called firstname-experiments which contains all of the experiments that particular student runs on the web server. You'll need to clone your firstname-experiments repository onto your local computer in order to work on your experiment code.

Navigate to the folder where you want your experiments to live on your local computer. I have a folder called github on my computer where I keep all of my GitHub repositories.

cd folderonyourlocalmachine

Then, clone your experiments repo (replacefirstname with your first name).

git clone [e-mail]:pennchildlanglab/firstname-experiments.git

Configure your environment

Now that your experiments repo is cloned, navigate to the newly created firstname-experiments folder and make a copy of the .env.sample file called .env.

cd firstname-experiments

cp .env.sample .env

Start the development containers

To work on the code, start the project's local development containers by running the following from inside the firstname-experiments folder.

docker-compose up -d --build

When your containers are running, a web server will be available for you locally at:

http://localhost:8080localhost

When you visit this address, you should see a landing page that says "Welcome to Firstname's webserver".

Run the sample experiment

To make sure your local development environment is working properly, you should run the sample jsPscyh experiment. Navigate to:

http://localhost:8080/experiment-sample/experiment.htmllocalhost

Run yourself in the sample experiment — it should only take a minute or two — and then check to make sure your data saved in your development database. The development database was created for you when you started your development container. You can access it via TablePlus by entering the following credentials:

Great! Now you are ready to create or edit your experiments

Edit experiments

To create or edit an experiment, you'll need to take the following steps:

1. Create a new branch

2. Make your changes

3. Commit your changes

4. Make a pull request

5. Address any requested changes

6. Merge your pull request

7. Delete your branch

Keep reading for more details about each step and/or watch the video for a tutorial.

Create or edit an experiment

Create a new branch

Your firstname-experiments repository has a main branch — these are the files that are live on the lab's webserver.

To prevent any issues with broken code interrupting running experiments, you will not be able to commit changes directly to the main branch. Instead, you need to create a new branch with a descriptive name and make changes there.

Start by making sure your local copy of the repository is up to date with the main branch:

# checkout the main branch
git checkout main

# pull any changes from the github repo
git pull origin main

Next, create your new branch:

# Create a new branch
git branch name-of-branch

To make changes on the new branch, you'll need to "checkout" the branch:

# Checkout a branch
git checkout name-of-branch

Make your changes

Make whatever changes you wish to your experiment on your new branch and test your code locally. To test, you'll need to make sure your development containers are running. From inside your local repo, run:

docker-compose up -d --build

Your webserver will be available at:

http://localhost:8080localhost

And your experiment will be available via that webserver at https://localhost:8080/your-experiment-folder/experiment-file.html where:

• your-experiment-folder is the folder name inside the experiments folder that you are editing and

• experiment-file.html is the name of the experiment file you are editing.

Run through your experiment and make sure the data save as you expect in your dummy database. See above for how to check the database.

Commit your changes

When you are ready to commit your changes — you might do this at the end of a workday, or when you are finished with your changes — you can push them to the github repository. This way, they will be (1) saved in the repo and (2) other users can see what you are working on.

To commit your changes, you need to add, commit, and push.

# Add all of the changes you've made
git add .

# Commit your changes and include a message indicating what you've changed
git commit -m "description of your changes"

# Push your changes to your branch
git push origin name-of-branch

Make a pull request

When you are ready for your changes to go live on the webserver, make a pull request. First, visit the your github repository in the pennchildlanglab github.

If you've committed your changes, will see a notification that your branch has recent pushes and a green button inviting you to Compare & pull request.

Click the Compare & pull request button to make your pull request. You will be asked to write a subject line describing briefly what your pull request is for, and a message in which you give more details and explain that you tested everything and it saved as expected in your dummy database. When you are ready, click the Create pull request button.

Katie will review your changes by reading your message and clicking the Files changed tab to see an overview of what changes you made.

Address requested changes

Katie may reject your pull request and ask that you make some revisions. Common reasons for rejected pull requests include:

1. Changes to protected files outside the experiments folder - many of the files and folders in your firstname-experiments folder are required configuration files that allow your code to work in the development container and on the webserver. If you make changes to any of these files or folders your pull request will be rejected to protect the webserver.

2. Changes to protected files inside the experiments/childlanglab folder - this folder contains required front- and back-end javascript and php files that allow your experiments to push data to the lab's database. If you make changes to anything in this folder your pull request will be rejected.

3. Missing lab required elements in experiment.html files - the lab requires a few elements inside html files (the jsPsych experiment code) to save data in the database. If any of these required elements are missing or incorrect, your pull request will be rejected. These requirements are outlined below in the Create new experiment section.

Merge your pull request

Once your changes pass all checks — meaning you've responded to any request for changes and your pull request won't break any existing experiments — Katie will merge your pull request with the main branch and your changes will go live on the webserver.

Delete your branch

After your pull request is merged, delete your branch. This lets everyone know that work on the branch is finished and prevents anyone (including you!) from accidentally using old branches. There is no risk of loosing anything when you delete your branch. Branches can always be restored if needed.

You can delete your branch right from the pull request on github:

Delete your branch from the Github repo

You may also wish to delete your branch on your local computer. To do that, first checkout the main branch and pull any changes from the Github repo:

# checkout the main branch
git checkout main

# pull any changes from the github repo
git pull origin main

Then, delete your branch locally:

# delete your branch
git branch -d name-of-branch

# you can also use the -D flag if you want it to override warnings
git branch -D name-of-branch

URL variables

The lab's database is expecting to collect some specific information about each "run" of an experiment. Things like: the project name, the experiment name, the condition, the lab member who ran the participant, the participant id number, and more.

In jsPsych experiments, we pass this information to the experiment through URL variables. URL variables (also called URL parameters or query strings) are just a way to pass information through a URL. URL variables are structured as a collection of key=value pairs (researcher=iris) that are separated by ampersands (&) and come after a question mark (?) at the end of a URL string.

URL parameters, figure by semrush.com

Key	Value	Description
participant	{{%PROLIFIC_PID%}} or test	The participant's ID number, usually from the recruitment database (prolific, lookit, etc). Use {{%PROLIFIC_PID%}} when running a prolific participant or test when running a test.
project	project-name	The project's name (from the lab's database). If you don't see a project that this experiment belongs to, ask Katie to set one up for you.
experiment	experiment-name
condition	condition-name	The name of the condition. This will depend on how you are using this variable to select conditions in your experiment. Sometimes it's a number, sometimes it's a descriptive word. If conditions are randomly assigned, we usually make the condition name random.
researcher	firstname	The first name of the researcher running the experiment.
sourcedb	prolific or lookit	The source database that participants were recruited from. For jsPsych experments this is most often prolific.
location	subdomain or lookit or childlanglab or camp	The location where the participant was run. If run on prolific, this will be your subdomain on the webserver (e.g. daoxin or yiran since the domain is daoxin.childlanglabexperiments.org)

Admin

First time user

Create a repository for the user

• use template to create a new repo (just main branch)

• clone this repo to your local machine

Setup remote with post-receive hook

• ssh into the server as root

• init a bare repo with git init --bare /path/to/bare_repo.git

  • `git init --bare /home/katie/repos/username-experiments.git`

• create an empty directory in deployed_experiments

  • mkdir /home/katie/deployed_experiments/username.experiments.org

• create post-receive hook

  • nano /home/katie/repos/username-experiments.git/hooks/post-receive

!/bin/bash
TARGET="/home/katie/deployed_experiments/username.childlanglabexperiments.org"
GIT_DIR="/home/katie/repos/username-experiments.git"
BRANCH="main"

while read oldrev newrev ref
do
        # only checking out the master (or whatever branch you would like to deploy)
        if [ "$ref" = "refs/heads/$BRANCH" ];
        then
                echo "Ref $ref received. Deploying ${BRANCH} branch to production..."
                git --work-tree=$TARGET --git-dir=$GIT_DIR checkout -f $BRANCH
        else
                echo "Ref $ref received. Doing nothing: only the ${BRANCH} branch may be deployed on this server."
        fi
done

• make sure post-receive is executable

  • chmod +x /path/to/bare_repo.git/hooks/post-receive

Add the remote via your local machine

• git remote add deploy [e-mail]/home/katie/repos/username-experiments.git

• git push deploy

• check remote to make sure files were checked out

• [do this after you deploy the container to check that changes deploy propoerty]make a commit and push to main and deploy branches

Start the deploy container on the server

• .env file

• docker-compose -f docker-compose-deploy.yml up -d --build

Setup an nginx proxy host

• manage.childlanglabexperiments.org

• Add proxy host

• enter the container name on port 80

• get an SSL cert via let's encrypt

• test (you should see "Welcome to User's webserver"

Test push-to-deploy new changes

• change the index.html to user's name.

Deploy a new experiment

• user makes a new pull request

  • check code (no changes to protected folders)

  • merge and rebase the develop repo

  • this will merge to main branch

• from your local repo, deploy the changes on main

  • checkout main git checkout main

  • run git pull origin main

  • Deploy them on the server git push deploy main