-
Notifications
You must be signed in to change notification settings - Fork 2
Terminology
This page gives definitions for some terms that are commonly used on this wiki.
A player's holdings are the amount of cash and asset that they have. Each player has two types of each holding: settled and available. This means that a player's holdings are fully described by four values: settled cash, available cash, settled assets and available assets (settled and available assets may also have multiple values if the trading environment has multiple assets). Descriptions of the differences between settled and available holdings follow.
Settled holdings: This value is the amount of cash/asset that the player actually holds. These are the 'true' holdings, and are only updated when one of the player's orders transacts. This is the value that should be used to determine payoffs at the end of the round, as it represents the loss/gain in holdings that the player made through their trades.
Available holdings: Players' available holdings are equal to their settled holdings, less the value of any outstanding orders they have on the market. This value represents the player's remaining buying power. This value is used to prevent players from short-selling. Players are only allowed to enter orders when they have enough available holdings to fulfill them.
A quick example to illustrate how available holdings work:
Imagine a player endowed with 1000 cash. They have no orders on the market, so their settled and available cash are both 1000. Now imagine they enter a buy order with price 10 and volume 15. This order has not transacted so their settled cash doesn't change, but their available cash decreases by 10 * 15 = 150. So their new cash holdings are 1000 settled cash and 850 available cash. Now, they go to enter another order with price 9 and volume 100. The total price for this order is 900. This order would be rejected even though they have enough settled holdings to pay for it. This is because their available holdings of 850 are insufficient.
This process works similarly for assets on the ask side, though only the volume of the order is considered in that case.
If your experiment has enabled short selling (by overriding Player.check_available), then available holdings become essentially meaningless. In this case, you may want to only display settled holdings to your players to reduce confusion.
The participant code (commonly shortened to "pcode") is a unique string that is assigned to each participant in your experiment. This unique code is automatically provided by oTree. You can access this code for a specific player object in Python backend with Player.participant.code. On the frontend, the participant code for the current player can be accessed from otree-redwood's otree-constants participantCode property.
oTree Markets uses these participant codes to identify players in a trading session. Every Order object is saved with an associated participant code to identify which player submitted that order.
The endowment is the amount of cash and asset given to each player at the beginning of each round. Endowments are set by overriding Player.cash_endowment and Player.asset_endowment.
A bid is an order to buy (trade cash for asset). An ask is an order to sell (trade asset for cash).
"Making" and "taking" describe each order's role in a trade. An order is a making order if it was sitting in the order book when the trade occured. An order is a taking order if it was the order that triggered the trade when it was entered. A trade can have multiple making orders, but it can only have one making order.
For example:
Players A and B enter buy orders into the market. Player C submits a sell order with a low price and enough volume to fill both player A and B's orders. This triggers a trade where player C's order is the taking order and players A and B's orders are the making orders.
The "frontend" and "backend" describe the two halves of an experiment. They're responsible for interfacing with the player and maintaining the experiment state respectively.
The frontend is the graphical interface that the player uses to interact with your experiment. This is written in HTML and Javascript. In a typical oTree experiment, your experiment's entire frontend is contained in the templates folder. A template describes the way a page should look and behave when it's shown to the player. oTree Markets also uses these templates, but with additional "static files" that allow these pages to be much more complex. For more information on the layout and design of frontends in oTree Markets, check out the Creating Market Interfaces page.
The backend is the part of the experiment that's responsible for maintaining and updating the experiment's state and delivering information to the frontend. This is written in Python. In oTree, your experiment's backend is mostly contained in models.py and pages.py. The backend is where you specify how your experiment behaves, as well as where you configure your experiment and produce output.
In standard oTree, the backend and frontend can only communicate in a limited way. The backend can pass information to the frontend when the page initially loads, and can collect information back when the player finishes with the page. There's no way for the two to communicate while the player is playing. This type of realtime communication is required for market experiments, so oTree Markets uses LEEPS' otree-redwood to add this functionality.