Programming experiments

Instructions for programming experiments in the lab via:

• PCIbex

• jsPsych

• Lookit

PCIbex

As of Spring 2023, most experiments are programmed in PCIbex. PCIbex was created by our friends at Penn Linguistics (Florian Schwarz and Jeremy Zehr) and is fairly simple to learn and use. We recommend the following tutorials to get started:

Basic TutorialPCIbex Documentation

Advanced TutorialPCIbex Documentation

Lab required elements

To write PCIbex to our database, you need to (1) create a unique id for each run and (2) send the results to our database. Add the following code to your PCIbex experiment to accomplish this:

// at the top of your PCIbex main.js, add this line to generate a unique id
const childlanglab_id = crypto.randomUUID();

// use this line to send results to our database anytime you wish to save
// run this at least at the end of your experiment to capture all data
SendResults('https://api.childlanglab.com/v1/runs/pcibex'
    +window.location.search+'&randomid='+childlanglab_id)

// OPTIONALLY you can also create a trial to send results if you like
// and add it to the end of your sequence, for example:
Sequence('trial1', 'trial2', 'sendToDB')

newTrial('sendToDB',
    SendResults('https://api.childlanglab.com/v1/runs/pcibex'
        +window.location.search+'&randomid='+childlanglab_id)
)

Note that, as a security feature, our database expects very specific URL parameters or it will reject your request to save data. Use the + Run experiment button from your experiment's page in the lab database to ensure you include them all properly.

What are the URL parameters?

The parameters are as follows. You would replace what is after the equal sign with the details for your experiment (but note the database +Run experiment button does all this for you! so please use that):

• project=speaker-fluency

• experiment=natnon-spoken-contrastive

• condition=pcibex

• researcher=Yiran%20Chen

• sourcedb=prolific

• location=prolific

• participant={{%PROLIFIC_PID%}}

Notes

• prolific asks you to pass this exact string {{%PROLIFIC_PID%}} to capture the prolific ID

• %20 indicates there is a space (since you can't have a space in a URL string).

To generate your URL with these parameters outside of the +Run experiment button, you'll have to add a question mark after your data collection link and then include each item above separated by ampersand (&). For example:

https://upenn.pcibex.net/p/UvmnVQ/?project=speaker-fluency&experiment=natnon-spoken-contrastive&condition=pcibex&researcher=Yiran%20Chen&sourcedb=prolific&location=prolific&participant={{%PROLIFIC_PID%}}

Recordings

PCIbex can record audio and video from participant webcams. Our lab's recordings get saved to the penn specific instance of PCIbex, which includes an s3 bucket. To ensure we can link recordings to data in our database, please name your recordings after the childlanglab_id you created in Lab required elements. For example:

// name your newMediaRecorder with the childlanglab_id 
newMediaRecorder(childlanglab_id, "audio")
        .log()
        .record()

// and refer to it by name whenever you get it
getMediaRecorder(childlanglab_id)
        .stop()

Preloading stimuli

PCIbex allows you to easily preload stimuli via a zip file with the PreloadZip() function. You can host your zipped resources easily in our lab's s3 bucket via the s3 page on our database.

Conditions

Assigned by PCIbex

One way to have different conditions in your experiment is to have PCIbex assign them. If PCIbex assigns the condition, enter pcibex as the condition in the lab URL parameters.

Passed in from URL variables

You can also make use of our lab's condition URL parameter in your PCIbex code. For example:

// create a global variable called condition
const condition = GetURLParameter( “condition” )

// use it in your code, to select a condition file, for example
// if you name your csv after your condition
const TABLE_NAME = condition+'.csv'

// Then use your template as normal
Template(TABLE_NAME, row =>
    newTrial("TRIAL_LABEL",
        newX("ELEMENT_1", row.COLUMN_NAME)
            .COMMAND_1()
    )
)

jsPsych

As of Spring 2023, please use PCIbex whenever possible!

Prior to Spring 2023, most experiments were programmed with jsPsych, a javascript framework for developing experiments that run in a web browser. If you've never used jsPsych before, we recommend the following tutorials:

The Basics: Hello World - jsPsych

Demo Experiment: Simple Reaction Time Task - jsPsych

For more advanced topics, you can also checkout the video tutorials:

Video Tutorials - jsPsych

Lookit

For asynchronous studies with babies and kids, we have a virtual lab on Lookit.

Your first experiment

If this is your first experiment using lookit, you'll need to join the lookit slack channel, join our lab on lookit, and complete the lookit tutorial below:

1. Accessing Lookit and community — Lookit documentation

Lab templates

These templates contain frames such as initial instructions or setting up video that can be used for any study. They do not contain any actual trials.

To use these templates, go to the main page for the template on Lookit (linked under each tab below) and click "Clone Study" in the menu on the right. Be sure to do this so you aren't editing the original template!

Then, on your copy of the study, click "Edit Study" in the menu on the right. Scroll down to find the protocol generator section, and click on it to begin editing.

You'll see that frames and frame_sequence contain JSON, just like in the regular protocol configuration.

Another option is to make a copy of the .js file of the protocol generator on Github (also linked below). You can work in that file, create a new study on Lookit, and paste your code into the protocol generator section.

For more information on protocol generators and examples of how they can be used, see the Lookit documentation.

Baby Looking Time

If you're creating a baby looking time study, use this template. Below is a preview of the template, so you can see what each frame looks like!

Click here for the .js file of the template on Github, and click here for the study on Lookit.

The comments in the template will tell you where you should make edits (e.g. placeholder text that should be replaced). Of course, you can also edit anything else that you'd like to edit.

Toddler Looking Time

If you're creating a toddler looking time study, use this template. Below is a preview of the template, so you can see what each frame looks like!

Click here for the .js file of the template on Github, and click here for the study on Lookit.

The comments in the template will tell you where you should make edits (e.g. placeholder text that should be replaced). Of course, you can also edit anything else that you'd like to edit.

School-Age Kids

If you're creating a study for school-age kids, use this template. Below is a preview of the template, so you can see what each frame looks like!

Click here for the .js file of the template on Github, and click here for the study on Lookit.

The comments in the template will tell you where you should make edits (e.g. placeholder text that should be replaced). Of course, you can also edit anything else that you'd like to edit.

If you spot a problem with any of the current templates or would like to request a new template, please create a new issue on Github!