The Virtual Commons

building extensible software for collective action research

forestry

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 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.
  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 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.

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.
Syndicate content