Before you start
We've migrated our old documentation from our wiki to this website. If you still encounter any broken links here please let us know.
First, make sure you've followed these steps to make sure you have the appropriate environment set up to install and run the foraging software. In order to deploy and run the foraging software you'll need:
- JDK 1.6 or better
- (optional) Maven if you want to use the built-in Jetty webserver
- Download the foraging codebase and unzip it on the server you wish to use to run the experiment. The foraging experiment server can be run on Windows, Linux, or Mac.
- Configure the foraging experiment
- Deploy the foraging experiment onto your server
After a successful deployment, there are three components to the foraging software that need to be run, in order:
- The experiment server can be started on your server machine via
java -jar -server server.jar or
- Start up one facilitator application via Java WebStart by opening a browser to
http://example.com/foraging/facilitator.jnlp (where example.com should be replaced with your server machine's URL). The facilitator application is used by the person running the experiment to monitor and drive the experiment workflow.
- Start up client applications on each and every client machine that will be participating in the experiment. For example, our typical foraging experiments run with 10-20 participants, partitioned into groups of 5. So in our case, we'd start the client application on either 10, 15, or 20 workstations, depending on how many participants we had. You can start up a client application via Java WebStart similar to the facilitator application by opening a browser to
http://example.com/foraging/. You should see a general instructions / waiting room message on each client screen.
After all clients and the facilitator have successfully connected to the server, return to the facilitator interface and click on the Round -> Show Instructions menu item to send the first round's instructions to each client interface. You should see every connected client's interface change to display the instructions for the practice round. If the images in those instructions don't display properly, there is a problem with the webserver / deployment configuration.
At this point the experiment won't begin even if you click on Experiment -> Start or Round -> Start because the server is waiting for all the clients to submit their quizzes. If you want to skip this step, you can tell the server to skip the quizzes by going to the terminal window where you started the experiment server and typing
skip-quiz and hitting enter. At this point you should be able to start the actual experiment round.
After a round ends, each client interface will be automatically shown a debriefing page that displays their current earnings and that of their group. After this has been displayed you'll click on Round -> Show Instructions to display the next round's instructions to each client, and after you're ready to begin the next round you'll either click on Round -> Start to start a regular round or Round -> Start Chat to start a chat round. If you'd like to stop a round prematurely, you can hit Round -> Stop at anytime.
The raw data saved from the experiment is stored in a directory relative to where you are running the experiment server, in the
experiment-data directory. The files themselves are stored in directories following a
month-day-year/time-of-experiment-run format. You can use the
ant convert target to generate various plaintext csv files and statistics for analyzing the experiments. By default the
convert target looks in a
raw-data directory relative to the root of the codebase. You can change this by passing in a
savefile.dir property which should point at a directory containing the
month-day-year/time-of-experiment-run subdirectories. We'll be working to make this process a little smoother eventually. A typical workflow that we use for processing data is:
- Run an experiment
- Copy experiment data from
alllee% cp -rp experiment-data/* /data/foraging/raw
alllee% l /data/foraging/raw
drwxrwsr-x 10 alllee alllee 4096 2010-04-15 16:06 ./
drwxrwsr-x 7 alllee alllee 4096 2010-08-05 17:41 ../
drwxrwsr-x 4 alllee alllee 4096 2010-03-22 12:44 03-10-2010/
drwxrwsr-x 4 alllee alllee 4096 2010-03-22 12:45 03-11-2010/
drwxrwx--- 5 alllee alllee 4096 2010-03-31 15:19 03-31-2010/
drwxrwx--- 3 alllee alllee 4096 2010-04-01 11:34 04-01-2010/
drwxrwxr-x 4 alllee alllee 4096 2010-04-06 15:51 04-06-2010/
drwxrwx--- 4 alllee alllee 4096 2010-04-15 14:28 04-07-2010/
drwxrwx--- 4 alllee alllee 4096 2010-04-14 13:32 04-14-2010/
drwxrwx--- 5 alllee alllee 4096 2010-04-15 14:25 04-15-2010/
ant convert -Dsavefile.dir=/data/foraging/raw to convert all the data at /data/foraging/raw
rsync -avzP /data/foraging/raw --exclude "*.save" --exclude "*.xml" /data/foraging/processed to copy over all the generated CSV text files into the