virtualcommons / foraging Goto Github PK

Spatially explicit, multiplayer foraging experiment for studying collective action

License: MIT License

Java 99.35% HTML 0.03% Batchfile 0.07% Shell 0.02% Python 0.51% Dockerfile 0.03%

collective-action multiplayer-game java experiments social-ecological-systems

foraging's Introduction

foraging

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.

features

Participants move and interact with a resource in a real-time 2-D grid environment.
Pluggable resource growth dynamics. The default is a parameterized density-dependent growth function but there are also "patchy" resource growth dynamics where the top half of the grid has a higher chance of regrowth than the bottom half. Arbitrary regrowth dynamics are possible by implementing a Java interface and specifying it in a configuration file.
Flexible experiment and round scoped parameterization via Java properties files used to define experimental treatments. Experiment scoped parameters apply to the entire experiment whereas round scoped parameters apply to a specific round.
Support for interactive quizzes, monitored real-time chat with options for censoring, voting, sanctioning, mini trust games in between rounds, embedded links that uniquely and anonymously identify each participant to Qualtrics surveys and limited fields of vision.
Binary and XML savefiles that store every user action (e.g., movement, harvest events, sanction events, chats) in a time ordered stream that can be converted to a variety of CSV statistics files and into QuickTime movies. Custom data analysis can be done by extending the SaveFileConverter class and analyzing the OrderedSet of user actions.

Download, configure, and deploy the software

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

Configure the software

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.

customize 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 application
add configuration files to src/main/resources/configuration, see the wiki's Configuration page for more details.

Run via docker-compose

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.

run docker-compose build --pull to build the foraging Docker image
run docker-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.
Back up your data: when you are done running an experiment make sure you back up the binary data saved in docker/data.
Convert binary data stored in 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.
Run docker-compose down or docker system prune to clean up your docker images when you're done.

Install all dependencies manually

You can also install the dependencies directly onto your system (e.g., yum, apt-get, or pacman on your favorite Linux distro) and

install and setup Java, Ant, and Maven

Run a demo

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.

publications

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.

status

If you'd like to add new features or find any bugs, please let us know.

foraging's People

Contributors

Stargazers

Watchers

Forkers

alee janderie kborash johannah minwooahn1 uia-worker

foraging's Issues

add unique participant ids to data out and surveys

chat data improvements

generate unique group numbers across the entire experiment
add sort order: date > round > group > timestamp

localize payment information

needs to be added to configuration files

update treatment configuration

3x3 treatment with no bot / nice bot / aggressive bot X low / medium / high growth rates
fix instructions w.r.t. payments
20 repeated rounds
expose movement / harvest probability in configuration

Key data variables:

number of tokens in the resource per second of each round (I guess this could be connected to biopack data, is this also data in seconds?)
number of tokens collected per round
number of tokens left in the resource at the end of the round

add communication & motives Experiment 1 configuration

create dockerized deployment

Jetty + experiment server

data processing pipeline

aggregate participant round data into summary files:

Round (1-60)
Block (1-3)
Growth rate (low, medium, high)
Bot type (nice, aggressive)
Date
ID (101-219)
Total number of tokens harvested by subject during the round
Total number of tokens harvested by bot during the round
Time (500-40000) when for the first time the number of tokens on the screen is 0 (if never, say 50000 so we can sort this)
Total number of tokens on the screen at the end of the round
Total number of movements by subject during the round
Total number of movements by bot during the round
Average distance between the avatars of bot and subject during the 40 seconds
SCL (average over the 40 seconds of the round)[this info is not in the game data, but where is it?)

possible classloader issue

Deployment at Carleton is unsuccessful, possibly due to OpenJDK vs Oracle JDK classloader issues:

# ant demo
...
compile:

prepare-demo:

demo:

check-configuration:

BUILD FAILED
/opt/foraging/build.xml:202: The following error occurred while executing this line:
/opt/foraging/build.xml:311: Did not find any configuration files in src/main/resources/configuration, please copy over an appropriate set of configuration files into src/main/resources/configuration

Total time: 3 seconds
# java -version
openjdk version "1.8.0_71"
OpenJDK Runtime Environment (build 1.8.0_71-b15)
OpenJDK 64-Bit Server VM (build 25.71-b15, mixed mode)

disable sanction guards

Currently costly sanctioning is only allowed if there are still resources on the board to prevent revenge sanctioning after the round is effectively over. Dan would like to disable this rule for the next set of treatments.

allow for custom round headers

Round -> Stage
Repeated Round Index -> Round

update bot types

rename aggressive/cooperative types to chase/nochase and add a givespace bot that values distance to the player

