Installation

Server Setup

In order to run our Java-based experiment software you'll need to:

1. Install the latest Java JDK
2. Install Ant, and optionally Maven to use the built-in Jetty webserver
3. Download the foraging codebase or clone the git repository onto the server you wish to use to run the experiment. The foraging experiment server runs on Windows, Linux, or Mac
4. Configure the experiment you'd like to run by copying your configuration files (server.xml and round*.xml files) into src/main/resources/configuration.
5. Deploy the foraging experiment

Running the software

After a successful deployment, there are three components to the foraging software that need to be run, in order:

using Java WebStart / JNLP

• Start the experiment server via java -jar -server server.jar or ant server
• Start up one facilitator 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 we start the client application on 10, 15, or 20 workstations, depending on how many participants are available. You can start up a client application via Java WebStart similar to the facilitator application by opening a browser to http://example.com/foraging/ or by double clicking the saved client.jnlp file if you have already downloaded one from a previous run. 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.

Experiment Data

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. A typical workflow that we use for processing data is:

• Run an experiment
• Copy experiment data from experiment-data to a backed up location, e.g., /data/foraging/raw

#!bash
% cp -rp experiment-data/* /data/foraging/raw
% l /data/foraging/raw
total 40
drwxrwsr-x 10 user user 4096 2010-04-15 16:06 ./
drwxrwsr-x  7 user user 4096 2010-08-05 17:41 ../
drwxrwsr-x  4 user user 4096 2010-03-22 12:44 03-10-2010/
drwxrwsr-x  4 user user 4096 2010-03-22 12:45 03-11-2010/
drwxrwx---  5 user user 4096 2010-03-31 15:19 03-31-2010/
drwxrwx---  3 user user 4096 2010-04-01 11:34 04-01-2010/
drwxrwxr-x  4 user user 4096 2010-04-06 15:51 04-06-2010/
drwxrwx---  4 user user 4096 2010-04-15 14:28 04-07-2010/
drwxrwx---  4 user user 4096 2010-04-14 13:32 04-14-2010/
drwxrwx---  5 user user 4096 2010-04-15 14:25 04-15-2010/
% ant convert -Dsavefile.dir=/data/foraging/raw # converts all the data at /data/foraging/raw
% rsync -avzP /data/foraging/raw --exclude "*.save" --exclude "*.xml" /data/foraging/processed # copy all the generated CSV text files into the /data/foraging/processed directory
% tar zcvf processed-data.tar.gz /data/foraging/processed # create a tarball of all the data files to be analyzed by our intrepid data analysts