Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Table of Contents
This page discusses and provides examples of ConG configuration files. We will present a number of example config files, and explain in more detail parameter specifications that define the game subjects play.
What is a Configuration File? - An experiment with ConG is started when the experimenter loads a .csv configuration file into the ConG Control.jar program. Configuration files are period-by-period specifications of attributes of the experiment to be run. This file fully characterizes the experiment session.
The config is a flat csv-formatted file - easily editable via any spreadsheet software - with a top-row header defining the fields to be defined in the experiment. The rows below the header are period by period definitions of the experiment session subjects interact with. These period by period definitions allow for the possibility of treatment variations or subject block randomization between periods.
Time Between Periods. The Control.jar program allows experimenters to "Autostart" periods. When Autostart is selected (via a check in a checkbox), as one period ends the next period will automatically start after a ten second delay. With Autostart unchecked, each period must be manually started by the experimenter via the Control.jar program. (See linked screen capture of the Control.jar interface, the highlighted section is where experimenters may start, stop, pause and autostart periods.)
What if I didn't include a column? If a column is not included in a configuration file, then ConG will refer to that field's default setting. Defaults vary by field, but if an experimenter is particularly concerned with the value of a field, they should define it in the configuration file. Examples:
- The "name" column of a configuration file is useful for data analysis, but has no effect on an experiment session, thus the column may be omitted from a configuration file without issue. However, the experiment Ticks file (the record of subject actions) will include a "name" column, and values in this column will all be the default for "name", an empty string. - The default for matchType is self. That is, should a configuration file fail to include a column for "matchType", then ConG will default this value to "self". Should an experimenter want to ensure the period is a two population game (matchType=pair) they should include the matchType column. - With the "matrix2x2" payoff function, the configuration file must also include the additional payoff parameters of min, max, Aa, Ab and so forth (see below). However, if the matrix2x2 payoff function is not used, then the configuration file need not include these additional columns associated with the matrix2x2 payoff function.
Immediately below is an example of a full .CSV config file for the Public Goods game in an html table format. We have painstakingly documented this game on another page. Download the full .CSV file here.
Note the top row Header (emboldened) below.
Each row of the configuration file is used to define a single period of the larger experiment session. The first column of every configuration file is the Period column, as highlighted below, and it specifies the number of periods that will occur in the game.
Although the periods below are labeled sequentially, "1", "2", "3"...."6", this field can be any string the experimenter wishes (so long as it does not include a comma - a comma may interfere with reading the .csv file). In the experiment output Ticks file, the period will be labeled as it is labeled config file. --For example, the config file excerpt below will have period labels of "1", "2", "3" and so forth, but other acceptable period name may be "Practice 1", "Practice 2", "Paid 1", and so forth.
ConG will run periods in the order in which they appear in the configuration file, going down. The first non-Header row will be the first period, the line below that will be the second period, and so forth.
- Note that the period label MAY NOT CONTAIN A COMMA. Commas will interfere with how the .csv file is read into ConG and spreadsheet software.
If the paid Boolean is set to TRUE, then that period's earning will be added to the payoffs table produced at the end of the experiment. If this field is set to FALSE, then points earned in this period will not be added to the subject payoffs table.
Unpaid periods are typically run the first few periods, as practice rounds, or at the end of a session, as pilot experiments.
In each period the configuration file specifies the length of the period and whether or not the period is to be run in discrete or continuous time (and in the discrete time specification, the number of subperiods the period will be divided into). For a more detailed discussion of discrete, and continuous time type experiments visit [wiki:CongVsDiscrete]
- The length column specifies the number of seconds in each individual period. - The subperiods column specifies the number of subperiods in the period. When the subperiods column entry is "0" for a given period this indicates that that period will be run in continuous time (many subperiods run during the length of the period). When the subperiods column entry is "1" this will signal ConG to run that period as a one-shot game (one subperiod lasting the entire length of the period). For values above "1", ConG will divide the length of the period into the number of desired subperiods.
Below is an html table representation of an example configuration file. - Periods 1 and 2 are run as one-shot games, where each period lasts 300 seconds or 5 minutes. - Periods 3 and 4 are discrete time games. Each of these two periods are 300 seconds in length and are divided into 10 subperiods. Each subperiod lasts 30 seconds (300 second period lengths divided by 10 subperiods) - Periods 5 and 6 are continuous time periods, (note the length field is set to 0, this sets the period to be run in continuous time).
|period||paid||length||subperiods||groupSize||matchType||...more config file fields ...|
|1||TRUE||300||1||3||self||...more config file fields ...|
|2||TRUE||300||1||3||self||...more config file fields ...|
|3||TRUE||300||10||3||self||...more config file fields ...|
|4||TRUE||300||10||3||self||...more config file fields ...|
|5||TRUE||300||0||3||self||...more config file fields ...|
|6||TRUE||300||0||3||self||...more config file fields ...|
Modifications to the configuration file allow for ConG to support arbitrary symmetric 2x2 matrix games and aggregative games (e.g. Public Goods). Aggregative games - in which individual payoffs are, in part, a function of own actions and the sum of counterpart player actions – allow for a number of payoff function types, including Public Goods and some Cournot game variations.
First we will look at an example of a configuration file from a sample symmetric 2x2 matrix game. For more information about symmetric matrix 2x2 games in ConG checkout this page.
The payoffFunction column specifies the type of payoff function used. There are two possible options: matrix2x2 and sum (additional payoff functions are possible with ConG extensibility). Under matrix2x2, ConG will run a symmetric 2x2 matrix game. (Note that the following columns must follow the payoff function column - failure to do this will likely result in an error.) - min and max specify the maximum and minimum values on the Y-axis of the payoff flow chart (see matrix2x2 for examples of the payoff flow chart with min of 0 and max of 17). - Since the game is symmetric, the column Aa refers to both players' payoffs when both players select strategy A. - Ab refers to the payoff when a player selects strategy A and his paired opponent selects B. - Ba refers to the payoff when a player selects strategy B and his paired opponent selects A. - Bb refers to the payoff when both players select strategy B.
|period||paid||length||subperiods||groupSize||matchType||payoffFunction||min||max||Aa||Ab||Ba||Bb||...more config file fields ...|
|1||TRUE||300||0||3||self||matrix2x2||0||17||10||0||18||4||...more config file fields ...|
|2||TRUE||300||10||3||self||matrix2x2||0||17||10||0||18||4||...more config file fields ...|
|3||TRUE||300||0||3||self||matrix2x2||0||17||10||0||18||4||...more config file fields ...|
Next we give an example of a configuration file for the Public Goods game. For a more complete discussion of the Public Goods game, and "sum" type payoff function games, go to their respective pages: Sum Payoff Function, and Public Goods Game.
- For both Public Goods games and Cournot type games the payoffFunction column has all entries as "sum". - With sum games, there is the additional field require, the type column. There are currently two sum game types: "public_goods" and "proportional". Each corresponds to the two separate game types, Public Goods and Cournot.
The fields below define a public goods game: - A refers to a parameter that defines the voluntary contribution multiplier (see functional form for more info on this parameter). This parameter may be varied each period. - smin and smax define the sMin and sMax parameters for the Public Goods game payoff function, and can be changed with each period. These parameters take on integer values as in the example below. - min and max refer to the minimum and maximum amount a player can contribute to the public pool.
The payoff function for "sum", "public_goods" takes the following form:
|1||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||... more config file fields ...|
|2||TRUE||300||10||3||self||sum||public_goods||pf||1.2||0||25||0||60||...more config file fields ...|
|3||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||...more config file fields ...|
|4||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||...more config file fields ...|
|5||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||...more config file fields ...|
|6||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||...more config file fields ...|
ConG has a variety of selectors, the interface with which players use to select strategies (e.g. radio buttons, slider, heatmap slider), which are specified by the configuration file. Certain games are only compatible with certain selectors (see this page for more details).
The Bubbles strategy selector has subjects select their strategies by clicking along the x-axis, with the y-axis corresponding to flow payoffs. See the [wiki:Bubbles]. In the configuration file excerpt, note under the selector column all entries are set to "bubbles".
|period||paid||length||subperiods||groupSize||matchType||payoffFunction||type||name||A||smin||smax||min||max||mixed||selector||...more config file fields ...|
|1||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
|2||TRUE||300||10||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
|3||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
|4||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
|5||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
|6||TRUE||300||0||3||self||sum||public_goods||pf||1.2||0||25||0||60||TRUE||bubbles||...more config file fields ...|
Below is an example of the pure selector. This is used in a Prisoner's Dilemma game, producing the radio-button selector. Notice that the mixed column entries are left blank for the "pure" type strategy selector.
For the "heatmap2d" selector there are more columns that specify the strategy selector.
- Setting the mixed column to "TRUE" will allow for mixed strategies (combinations of say strategy A and B). Leaving mixed column entries blank will not allow for mixed strategy selections. - The matrixDisplay column has three possible entries: "!HeatmapSingle", "!HeatmapBoth", and "corners". For more information on the differences between these selectors visit the [wiki:heatmap2d]. - The showHeatmapLegend section has two options: True and False, which makes visible or hidden the heatmap legend. The heatmap legend is the vertical scale color legend next to the flow payoff chart that links payoff values to colors (see screenshot).
Below is an example of a period from a configuration file, with the "!HeatmapSingle" selector chosen.
Experimenters have many grouping and matching options with ConG. For a review, refer to the Grouping and Matching page.
ConG offers the ability for subjects to chat with other players in their group during an experiment. For screen shots of the free-form and canned-response chat windows, refer to the ConG Communications page.
- The chatroom column determines whether or not a chatroom will be present in a given period. Setting chatroom to TRUE enables the chatroom, and setting chatroom to FALSE disables the chatroom. With chatroom=TRUE, during that period a second window will open on subject terminals, allowing subjects to type messages seen by other players in their group. - With freeChat. With "freeChat" set to TRUE, subjects are able to type any string they choose into the chat window. With freeChat set to FALSE, subjects are limited to specific canned responses (see screenshot of canned messages available). Please note that the canned-response chat window was specifically designed for the bubbles selector display, and probably will not make sense for use with other selectors. Thus we suggest that if communication is needed during an experiment, experimenters use the freeChat=TRUE setting. - The objectiveColors column is a chatroom option that, again, only applies to the bubbles selector. It can be set to either TRUE or FALSE. When the objectiveColors is set to TRUE, this means that the players are a consistent color to one another. If one player appears GREEN on their own display, then they appear GREEN to everyone else in the game they are playing. If objectiveColors is set to FALSE, then although one's "bubble" appears GREEN on their terminal, it might not appear GREEN on other subjects' terminals. Note also that colors do not necessarily carry over from one period to the next. For the Chat feature to have an objective use to players, this field must be set to TRUE.
Below is an example of a configuration file for a Public Goods type game with two periods that have different chat options.
For screenshots of the chatroom options please visit the public goods game page