data conversion issue

  [java] java.lang.NullPointerException
     [java]     at edu.asu.commons.foraging.data.MovementStatisticsProcessor.process(MovementStatisticsProcessor.java:58)
     [java]     at edu.asu.commons.experiment.SaveFileProcessor$Base.process(SaveFileProcessor.java:125)
     [java]     at edu.asu.commons.experiment.SaveFileProcessor$Base.process(SaveFileProcessor.java:100)
     [java]     at edu.asu.commons.experiment.Persister.processSaveDirectory(Persister.java:241)
     [java]     at edu.asu.commons.experiment.Persister.processSaveFiles(Persister.java:215)
     [java]     at edu.asu.commons.experiment.Persister.processSaveFiles(Persister.java:220)
     [java]     at edu.asu.commons.experiment.Persister.processSaveFiles(Persister.java:220)
     [java]     at edu.asu.commons.foraging.data.ForagingSaveFileConverter.convert(ForagingSaveFileConverter.java:38)
     [java]     at edu.asu.commons.foraging.data.ForagingSaveFileConverter.main(ForagingSaveFileConverter.java:53)

unify biopac data with data aggregation pipeline

work with Simon and Philip to unify the biopac data with the summary data

ostrom lab pretest

Pretest 2 participants in a group, full vision, twice as large as private property

spontaneous generation

Private property round had spontaneous generation after all tokens appeared to be gone

strange SAXParseExceptions in round configuration

Super annoying bug related to the new FMRI config parameterization. Will reliably generate SAXParseExceptions whenever the 25 line is changed in source control. Changing it locally gets rid of the exception, but once it's committed it starts up again.

     [copy] Copying 150 files to /home/alllee/workspace/foraging/target/classes/conf                                                                                                                                                                                      [22/1833]
     [java] java.util.InvalidPropertiesFormatException: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.load(PlatformXmlPropertiesProvider.java:80)
     [java]     at java.util.Properties$XmlSupport.load(Properties.java:1201)
     [java]     at java.util.Properties.loadFromXML(Properties.java:881)
     [java]     at edu.asu.commons.conf.PropertiesConfiguration.loadProperties(PropertiesConfiguration.java:55)
     [java]     at edu.asu.commons.conf.ExperimentRoundParameters$Base.<init>(ExperimentRoundParameters.java:71)
     [java]     at edu.asu.commons.foraging.conf.RoundConfiguration.<init>(RoundConfiguration.java:146)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.createRoundConfiguration(ServerConfiguration.java:49)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.createRoundConfiguration(ServerConfiguration.java:28)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.loadParameters(ExperimentConfiguration.java:181)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.loadServerProperties(ExperimentConfiguration.java:170)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.<init>(ExperimentConfiguration.java:150)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.<init>(ExperimentConfiguration.java:137)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.<init>(ServerConfiguration.java:40)
     [java]     at edu.asu.commons.foraging.server.ForagingServer.<init>(ForagingServer.java:135)
     [java]     at edu.asu.commons.foraging.server.ForagingServer.main(ForagingServer.java:1181)
     [java] Caused by: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.
     [java]     at com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.createSAXParseException(ErrorHandlerWrapper.java:203)
     [java]     at com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.fatalError(ErrorHandlerWrapper.java:177)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:400)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:327)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLScanner.reportFatalError(XMLScanner.java:1438)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl$PrologDriver.next(XMLDocumentScannerImpl.java:999)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl.next(XMLDocumentScannerImpl.java:606)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl.scanDocument(XMLDocumentFragmentScannerImpl.java:510)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:848)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:777)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XMLParser.parse(XMLParser.java:141)
     [java]     at com.sun.org.apache.xerces.internal.parsers.DOMParser.parse(DOMParser.java:243)
     [java]     at com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderImpl.parse(DocumentBuilderImpl.java:339)
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.getLoadingDoc(PlatformXmlPropertiesProvider.java:106)
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.load(PlatformXmlPropertiesProvider.java:78)
     [java]     ... 14 more
     [java] Exception in thread "main" java.lang.IllegalArgumentException: Couldn't loadFromXML using resource: conf/ and stream: java.io.ByteArrayInputStream@a09ee92
     [java]     at edu.asu.commons.conf.PropertiesConfiguration.loadProperties(PropertiesConfiguration.java:58)
     [java]     at edu.asu.commons.conf.ExperimentRoundParameters$Base.<init>(ExperimentRoundParameters.java:71)
     [java]     at edu.asu.commons.foraging.conf.RoundConfiguration.<init>(RoundConfiguration.java:146)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.createRoundConfiguration(ServerConfiguration.java:49)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.createRoundConfiguration(ServerConfiguration.java:28)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.loadParameters(ExperimentConfiguration.java:181)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.loadServerProperties(ExperimentConfiguration.java:170)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.<init>(ExperimentConfiguration.java:150)
     [java]     at edu.asu.commons.conf.ExperimentConfiguration$Base.<init>(ExperimentConfiguration.java:137)
     [java]     at edu.asu.commons.foraging.conf.ServerConfiguration.<init>(ServerConfiguration.java:40)
     [java]     at edu.asu.commons.foraging.server.ForagingServer.<init>(ForagingServer.java:135)
     [java]     at edu.asu.commons.foraging.server.ForagingServer.main(ForagingServer.java:1181)
     [java] Caused by: java.util.InvalidPropertiesFormatException: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.load(PlatformXmlPropertiesProvider.java:80)
     [java]     at java.util.Properties$XmlSupport.load(Properties.java:1201)
     [java]     at java.util.Properties.loadFromXML(Properties.java:881)
     [java]     at edu.asu.commons.conf.PropertiesConfiguration.loadProperties(PropertiesConfiguration.java:55)
     [java]     ... 11 more
     [java] Caused by: org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.
     [java]     at com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.createSAXParseException(ErrorHandlerWrapper.java:203)
     [java]     at com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.fatalError(ErrorHandlerWrapper.java:177)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:400)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:327)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLScanner.reportFatalError(XMLScanner.java:1438)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl$PrologDriver.next(XMLDocumentScannerImpl.java:999)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentScannerImpl.next(XMLDocumentScannerImpl.java:606)
     [java]     at com.sun.org.apache.xerces.internal.impl.XMLDocumentFragmentScannerImpl.scanDocument(XMLDocumentFragmentScannerImpl.java:510)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:848)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XML11Configuration.parse(XML11Configuration.java:777)
     [java]     at com.sun.org.apache.xerces.internal.parsers.XMLParser.parse(XMLParser.java:141)
     [java]     at com.sun.org.apache.xerces.internal.parsers.DOMParser.parse(DOMParser.java:243)
     [java]     at com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderImpl.parse(DocumentBuilderImpl.java:339)
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.getLoadingDoc(PlatformXmlPropertiesProvider.java:106)
     [java]     at sun.util.xml.PlatformXmlPropertiesProvider.load(PlatformXmlPropertiesProvider.java:78)
     [java]     ... 14 more

