The Virtual Commons

building extensible software for collective action research

experiments

Google Summer of Code 2012 Ideas

We have the following projects in active development:

  1. client-server networked multiplayer "games" in Java that are deployed via ant/ivy/maven and WebStart
  2. rich web based experiments using Django on the back-end and socket.io, jQuery, and Sencha Touch on the front-end

We have over five years of experience working with student developers and are currently mentoring a team of 5 undergraduate computer science students from ASU's engineering capstone course alongside two REUs (Research Experience for Undergraduates) students and a graduate RA. Our experiment software is currently being used here at Arizona State University, at Indiana University - Bloomington, at the University of Maine, in Stockholm, and Bratislava and we hope to make it even more widely accessible with the following improvements.

Web-based projects

We are actively developing a web-based experiment framework for social science researchers that use experiments to study collective action issues (http://vcweb.asu.edu) as well as an HTML5 mobile app entitled Lighter Footprints. The app places people into groups where each participant can learn about and "perform" virtual activities that would reduce their carbon footprint (riding your bike to work or carpooling, taking public transportation, eating locally grown food, turning off your computer at night, etc.). Each activity has an associated number of "green points" that are earned for performing that activity. Groups that earn a certain number of green points can advance in level, unlocking new activities that can be performed.

Activity Verification

This idea is a part of the Lighter Footprints project.

Brief explanation: One important aspect of supporting sustainable activities is that there should be an easy way for us to verify the activities of the users. While sustainable activities can span a whole range, we plan to focus our verification efforts on the following activities: using different modes of transport, participating in recycling, and reducing energy consumption.

We can develop verification methods in several ways:

  1. Develop sophisticated machine learning classifiers that work on small training data sets.
  2. Create a peer-to-peer rating system, that incentivizes participation; massive health (http://massivehealth.com/), for example, is a mobile app that incentivizes good eating habits.

Expected results:
A mobile app that provides basic verification of human activity, within a restricted set of activities.

Mentor(s): Hari Sundaram, Pavan Turaga
Knowledge Prerequisite: Java

Visualization of dynamical systems

This is similar in spirit to Bret Victor's KillMath project. We are currently developing methods to visualize dynamical systems using JavaScript and HTML5 Canvas and would like to create an animation of a dynamical system given an annotated set of data points similar to xppaut.

Mentors: Marty Anderies, Miran Bozicevic, Allen Lee

VCWEB improvements

Our experiments frequently require real-time features such as chat. We currently have a working implementation of comet for real-time chat and allowing an experimenter to control client browser state transitions from one screen to another using socket.io v6 and tornadio. This support is experimental at the moment and needs to be upgraded to socket.io v7+ and tornadio2.

Other areas of improvement include better integration with neo4j (replacing expensive relational traversal queries with graph database queries), and alternative scheduling systems to celery.

Mentor: Allen Lee, Kushal Bandi

Knowledge Prerequisite: Python/Django, JavaScript, some HTML/CSS

Virtual Commons Java Client-Server Projects

These projects represent improvements to the csidex experiment framework, the foraging experiment, or the irrigation experiment.

Project: experiment configuration, installation and deployment improvements

Brief explanation: This project is for someone interested in build, configuration management, and deployment. Configuring and installing our experiment software has a lot of room for improvement. At the moment it requires proper installation and configuration of Ant and Maven and executing commands on the command-line (with a few scripts provided for convenience). There are several areas of improvement depending on student interests:

  • Integrate with a java package installer like http://izpack.org/
  • Replace Ant+Ivy deployment with pure Maven (or perhaps buildr or sbt)
  • Design and implement a configuration tool that lets users select between different sets of experiment configurations / parameterizations. We run controlled experiments that consist of specific parameterizations and compare data gathered across these parameterizations (called "treatments").
  • Develop a web-based configuration management solution that lets users modify configuration values and download a custom software package

Mentor(s): Allen Lee

Knowledge Prerequisite: Java

Project: Provide integration with online survey software (e.g., Qualtrics)

Brief explanation: Surveys are a key component of our experiments and data analysis. We have been using paper surveys that are completed during or immediately after the experiment has concluded. We'd like to reduce data entry and get better analytics on our surveys by integrating with online survey tools such as Qualtrics (http://www.qualtrics.com).

There are several methods we can employ to relate participant experiment data with survey responses, the most straightforward is to use a combination of date/time + each participant's identifier to generate a hash.

Expected results:

  • Support adding survey URLs to the round configuration
  • Robust design and implementation for associating participant data with survey responses
  • JUnit tests covering any new code

Mentor(s): Allen Lee, Marco Janssen

Knowledge Prerequisite: Java

Project: Incorporate netty.io into the csidex network stack

Brief explanation:The csidex framework provides a interfaces for network abstraction with the most stable implementation based on blocking sockets. netty.io is a high performance network framework for Java -- integrating it into the csidex network abstraction as a configurable option selected at runtime would be beneficial for experiments that are network-intensive (e.g., the foraging experiment) for both scalability and performance reasons.

Expected results:

  • NettySocketDispatcher that uses Netty as the underlying transport mechanism but conforms to the existing csidex networking interface
  • Can be selected at run-time via appropriate parameterization of an ExperimentConfiguration (choice between traditional blocking sockets and NIO)
  • JUnit tests covering the new code

Knowledge Prerequisite: Java, NIO, multithreading, concurrency

Mentor(s): Allen Lee

Foraging Experiment Deployment

Typical workflow

On the server side:

  1. Compile / assemble jars with the appropriate configuration parameters set
  2. Deploy / copy jars and JNLP files to a location on the filesystem that is mounted on a webserver (e.g., accessible from the web).
  3. Start up an experiment server via
    java -jar -server server.jar

    or

    ant server

Start up client software on each client computer by opening a browser to the URL associated with the client.jnlp and client.jar files, e.g., http://www.example.com/foraging/client.jnlp

Start up a facilitator application by visiting http://www.example.com/foraging/facilitator.jnlp

Currently, foraging deployment requires the command-line. On Windows you'll need to use the built-in cmd shell or a more advanced shell environment like Cygwin or Windows PowerShell. On Linux or Mac OS X, just open up a terminal (Terminal.app on the Mac).

One item on our wishlist would be a graphical installer / deployment dashboard - if you'd like to help, please let us know!

Required software

  1. A webserver with the mime-type set properly for delivering Java WebStart (JNLP) files
  2. Ant
  3. Maven if you want to use the built-in Jetty webserver. This satisfies the first requirement for a webserver.
  4. Java JDK 1.6
You must have the Java Development Kit (JDK) installed, and not just the Java Runtime Environment (JRE)

Setting up a webserver

The client software is distributed using Java WebStart, and the JNLP files for the client and facilitator need to be delivered by some kind of a webserver (examples include Apache, Lighttpd, IIS, or any servlet container like Tomcat, Resin, or Jetty). The JNLP file is how Java on the client side knows where to download the client jars, where to resolve any additional jar dependencies, and which class contains the main method / entry-point to the application. If you have an existing webserver set up keep in mind that you may need to configure your webserver to properly deliver JNLP files by adding a mime-type entry associating application/x-java-jnlp-file with the jnlp file extension.

Using the built-in Maven webserver
If you'd like to skip the maintenance hassle of installing and configuring your own webserver, just use the built-in Maven Jetty webserver. You will need to install Maven, however.

Step 1 - Install the Java 1.6 JDK

You must make sure that the Java 1.6 JDK is installed properly. This means that you should have javac and java on your path. If you installed the JDK in a special location, make a note of it, because you will need it to set up Ant properly. In order to function properly, Ant needs the JAVA_HOME environment variable to point to the location where you installed Java. In Linux this might be /usr/java/latest, or /opt/jdk or wherever you decided to install the JDK. In Windows this is usually C:\Program Files\Java\jdk1.6.0_10 or something along those lines.

Step 2 - Set up Ant

Ant is currently needed to properly compile and deploy the foraging application.

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. We recommend 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.
  4. set the PATH variable to include the bin directories under JAVA_HOME and ANT_HOME so you have access to the ant executable.

Step 3 - Set up Maven (required to run the builtin Jetty webserver)

This step is optional if you have an existing webserver, but provides convenient access to a webserver if you don't. The process for installing Maven is much the same as installing Ant. The Maven downloads page has some instructions on how to do this, which involves downloading and unpacking the Maven archive somewhere and then setting the M2_HOME environment variable and PATH variable to provide access to the mvn executable. Just as in the Ant instructions you will need to make the bin directory under M2_HOME part of the PATH so that you have access to the mvn executable. For Windows installations, there is a convenience jetty.bat included that does most of the work, you just have to tell it where you installed Maven by setting M2_HOME to that location.

Step 4 - Download the foraging software

  1. Download the latest stable release of the foraging package from BitBucket
  2. Unpack the source archive and then enter the unpacked foraging directory (e.g., cd foraging-0.2)

Step 5 - Prepare the foraging software for deployment

The foraging software consists of a set of jarfiles and JNLP files. There is a server jar, a client jar, and a facilitator jar. The server jarfile needs to be executed to start the server, but the client and facilitator jars need to be deployed alongside Java WebStart (JNLP) files so that they can be run remotely. Follow these steps to install the software properly on your system:

  1. copy build.properties.example to build.properties and then edit build.properties.
    Attention
    The following properties must be set properly or deployment will not work.
    1. server.address - the server name, set this to the IP address or domain name of the machine that will be running the experiment server and hosting the webserver. Due to Java's security model, the same machine must perform both these tasks.
    2. web.dir - an absolute path on the server's filesystem that specifies where you would like to deploy the foraging jars and JNLP files. Note that it must be accessible / mounted by the webserver.
      If you are using the builtin Maven Jetty webserver, you can leave this at its default value
    3. codebase.url - the URL that maps to the above path. If you want to use foraging as the project name, you can get by with just setting the server.url and commenting this line out, since the build.xml that loads this properties file sets the codebase url to the server.url + /foraging by default.
    4. server.port - the port you want the Java experiment server (located in server.jar) to listen on - this must be a free, unused port on your system and you may need to poke a hole in your firewall to allow traffic to go through. The experiment server is the Java server process handling all the various client requests like moving around, harvesting a resource, and, in general, executing the game logic. By default it is 16001, which is usually unused (hopefully - if conflicts occur we can change this default).
  2. After editing the build.properties file and saving it, you can run ant help to see if the deployment values are sane. After you've made sure that files will be copied into the right place, execute ant deploy and everything should get copied over appropriately.

Step 6 - Deploy the foraging software

  1. Make sure you have configured your experiment properly.
  2. Copy all the configuration files (e.g., server.xml, round0.xml, round1.xml, round2.xml, ...) into src/main/resources/configuration
  3. Run ant deploy to install the software.
  4. To run the server, try executing java -server -jar server.jar
    If this command does not work, use ant server instead
  5. If you want to run the embedded Maven Jetty webserver, execute mvn jetty:run in a shell.
  6. You should now be able to run the facilitator via WebStart by going to whatever value you used for codebase.url and adding a /facilitator.jnlp to the end of it. For example, if I use http://www.example.com/foraging/ as my codebase.url then I would go to http://www.example.com/foraging/facilitator.jnlp to start the facilitator.
  7. Clients can be started by going to codebase.url directly, an index.html file that redirects to client.jnlp should be installed there. Using the same example as earlier, we can start a client by visiting http://www.example.com/foraging/

Limitations and Known Issues

At the moment the experiment server and the webserver must be resident on the same machine due to restrictions from the Java security model - it should be possible to circumvent this issue by modifying the security manager but it would require some time to research and then implement.

Foraging Experiment Configuration

There are a number of configuration parameters you can use to tweak the runtime behavior of the foraging experiment. In order to modify an experimental treatment you will have to perform the following steps:

  1. Make sure your foraging/src/main/resources/configuration directory contains the appropriate server.xml and round*.xml files. This directory must contain at minimum a server.xml file and its referenced round*.xml, e.g., round0.xml, round1.xml and round2.xml. There are samples used from experiments run at Arizona State University and Indiana University stored in foraging/src/main/resources/configuration/asu-experiments and foraging/src/main/resources/configuration/indiana-experiments. If you end up losing or corrupting the configuration files, you can always copy that set of configuration files from one of these directories to start off as a sample by executing something like cp foraging/src/main/resources/configuration/asu-experiments/* foraging/src/main/resources/configuration/.
  2. Modify the round*.xml files as needed to tweak or change any of the parameters listed below.
  3. Modify build.properties as necessary according to the Foraging Deployment instructions.
  4. Run ant deploy from the top-level foraging directory where the build.xml file resides - see Foraging Deployment for more information about deployment.
Parameter Name Allowed Values Description
chat-enabled true / false Enables/disables a communication round before the beginning of this round.
chat-duration 0 - N Duration of the communication round, in seconds.
chat-instructions text/html Rudimentary HTML or text to be displayed when the user is given the opportunity to chat.
sanction-type real-time / post-round / none The type of sanctioning allowed. When set to real-time, participants are allowed to sanction each other during the round. When set to post-round, participants may only sanction at the end of the round and are presented with a table allowing them to choose how many tokens to reduce from each other participant. Make sure to also specify the sanction-cost and sanction-penalty parameters (these default to 1:2, respectively, so it costs a participant one token to reduce another participant's tokens by 2).
practice-round true / false Enables/disables the practice round. In the practice round, participants will be able to reset the resource distribution, but do not receive any income from the tokens they collect.
clients-per-group 1 - N If set to a number > 1, participants are placed partitioned into groups consisting of N participants each. Each group has a resource distribution, and all participants in each group share that resource distribution in an open-access setting.
regrowth-rate float between 0 - 1 The regrowth rate is the multiplier / scaling factor used to adjust the probability that the current cell generates a new token. It is multiplied by the neighboring tokens ratio to generate a minimum threshold probability.
max-cell-occupancy integer between 1-N The maximum cell occupancy represents the number of participants that can occupy a given cell. If set to 1, then only one participant can occupy a cell at a time. If set to N, then N participants can all occupy the same cell.
display-group-tokens true / false Enables/disables the group token display that shows the current tokens for all members of the group at the top of the screen.
quiz true / false Enables/disables a quiz for this round, which causes the server to block until all quizzes have been submitted.
quiz-instructions text/html The instructions to be displayed for the quiz, should contain the form and input fields as well. Input fields in the form should named q1, q2, q3, ... qn so that the quiz questions can be correlated with their answers. The answers to the quiz questions should be created in a similar format, i.e., for the given example, there should also be q1, q2, q3, ... qn configuration parameters.
always-explicit true / false Enables / disables whether or not explicit mode is always on.
duration 0 - N Duration of the round, in seconds.
resource-width 0 - N The width of the resource grid.
resource-depth 0 - N The depth of the resource grid (in the 2D of the foraging experiment, this is the height).
private-property true / false Enables / disables single participant per resource grid, typically used for the practice round only.
Syndicate content