The foraging experiment is a common pool resource experiment where participants are placed in randomized groups and interact with a spatially explicit renewable resource. It is built on the Social Ecological Systems Experiment Framework and has been used to conduct research studies at Arizona State University, Indiana University, and the University of Alaska-Anchorage.
First, you'll need to clone this git repository via the command-line or a git GUI client, e.g., % git clone https://github.com/virtualcommons/foraging.git
(recommended) or you can download and unpack the latest stable release
Next, you'll need to configure the software. At a minimum, you'll need to customize the build.properties
file and add a set of configuration files representing an experiment treatment to src/main/resources/configuration
. This step is clumsy and could use a lot of improvement.
build.properties
from the build.properties.example
file. At a minimum, make sure you set the
server.address
to the IP address or fully qualified hostname of the machine you are using to serve this applicationsrc/main/resources/configuration
, see the wiki's Configuration page for more details.If you install Docker and docker compose you won't need to manually install Java, Ant, and start a webserver to serve the JNLP files, jar files, and static image assets in addition to the experiment server responsible for the experiment logic and generating data files in ./docker/data
.
NOTE: The docker build currently binds to port 80 instead of port 8080 - if you want to change this, modify the port mapping in docker-compose.yml for the nginx web service.
docker-compose build --pull
to build the foraging Docker imagedocker-compose up -d
to start an experiment server listening on port 16001 and an nginx webserver listening on port 8080 to deliver the foraging client and
facilitator applications via Java WebStart. The relevant URLs are http://<server.address>
to start a WebStart client and http://<server.address>/facilitator.jnlp
to start a WebStart facilitator where <server.address>
is as defined in your build.properties
file.docker/data
. DATA_DIR
to a variety of plaintext files via docker-compose run data
or customize the statistics you see by writing a custom SaveFileProcessor
and adding it to the list in ForagingSaveFileConverter. You can select the data directory with the DATA_DIR
environment variable and convert XML XStream savefiles by setting XML=xml
as an environment variable, e.g., docker-compose run -e DATA_DIR=<data-directory> -eXML=xml data
.docker-compose down
or docker system prune
to clean up your docker images when you're done.You can also install the dependencies directly onto your system (e.g., yum
, apt-get
, or pacman
on your favorite Linux distro) and
You can run a demo from the command-line (e.g., Windows PowerShell or Command Prompt, Mac OSX Terminal.app, or any Linux terminal) after Ant and Java have been installed via
% ant prepare-demo
% ant demo % this will start a server, a facilitator, and 5 clients in the demo treatment
For more detailed instructions, please see the installation instructions on our wiki.
Data generated from the foraging framework has been published in Lab Experiments for the Study of Social-Ecological Systems. Archives of the configuration files used and the experiment data are also available.
If you'd like to add new features or find any bugs, please let us know.