How to Configure and Launch an Experiment Through a Web-Based Interface

Note that these instructions provide an idea of the scope of Version 2.0 of jMarkets. Its capabilities are far greater, however, but alternative configurations require the experimenter to provide implementations of new payoff/bankruptcy functions. It is assumed that jMarkets is deployed and tomcat is running.

Logging in as An Experimenter

Log into jMarkets as experimenter by navigating to the site http://Your_Server:8080/jMarkets2/ExpLogin (substitute the name of the server where jMarkets is running for Your_Server). You will need to provide your email and a password to authenticate to the system.

Session Configuration

Upon logging in as an experimenter, Session Configuration page will appear. You need to enter the following:

• Name of session
• Number of periods
• Maximum number of subjects
• Number of groups Each group is a number of subjects - perhaps only one - with the same initial endowments and access to markets; this will become clear later in the configuration.
• Timeout length The length of time in seconds between periods.
• Manually advance periods Whether to manually or automatically advance periods.
• Load from file Note that there is a possibility to load a configuration from a file, in which case you do not have to enter the above. If you saved an earlier configuration, you can retrieve it by selecting the configuration file (before launching, you will be given the option to save your configuration).

Generic Period Configuration

Next you will be shown the Period Configuration page. This page allows you to specify, per period:

• The number of securities Numbers can therefore be different for different periods.
• The number of states This is a variable that you need if you use the Generic Payoff function or any of the other payoff functions; basically, each security may pay a different amount depending on a state; of course, if you don't need that, you just specify to have one state only.
• The number of ticks ("Divisions") per security If you later specify that the minimum price of a security is $1 and the maximum price is $100, and you asked for 100 ticks per security , then the tick size will be $1; it will be $2 if the minimum price is $2 and the maximum prices is $200; etc.
• The period length in seconds.
• The open delay Delay before markets open - subjects are given a warning that markets are about to open when a period starts.
• Dynamic price trigger Whether to allow mininum and maximum prices to auto-adjust based on previous period transaction prices.
• Choice of trading interfaces You can choose between two different trading GUI for a period.
• Relaxed cash constraint check Effective cash constraint check is different from the default cash validation such that values of subjects' non-cash assets are taken into consideration as well.
• Group names.
• Payoff Functions. You choose all the payoff functions you may be using (you may end up using different payoff functions for different periods and groups of subjects; a payoff function specifies the period payoff per unit of holding of a security; these functions are parametrized later on).
• Bankruptcy Functions. You also choose all the bankruptcy functions to be used (bankruptcy functions check whether you can make good on promises you make implicitly by sending in orders- see later).

Note that you must choose at least one payoff function and one bankruptcy function before entering subsequent period specific configurations.

Period Specific Configuration

Next you will be shown the configuration pages for each of the periods. Per period, you specify the following:

• Select which market mechansim to use: Call market or Continuous market.
• Indicate what group each subject belongs to.
• Specify initial cash, whether to carry cash over from one period to the next, payoff function, bankruptcy function and bankruptcy cutoff per group (if the latter is negative, a subject may make more promises than s/he is able to possibly deliver on.
• Parametrize the payoff and bankruptcy functions In the case of the payoff functions, this means specifying the end-of-period payoffs for each of the securities, as well as the exchange rate for cash (usually 1); in the case of the bankruptcy functions, this means specifying the payoffs of all the securities in all possible end-of-period states.

   Note that currently, only the first state is used for payoff calculation, however one can easily provide an implementation/extension to the server that would draw the states on the fly.
  

• Determine the names, minimum and maximum prices, and time that the market remains open, for each of the securities; also, specify what groups have access to the market (either as buyer - bid - or as seller - ask - or both), what their initial endowments are, how many units they can short-sell, whether holdings on the market pay dividend or carry over from this period to the next.

Special Notes

• You can copy specifications from earlier periods, so if the configuration remains the same in subsequent periods, you do not have to re-enter the information.
• Period and group numbering starts with 0, not 1 - a typical Java situation.

Save and Launch an Experiment

Click on "Save Session" to save the configuration locally, and click on "Validate and Launch" to start the experiment.

The experimenter will have control of the experiment via the experimenter GUI. It contains, among other things, buttons to start the experiment and stop/start a period. Note that the experiment can be started even when not all subjects have logged in, that is, even if the number of logins is less than the maximum number of subjects. Once an experiment is started, no more logins are accepted (but subjects who leave jMarkets can re-authenticate). The experimenter GUI also displays server messages,several performance metrics, and it can display a real-time graph of transaction prices upon request.

Note that when you set up a new configuration, you normally want to launch the experiment and let it run its course, making at least as many clients connect as there are groups, to see whether everything is configured properly. One way to verify whether the configuration is right is to check the total payments through the outputwriter after the mock experiment finishes. One thing to note, however, is that the mock clients need to trade AT LEAST ONCE, for otherwise the outputwriter cannot create a report.

How Subjects Participate

We usually set up a separate web site for each experiment, from which subjects can navigate to the jMarkets interface. Such a web site includes welcome pages, pages with detailed instructions, and news pages, as well as a link to jMarkets. The web site is to be viewed as an entry portal to jMarkets. Here is an example.

To participate, subjects should be asked to navigate to http://Your_Server/jMarkets/Welcome. This page asks them to Sign Up. Signup means that they have to provide email, first and last name, phone number. In addition, they are to choose a password that they can use in the experiment. Their reponses are written into the jMarkets database. Once they have signed up, they can join the experiment.

If subjects are already in the jMarkets data base, they need not Sign Up anymore in order to participate.

Typical Subject Instructions

• Demo site We usually set up a separate web site for each experiment, from which subjects can navigate to the jMarkets interface. Such a web site includes welcome pages, pages with detailed instructions, and news pages, as well as a link to jMarkets. The web site is to be viewed as an entry portal to jMarkets. Here is an example.

  Subjects should be asked to close their GUI window and the web browser after participation.
  

• History Panel The History panel shows a chart of past transaction prices for each of the securities. Like the Active Markets panel, it refreshes every period.
• Earnings History Panel The Earnings History table shows, for each period, your final holdings for each of the securities (and cash), as well as the resulting cumulative earnings.

How Trade Takes Place

Whenever you enter an offer to sell at a price below or equal to that of the best available buy order, a sale takes place. You receive the price of the buy order in cash. Whenever you enter an offer to buy at a price above or equal to that of the best available sell order, a purchase takes place. You will be charged the price of the sell order.

The system imposes strict price-time priority: buy orders at high prices will be executed first; if there are several buy orders at the same price level, the oldest orders will be executed first. Analogously, sell orders at low prices will be executed first, and if there are several sell orders at a given price level, the oldest ones will be executed first.

Restrictions On Offers

Before you send in an offer, jMarkets will check two things: a shortsale constraint and a bankruptcy constraint.

The shortsale constraint concerns whether you have anough cash or securities. If you send in an offer to buy, you need to have enough cash. When you send in an offer to sell, you need to have enough securities. We may allow you to sell securities that you don't own, however, up to a certain level. This is the short selling that we alluded to above. In that case, the payoff of the security you sell short will be subtracted from your total pay at the end of the period.

The bankruptcy constraint concerns your ability to deliver on promises that you implicitly make by trading securities. We may allow you to hold a portfolio of securities that may generate a negative payoff at the end of a period. In general, however, we will not allow you to trade to holdings with unlimited losses. The limit is referred to as bankruptcy cutoff. If the bankruptcy cutoff is set equal to zero, you will only be allowed to make trades that guarantee positive payoffs at the end of the period."