The Virtual Commons

building extensible software for collective action research


Foraging Documentation

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:

  1. JDK 1.6 or better
  2. Ant
  3. (optional) Maven if you want to use the built-in Jetty webserver

Setting up the software

  1. 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.
  2. Configure the foraging experiment
  3. Deploy the foraging experiment onto your server

Running the software

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

  1. The experiment server can be started on your server machine via java -jar -server server.jar or ant server
  2. Start up one facilitator application via Java WebStart by opening a browser to (where 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.
  3. 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 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. We'll be working to make this process a little smoother eventually. A typical workflow that we use for processing data is:

  1. Run an experiment
  2. Copy experiment data from experiment-data to /data/foraging/raw
    alllee% cp -rp experiment-data/* /data/foraging/raw
    alllee% l /data/foraging/raw
    total 40
    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/
  3. Run ant convert -Dsavefile.dir=/data/foraging/raw to convert all the data at /data/foraging/raw
  4. Run rsync -avzP /data/foraging/raw --exclude "*.save" --exclude "*.xml" /data/foraging/processed to copy over all the generated CSV text files into the /data/foraging/processed directory.

Software Prerequisites

Setting up a server to run our experiment software

In order to run our Java-based experiment software for the foraging or irrigation experiments, you'll need to download a few tools.

  1. The latest version of the Java JDK is recommended. Currently, the software packages hosted by SourceForge are source packages that must be compiled on your target system in order to run properly. We plan to improve the installation and configuration of the software eventually, if you'd like to help out, please let us know.
  2. The latest version of Ant is needed to build and deploy the source code properly.
    Instructions on how to install Ant on a variety of operating systems are detailed here but the basic steps are to:
    1. download the binary distribution of Ant
    2. unpack it somewhere (and keep track of its location!). On Linux this might be /opt/ant or /usr/local/ant or /usr/share/ant, on Windows it is wherever you decide to install it. For the purposes of this example we suggest a location like C:\tools\ant
    3. set the JAVA_HOME and ANT_HOME environment variables to point to the appropriate locations. The deploy.bat file in the foraging directory can be used as a template to deploy the software on Windows, just change the paths of ANT_HOME and JAVA_HOME to reflect your system's configuration, e.g., C:\tools\ant
    4. set the PATH variable to include the bin directories under JAVA_HOME and ANT_HOME so you have access to the ant and java executables
  3. (optional) Download and install Maven if you don't want to set up and install your own webserver.
  4. Finally, download the actual software packages from our source repositories at BitBucket.
Syndicate content