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 your experiment server. The experiment server can run on any OS with Java.
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 and setting the appropriate server/URL properties in build.properties.
5. Deploy the experiment and start the experiment server, facilitator, and all client application.

Running the software

After a successful deployment, there are three components to the foraging software that need to be run, in order (assuming you are using Java WebStart).

1. Start the experiment server via java -jar -server server.jar or ant server on your server machine.
2. Start one facilitator (you can do this locally on your server via ant fac or java -jar facilitator.jar) or via Java WebStart by opening http://example.com/foraging/facilitator.jnlp in a browser, where http://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, transitioning from one round to the next, deciding when to show instructions and other tasks.
3. Start the foraging client on each machine that will be participating in the experiment. Our foraging experiments run with 10+ participants, partitioned into groups of 5, so we always start the experiment on 10 clients, and start up 5 more clients at a time as more participants trickle in.

Client applications can be started with Java WebStart by opening a browser to http://example.com/foraging/ or by opening the saved client.jnlp file if you have already downloaded one from a previous run.

After the client has started you should see a general instructions / waiting room type message on the screen. If the client fails to start, enable the Java console and examine the errors there or check the server logs. If all else fails, feel free to send us a note.

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 - see troubleshooting deployment.

The experiment won't begin even if you click on Experiment -> Start or Round -> Start as the server is waiting for all clients to submit the introductory quizzes. To skip this step you can enter 'skip-quiz' in the terminal window where you are running the experiment server. Now clicking on Round -> Start will begin the round and transition every client to the actual game round.

When a round ends, each client interface is automatically switched to a debriefing page that typically displays that participant's current earnings and that of their group as well as any additional instructions, debriefing, or survey instruments as needed. After the participants have had enough time to read their debriefing, click on Round -> Show Instructions to display the next round's instructions to each client. If the treatment calls for dedicated communication rounds you can select Round -> Chat, or just continue with the Round -> Start, Show Instructions sequence. To end an experiment round prematurely you can use Round -> Stop.

The explicitness of experiment transitions is designed to let experiment facilitators address any questions or disruptions that may occur in between rounds.

Experiment Data

Raw data generated by an experiment run is stored in the experiment-data directory, relative to where the experiment's server.jar file is being run on the filesystem (for typical installations this is just the root of the codebase you've downloaded). 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. Our typical data processing workflow is:

• Run an experiment
• After the experiment has concluded, copy experiment data from experiment-data to a location with scheduled redundancy and backups, e.g.,

% 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 intrepid data analysts