The Virtual Commons

building extensible software for collective action research

Creating experiments in vcweb

The intent of the vcweb framework is to provide useful scaffolding and functionality for any kind of web-based experiment. As with most software projects however, its initial design will be tailored to its initial use cases - in our case, the forestry, fishery, and irrigation field experiments as well as a few prototype experiments designed by our other collaborating researchers. We hope to design and implement the software so that it is applicable and useful in broader contexts and welcome any feedback to help us refine and generalize the design and implementation of the framework.

Framework benefits

The vcweb framework is currently implemented in Django and brings all of Django's benefits for web application development including account management, administration pages, data management / object-relational management, and URL/view/template management.


Creating a new experiment


Creating a new experiment in vcweb is done by creating a Django app. In the Django lingo, vcweb is implemented as a project, which is a container for multiple apps. The core of the vcweb framework is implemented as an app and each experiment is also implemented as an app. It is our goal that you can use as many or as little features of the vcweb framework you want by adding only the appropriate dependencies to the core vcweb app within your own custom experiment app. The vcweb app does impose basic namespace conventions on your app. Any actionable URLs within an experiment have to fall under the /experiment-name/... namespace. We may eventually enforce a few URL hooks that need to be implemented as well (e.g., /experiment-name/admin/, /experiment-name/manage, or /experiment-name/start|stop|pause) but the rationale for implementing these should come from the bottom-up as dictated by the community.


User interfaces


The core vcweb app provides some base interfaces and look and feel CSS + Django templates that can be used if you want to get an experiment up and running quickly. You can define your URLs and views and custom templates that extend from these Django templates and customize exactly how you want your experiment interface to look, as well as defining URLs that contain mobile-friendly interfaces and the corresponding JavaScript to differentiate between which version of the web interface should be displayed - this is a simple client-side check that could for example redirect to /experiment-name/mobile/participate if you're using a mobile browser or /experiment-name/participate if you're using a regular browser.


URL management


URLs are chunked off according to a short name given to the experiment and are typically partitioned under /vcweb/experiment-name/whatever - this is completely configurable within the custom experiment app's urls.py. You have complete control over what Python code is executed given a specific URL or if you want to simply forward on directly to a Django template or static HTML page you can also do that within urls.py. See the Django view documentation for more information.


View templates


Django has its own template system which gives you limited programmatic and logical control over how your pages are rendered and variable interpolation. The basic way this works is you visit a URL configured in urls.py and it executes the Python view code registered with that specific URL. The last thing this bit of Python code associated with the URL does is define what template should be rendered as a final result, and what data should be passed to it in the form of a dictionary/map of string variable names bound to data values. These string variable names can then be accessed transparently within your Django template to perform control logic (display data conditionally, iterate over collections, etc.)


Data model


Currently the vcweb core framework offers a full data model that aims to allow for fully flexible experiment data to be collected and managed. This will be outlined more in the vcweb data model page. Basically, configuration and experiment data are stored as key-value pairs using whatever data storage engine Django is currently configured with, typically PostgreSQL or MySQL for production or SQLite for fast development.


Experiments and groups


Each experiment has one or more groups, and each group is comprised of a set of participants. Data for a given experiment is currently collected at the participant level with foreign keys to the combination of the given participant generating the data, the round in which the data was generated, the experiment the data was generated in, the data parameter and value that was generated, and the exact time the data value was stored in the table. The round is the set of configuration metadata associated with a given round in the experiment and contains references to all configuration parameters associated with that specific round including that round's sequence number. Round configuration metadata is currently designed to be unique so if you want to re-use round configuration metadata in multiple experiments we'll need to implement a way to easily copy/clone a round or full experiment's configuration and allow for later tweaking. This is an area that we may decide to refactor at some point in the future.