Sebastian Kranz, Ulm University
Author: Sebastian Kranz, Ulm University
Date: 2017-04-24
gtree is an R package with a shiny-based web GUI that allows to develop, conduct and game theoretically analyse economic experiments. The experiments run on a webserver, and can e.g. be conducted in a lecture hall, where students participate via smart phone.
There already exists two great toolboxes to develop and run economic experiments:
The classic zTree, created by Urs Fischbacher (2007). It is very flexible and has allowed to realize thousands of economic experiments in economic laboratories all around the world.
The newer oTree, created by Daniel Chen, Martin Schonger and Chris Wickens (2016). Experiments can be specified in Python with Django and are conducted via the web. Like with gtree, subjects can participate with almost any device that can browse the web.
gtree is structured with the goal in mind that typical multi-stage experiments can be created fairly easily and quickly. I would like it to be easy enough such that most economics students are able to enter such experiments as part of a seminar paper.
While not yet fully implemented, in a not-so-distant future version, there will be flexibility to specify all sorts of more complicated experiments, like real-effort games or real time auctions. Whatever you will be able to program with R & Shiny or Javascript can in principle be a part of an experiment, similar as oTree allows to employ the full flexibility of using Python & Django and Javascript.
Overall, developing and running experiments in gtree differs in some aspects, but not in too many aspects, from the two existing toolboxes.
The main contribution is that typical multi-stage experiments are entered in a format that allows direct conversion to a game tree (short a gtree!). Hence, you specify an experiment in a form that is similar to zTree or oTree but you can immediately also perform game theoretic analysis.
You can solve equilibria for standard preferences (risk-neutral money maximizer) or specify some other preferences like inequity aversion or loss aversion.
While gtree also has a rudimentary internal pure strategy SPE solver, it mainly uses Gambit (by Richard McKelvey, Andrew McLennan und Richard D., McLennan, Andrew M., and Ted Turocy, 2016) to compute the equilibria.
The possibility of easy game theoretic analysis, can e.g. be helpful for...
the analysis of the experiment when comparing observed behavior with game theoretic predictions.
the development of the experiment, e.g. to search for parameters that will yield nicely separated game theoretic predictions for different treatments.
meta studies that compare a large number of economic experiments from a game theoretic perspective
In the left panel of the gtree explorer, you see a list of all games specified in your project. To create a new game, right-click right on the "Games" folder (or any existing game) and choose the "New Game" option in the context menu:
Then a window opens that asks you to enter a name (gameId) of the game. We pick "UltimatumGame" and press Ok. Note that a gameId can contain only letters and numbers, no spaces nor underscores _. That is because underscores are used in identifiers for different game variants.
Then a tab opens in the main window that contains a tree with the initial game structure.
We first open the node "Variants, Params". We see a table in which we can specify different parameters (columns) and different variants (rows) for the game. The parameter "numPlayers" is given and by default set to 2. If your game has a different number of players, you can change it simple by clicking on the cell and changing the number.
To add or remove parameters or variants, we right click on a table cell and pick the corresponding option to insert or remove columns or rows.
We want to add a new parameter "cake" that specifies the size of the cake that can be split between the propose (player 1) and responder (player 2). So we right click on the cell "numPlayers" and pick the option "insert column on the right".
We enter the parameter name "cake" in the title row and the value of the parameter in the row for our only game variant "base"
Here, we have set the cake size to 10.
It is useful to save your game from time to time. To do so, simply press the "Save" Button.
The game files will be saved in the folder
\<projectdir>/games/\<gameId>
That folder is automatically generated, when we create a new game. You can have a look at this folder in a file explorer
The subfolders "eq","gambit" and "pages" are currently all empty:
"eq" will contain files for computed equilibria
"gambit" will contain gametree representations in Gambits "efg" format
"pages" will contain customizable markdown files that specify how the stages are shown to subjects.
The file "UltimatumGame.json" contains the game specification as a .json file. It currently looks as follows:
{"game": {
"gameId": "UltimatumGame",
"gameInfo": {
"label": "",
"tags": "",
"descr": "",
"articles": "",
"variantOf": ""
},
"varpar": [
[
"variants<U+2193> params<U+2192>",
"numPlayers",
"cake",
"descr"
],
[
"base",
"2",
"10",
"The base variant"
]
],
"stages": [
{
"name": "actionStage1",
"descr": "",
"player": "1",
"condition": "",
"observe": "",
"nature": [],
"compute": [],
"actions": [],
"special": {
"beliefs": [],
"freetext": []
}
},
{
"name": "resultsStage",
"descr": "",
"player": "[1,2]",
"condition": "",
"observe": "[payoff_1,payoff_2]",
"nature": [],
"compute": [
{
"name": "payoff_1",
"formula": "=0"
},
{
"name": "payoff_2",
"formula": "=0"
}
],
"actions": [],
"special": {
"beliefs": [],
"freetext": []
}
}
]
}}
In principle, you could specify games by manually adapting this json file. Using the gtree explorer should usually be much more convenient, however. Nevertheless, directly modifying the json file may be useful in some situations, e.g. to quickly change variable names via find and replace with a text editor.
We now go to the stages and open the automatically created stage with name "actionStage". We adapt it as follows:
We first change the stage name to "offerStage".
We then enter a short stage description in the field descr
. Stage descriptions are optional and is only used for experimenters to better understand the structure of the experiment.
We set the player
field to 1, since only player 1 will see this stage and act in it.
We keep the field condition
empty, it will be explained in later examples.
Also the field observe
is empty, since there is nothing yet to observe. Note that parameters are automatically assumed to be known to all players, i.e. players should be given that information in the instructions.
Then we add an action: we right-click on the tree element "actions" and choose the menu item "Add action" and enter the following specification:
We now add an action (right-clicking on actions
) with the following specifications:
Finally, we specify the results stage. We adapt the already given results stage:
Besides actions, we can specify moves of nature, i.e. random variables, and compute deterministic transformations of other variables in a stage. Payoffs are deterministic transformations named payoff_i
where i
is the player number. To conduct a game theoretic analysis, the payoff variables must be specified. Here we specify payoffs as following:
Let us first save the game by pressing the "Save" button.
The also press the "Check" button. This goes through your specifications and checks for errors. If everything is alright, you should get a result as follows:
To test the check function, I add a mistake in the set definition of the offer
action. You then get a message that errors have been identified:
You can the scroll down the tree to find the specific location of the error(s) with a more detailed message:
This error message is forwarded from the R evaluator, that is why we read the line Error in eval(expr, envir, enclos) :
that may look cryptic to you. However, the subsequent information object 'Cake' not found
should tip you off what is wrong:
We have specified the paramater cake
in lowercase letters, hence R does not know the variable Cake
when it tries to compute the offer set.
Note that pressing the "Check" button may not detect all errors in your game. One reason is that some errors may only be detected with relatively time consuming computations. For example, you have to make sure that a variable with the same name is not assigned twice in an experiment. This does not forbid that a variable is defined in multiple stages. Yet those stages must be run under mutually exclusive conditions. Testing whether stage conditions are mutually exclusive, may be quite time consuming in large games, however, and is therefore not performed when the check button is pressed. Some errors may pop up later when a test run is conducted. I hope that the "Check" button catches most errors, however.
We have now already entered a version of the ultimatum game that allows game theoretic analysis and to conduct the experiment. To perform the game theoretic analysis, press the button "Equilibria". A new tab with a screen like the following will open (I have to improve its design at some point):
Before solving for equilibria, we compute the game tree by pressing the "Gametree" button. We see the following summary information:
The game tree has 22 different outcomes and 12 different information sets (1 for player 1 and 11 for player 2).
More interestingly, the normal form representation of this game has 22 528 different strategy profiles. The number of strategy profiles is the product of the number of moves of all information sets. Here that product is $11 * 2^{11}$.
While 22 528 strategy profiles are still easily tractable, the number already suggests that normal form games from typicial experiments can be very big. For example, if the cake size would be 100, the normal form game would have $101*2^{101}$ different strategy profiles, which is a number with 32 digits. Non-surprisingly a main obstacle in numeric game theoretic analysis can be the curse of dimensionality: many games are just too large to analyse.
One useful and common method to reduce complexity is to split the game into subgames and solve them via backward induction. Here we can split the game into 12 subgames (each information set starts an own subgame, yeah!). Solving the game via backward induction requires to effectively only considers 33 strategy profiles. Even with a cake size of 100, the game remains very tractable via backward induction.
Unfortunately, many games with imperfect information don't have many proper subgames. One direction for future development of gtree are heuristics that allow to handle certain large games that cannot be decomposed into sufficiently small subgames.
Take a look at the game directory
\<projectdir>/games/\<gameId>
We have two new files "UltimatumGame.rg" and "UltimatumGame_base.tg" that contain different internal representations of the game. These files contain serialized R objects and should not be manually altered. More interesting is the subfolder gambit
, which contains the file UltimatumGame_base__payoff.efg
. This is a text file that contains the game tree of the base variant of our ultimatum game in the Gambit extensive-form game format.
You can open the file with Gambit to have a look at the game tree (for games with too many outcomes Gambit will most likely hang up, however). A screenshot looks as follows:
To compute all pure strategy subgame perfect equilibria of our ultimatum game, simply click the button "Solve".
If keep the default item "All pure SPE (Gambit)" in the select box "Solve for", gtree uses the Gambit command tool gambit-enumpure
to solve for all pure strategy SPE. You can also user different Gambit solvers, e.g. if you are interested in mixed strategy equilibria. A list of the Gambit solvers is found here:
http://www.gambit-project.org/gambit15/tools.html
You can also select an internal solver from gtree to solve pure strategy SPE. Yet, for most games the Gambit solver is faster and requires less memory. (Still, there are some games for which Gambit's enum-pure solve seems to be quite slow, while gtree's internal solver works considerably faster.)
As result, we first get 3 aditional lines in our summary table.
The Ultimatum game has 2 different SPE which also have different equilibrium outcomes, and took around a second to solve the game.
Another table shows the equilibrium outcomes:
I hope that gtree is in itself useful to develop, run and analyse new economic experiments, as well as, for teaching purposes where experiments are replicated and analysed in a classroom.
My original motivation for developing gtree, however, is to use it as one of several tools to build up a database that contains the data, structure and game theoretic representation of a large number of performed economic experiments. Such a database should facilitate meta studies across a large number of experiments and hopefully provide better insights into economic behavior.
I am not yet sure of the exact further steps towards such a database. Yet, some ideas are the following:
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.