Template for a free recall experiment with automatic audio transcription
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


autoFR logo


AutoFR is a verbal free recall experiment that incorporates automatic speech-to-text processing by wrapping the Google Cloud Speech API. We've implemented the experiment using jsPsych and psiTurk for easy deployment on Amazon Mechanical Turk. (You can also follow the instructions below to run the experiment locally.) This code may be used "as is," or it may be used as a template to create your own variants of this experiment.

Installing autoFR

  • Install Docker and Google Chrome
  • Clone this repo: git clone https://github.com/ContextLab/autoFR.git
  • Set up Google Cloud Speech following these instructions. Once you have a JSON formatted API keyfile downloaded, put in in the exp/autoFR/google-credentials folder, renaming it credentials.json.

Running autoFR

  • Run docker
  • Navigate to the cloned repo in terminal and type docker-compose up -d (this may take a little while)
  • Then, type: docker attach autofr_psiturk_1
  • Navigate to the experiment folder: cd autoFR
  • Type psiturk. This should spin up a psiturk server
  • Then, type: server on (you may get an error the first time you try this, but try it again).
  • Then type debug <-this will initialize a local version of the experiment.
  • Point your Google Chrome browser to localhost:22362 and follow the on-screen instructions to run in the experiment!

IMPORTANT NOTE: Make sure you have pop-up blockers turned OFF!!

Analyzing the data

The audio data is stored in the folder autoFR/audio. Each new subject's data is put in a folder with a unique name. At the end of an experiment, the audio data is automatically shipped off to Google Speech, and a text file and response object will be saved out for each list.

We've created Quail, a Python toolbox for analyzing and plotting free recall data. Detailed instructions may be found here; in summary, Quail relies on a data structure called an egg. To create an egg object from the data you collect from this experiment (so that you can analyze it with Quail, make plots, etc.), follow the example code below:

import quail

# location of the database
dbpath = '~/exp/autoFR/participants.db'

# location of the audio files
recpath = '~/exp/autoFR/audio/'

# option to remove subjects
remove_subs = ['debugV2WLPQ:debugQN6O0V', 'debugFIGADU:debugPSS00O', 'debugZ5SE8F:debugYT96YP']

# experiment word pool
wordpool = '~/exp/autoFR/static/files/cut_wordpool.csv'

# experiment version (defined in autoFR/config.txt)
experiments = ['0.0', '1.0', '1.1', '6.1', '7.1', '8.1']

# optionally group experiments with different versions into a single egg
groupby = {'exp_version': [['0.0', '1.0', '1.1'], '6.1', '7.1', '8.1']}

# generate a list of `eggs` of len(groupby['exp_version'])
eggs = quail.load(dbpath=dbpath, recpath=recpath, remove_subs=remove_subs,
                  wordpool=wordpool, experiments=experiments, groupby=groupby)