dust off MovieCreatorProcessor

It's likely the quick time movie processor will no longer work due to missing / aging libraries. Check if it's still functional and see if there are any viable replacements to generate movies from the data files again.

java webstart deprecated

Current JNLP setup will need to be replaced with new jlink tool

display summarized instructions after dedicated chat round

After a dedicated chat round ends display summarized instructions instead of the original round instructions

ivy is pulling too many dependencies into lib

update decaro config

replace earning reductions with fines & monetary penalties rubric
make sure occupancy check is set
revert exit survey instructions change

foraging data processor: aggregated for bayesian analysis

emit a boolean that signifies whether a participant moved from a cell with a token on each movement event

split data up across pre/post resource collapse

After the last TokenCollectedEvent collapses the resource we should split up the data for pre-collapse / post-collapse:

moves
average distance to bot
SCL measures

replace SocketDispatcher

https://netty.io/

http://tterm.blogspot.com/2014/03/netty-tcp-client-with-reconnect-handling.html

update archived experiment configuration files

Need to update the treatment instructions to the new StringTemplate-based format and go through updated configuration properties for an upcoming replication test.

set up relative timestamps

Either look into communicating via parallel port:

http://www.oracle.com/technetwork/java/index-jsp-141752.html
https://docs.oracle.com/cd/E17802_01/products/products/javacomm/reference/api/javax/comm/ParallelPort.html

Or do a net time sync between computers and emit relative timestamps in the save file converter.

add install / run scripts for centos + ubuntu

Add a simple install script for centos for Carleton. The Docker build still has issues with older kernels / distributions.

install ant via package manager
set up nginx
create appropriate build.properties (possibly)

split quiz results page from instructions

For coding expedience the quiz results are shown alongside the current round instructions. Daniel would like to change this into separate screens but this would involve adding another GUI click through window for quiz results, or (better long-term) refactoring how quizzes are rendered.

Relevant code in GameWindow2D.createQuizListener

bot logic improvements

when searching for a new location, don't delay after harvest
add aggressive radius for token proximity, bot makes a beeline for closest point within the aggressive radius when enabled
reduce delays, actions should be less timed
distinguish between bot-beeline and within-player-radius behavior

improve deployment + configuration

update configuration:

rename round files to stage
remove 'a' and 'n' prefixes
create ant tasks to deploy appropriate fmri config and run test server / facilitator / client

token counts not updating in realtime

the token collected counts at the top right of the screen are only updating on full sync

update data conversion

need to update conversion scripts to take into account new variables of interest
possibly aggregate by repeated round, with a file for each repeated round and add round number to column list

