Contribute a Survey

A survey is (for now) just an experiment that is primarily questions. Since this is a common need for researchers, we have developed a simple means to turn a tab separated file into a web-ready experiment. We will be using the Experiment Factory survey generator (a Docker container) to convert a tab delimited file of questions (called survey.tsv) with a standard experiment factory config.json to generate a folder with web content to serve your experiment.


First, generate your questions and config. As linked above, the configuration file has the same requirements as an experiment in the Experiment Factory. For template, you should put "survey". The survey file should have the following fields in the first row, the header:

We have provided an folder with examples (state-mindfulness-survey) that you can use to generate a new survey.

Run the Container

To generate the survey, we will run the container from the folder where our two files are. If we run without specifying start we will get a help prompt. But really we don’t need to look at it, because most of the arguments are set in the image. We just need to make sure that

  1. the config.json and survey.tsv are in the present working directory
  2. we specify start
  3. we map the $PWD (or where our survey and config are) to /data in the container

Let’s just wget the needed survey.tsv and config.json, because the repository has the completed survey.

mkdir -p /tmp/mindfulness-survey
cd /tmp/mindfulness-survey
config.json    survey.tsv

Make a README to describe your survey!

echo "My Awesome Survey!" >>

The output is minimal, but when we finish, our survey is ready!

$ docker run -v $PWD:/data expfactory/survey-generator start
Writing output files to /data/index.html

$ ls
config.json  css  index.html  js  LICENSE  survey.tsv

Now we can easily test it by opening a web browser:

python3 -m http.server 9999

If you need to generate the index.html again and force overwrite, use --force.

docker run -v $PWD:/data expfactory/survey-generator start --force


If you want to build the image:

docker build -t expfactory/survey-generator .