add new resource regeneration type and config type

Add new ResourceDispenser.Type for non-neighboring-density-dependent (still spatially explicit / overall density dependent).

Algorithm:

raw regrowth = number of trees * regrowth rate
if raw regrowth > 1, Math.max(Math.round(raw regrowth * ratio of all open spots to total spots), 1)
if 0 < raw regrowth < 1, use uniformly distributed random number to determine (e.g, 0.9 = 90% chance for new tree, 0.8 = 80% chance)

improve in-round chat UI

in-round chat's layout isn't effective - too small in the BorderLayout.EAST

Java 8 webstart issues

Java 8 clients appear to make a separate initial request that generates an invalid stream header exception on initial socket connect - need to investigate and fix. Killing the server and restarting it pops up a notification on the client saying "Do you want to connect to x.x.x.x?". At that point if you click OK on the client, it will connect normally to the server.

Mar 21, 2015 1:09:15 PM edu.asu.commons.net.ServerSocketDispatcher processIncomingConnections
INFO: incoming connection: Socket[addr=/72.201.66.20,port=49539,localport=16001]
java.io.StreamCorruptedException: invalid stream header: 47455420
        at java.io.ObjectInputStream.readStreamHeader(ObjectInputStream.java:806)
        at java.io.ObjectInputStream.<init>(ObjectInputStream.java:299)
        at edu.asu.commons.net.SocketDispatcherWorker.<init>(SocketDispatcherWorker.java:38)
        at edu.asu.commons.net.SocketDispatcherWorker.<init>(SocketDispatcherWorker.java:42)
        at edu.asu.commons.net.ServerSocketDispatcher.processIncomingConnections(ServerSocketDispatcher.java:91)
        at edu.asu.commons.net.AbstractServerDispatcher$2.run(AbstractServerDispatcher.java:118)
Mar 21, 2015 1:09:15 PM edu.asu.commons.net.AbstractServerDispatcher$2 run
SEVERE: IO Exception while processing incoming connections: java.io.StreamCorruptedException: invalid stream header: 47455420

remove in round chat when communication is not enabled

in round chat panel is disabled but still displayed (so participants could view old chat history but not communicate further). @decarolab would like to remove it entirely so as not to distract participants

look into xhtmlrenderer for improved CSS 2.1 support

https://github.com/flyingsaucerproject/flyingsaucer

Consider replacing JEditorPane with XHtmlPanel.setDocumentFromString

fMRI UI changes

don't render number for single person / private property or 2 person games
change harvest animation: when issuing a harvest request, square behind the dot highlights to green. On successful harvest, overlay token onto the dot, then fade it out.
change token image to fill back square

look into jib for containerization

https://cloudplatform.googleblog.com/2018/07/introducing-jib-build-java-docker-images-better.html

fMRI: additional participant questions

Either use qualtrics or embed directly like the quiz

StringTemplate object references in WebStart deployment not interpolating correctly

Affects payment results and debriefing

support multi-page instructions

add ability to page through multiple sections of instructions.

single player optimizations

Single player version can be optimized to maintain the game state on the client and send it to the server in batches.

set up UoL surveys

trim whitespace on build.properties

Chris at UoL ran into an issue where trailing whitespace in server.address mucked up the config. Trim them on load:

http://stackoverflow.com/questions/38616054/ant-how-to-remove-the-leading-or-trailing-spaces-from-the-values-in-the-proper

remove time remaining label from embedded TextEntryPanel

During in-round-chat, no need for duplicate time remaining label. Also the thread of execution that updates it is not being cleaned up when we manually start a round while chat is running, creating spurious time remaining data

Participants placed in groups of 1 (Docker, demo config files)

I've been unable to get the demo configuration files and the docker setup included in the repository to work properly. Whenever we run the facilitator and connect to it with 5 clients, each client is placed in it's own harvesting group instead of all competing on the same board. The initial practice round and questions seems to work fine.

We've tried setting clients-per-group and removing that configuration value (as 5 appears to be the default group size in the code).

I know it's loading the configuration files correctly since other changes I've tried, like board size, are reflected in the clients. Any help or advice you could provide would be really appreciated. It's entirely possible I'm misunderstanding what the demo files are supposed to produce.

     [java] WARNING: An illegal reflective access operation has occurred
     [java] WARNING: Illegal reflective access by com.thoughtworks.xstream.core.util.Fields (file:/home/alllee/workspace/foraging/lib/xstream-1.4.10.jar) to field java.util.TreeMap.comparator
     [java] WARNING: Please consider reporting this to the maintainers of com.thoughtworks.xstream.core.util.Fields
     [java] WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
     [java] WARNING: All illegal access operations will be denied in a future release

x-stream/xstream#101