Payoff Matrix Software

The Payoff Matrix is a free (open source) software written by Matthew Kidd to generate performance statistics for players, partnerships, partnership interactions (“the payoff matrix”), and partnership correlations for pair games by directly reading ACBLscore game files or USEBIO XML. The output is a set of tab delimited text files which can easily be viewed in Excel or other spreadsheet programs or further analyzed. Additional output supports embedding a visual view of the payoff matrix in HTML.

⇓ Download Now

Introduction

Ever wondered how well you or one of your partnerships is doing on average? Or perhaps you own, manage, or direct at a bridge club and are curious how well all the regular partnerships are doing in a particular game, e.g. Thursday night. ACBLscore has some functionality for generating reports but the output is usually based on masterpoints, the award system, rather than on performance metrics such as average partnership percentage in a game with a fairly consistent field strength. The Payoff Matrix software is performance oriented.

If you play in the same game long enough you’ve probably wondered how well you are doing against the other regular partnerships. Anything can happen in a two or three board round but over a year or two your partnership could end up playing dozens of boards against another regular partnership, more boards than you play total in any single session. The Payoff Matrix program computes exactly how well each partnership does against each other partnership; in other words it calculates who pays off to whom and how much. Moreover, the Payoff Matrix calculates whether each partnership is under-performing or over-performing against each other partnership based on the difference in partnership strength as judged by how well each partnership does against the entire field. Check out this visualization of the output for the La Jolla Unit game.

Version 1.0.9 adds pair-pair correlation calculations for pairs seated in the same direction within an event. See how similarly partnerships play based both on how often they achieve the same raw score on boards and how close their board by board matchpoint percentages are on average.

The Payoff Matrix software creates tab delimited text output for players, partnerships, partnership interactions, and partnership correlations. The output is detailed in the section Output Files. The software reads ACBLscore game files directly based on knowledge obtained from reverse engineering the format (see ACBLscore Game Files Decoded). This process is very fast and does not require the user to first generate any text or HTML reports in ACBLscore from each game file, a tedious step that can not be automated using a command line script given the way ACBLscore is written. On my Windows 7 era laptop, the program processes 150–200 game files per second. It is easy and quick to examine many scenarios, for example performance in different games over different time windows. The European USEBIO reporting standard is also supported.

In addition to calculating average percentages and the associated error, the Payoff Matrix software tallies related statistics, including total masterpoints, average masterpoints earned per session, successful slams, successful slam average per session. The lifetime masterpoint total of each player at any selected months can also be added to the output for players and partnerships.

License, supported platforms, and software setup

The Payoff Matrix software is released under the terms of GNU General Public License GPLv3. I would greatly appreciate additional data sets. If you find the software useful and wish to help me, zip up all your ACBLscore game files and e-mail the zip file to me at software@lajollabridge.com.

Perl runs on all major operating systems. On Windows you will need to install a Perl interpreter. ActiveState has a good free Perl distribution which you can download from their web site. Just double click on the installer (.msi) file and choose the default options. You can use either a 32-bit or 64-bit Perl distribution if you have 64-bit Windows. Strawberry Perl is a popular alternative. Perl has been included on Apple computers since Mac OS X. Many Unix and Linux distributions have Perl pre-installed.

The payoffmatrix.pl script has only been tested on Windows but should run on all platforms.

The Payoff Matrix -dy and -js switches require Date-DayOfWeek and JSON packages respectively. The -ip and -io switches require the GD package. The -ub switch requires the XML-Bare package. The JSON package is included in the ActiveState distribution and most other Perl distributions but Date-DayOfWeek and GD usually aren’t. If a package is not installed when it is automatically needed, the Payoff Matrix software will try to install it and any dependencies automatically on Windows when needed by invoking the ActiveState Perl Package Manager (PPM). This will require write access to the area where user added Perl packages are stored, typically C:\Perl\site. Or you can install the packages manually, for example via ppm install Date-DayOfWeek from the DOS command line.

On Unix, you must install the packages yourself — if you are running Unix you probably know how to do this. The following command is an example of how to install a Perl package that is available on the Comprehensive Perl Archive Network (CPAN) if you have this cpan Unix package installed.

cpan -i Data::DateOfWeek

As of version 1.0.5, payoffmatrix.pl can directly generate images of the payoff matrix, see for example the La Jolla unit game matrices. The Payoff Matrix software distribution also includes the legacy Matlab code (payoffmatrixim.m) used to generate the payoff matrix image from the tab delimited output produced by the Perl program. Matlab is fantastic but it is also quite expensive so it is good to now have the functionality rolled into the Perl code.

Send feedback and bug reports to software@lajollabridge.com

Running the Payoff Matrix Perl program

Start a DOS shell (on Windows) or the shell of your choice (on Unix / Mac). On Windows XP you can start a DOS shell via Start (menu) → Programs → Accessories → Command Prompt; or more simply via Start (menu) → Run, type cmd, and press <enter>. On Windows 7 (and probably Vista), Microsoft has gone to more trouble to hide the “scary” DOS shell and even the Run Box. See this explanation of how to get the Run Box to appear.

From the DOS or Unix shell, switch to the directory containing payoffmatrix.pl (cd = “change directory”) and then run Perl to invoke the Perl program as in the example below:

cd C:\Documents and Settings\username\My Documents   (typical for XP)
cd C:\Users\username\Documents   (typical for Win7 / Vista)

perl payoffmatrix.pl
perl -S payoffmatrix.pl   (finds payoffmatrix.pl if it is on the system path)

Note: in the last example, the -S switch which occurs before ACBLmerge.pl, is a Perl option rather than a payoffmatrix.pl option.

Invoking payoffmatrix.pl without any command arguments will display the full list of available command line options (switches).

Selecting game files

Next try the following:

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -pl player.txt -pr pair.pxt -pm payoff.txt

If you have ACBLscore installed in the standard location (C:\ACBLSCOR) and have a collection of game files in the standard game file location (C:\ACBLSCORE\GAMEFILE), this command will process all the game files and generate player, partnership, and partnership interaction (“payoff matrix”) statistics. Game files are assumed to have the standard file extensions of .ACM (morning session), .ACA (afternoon session), .ACE (evening session), .ACL (late session), .ACB (mixed, mostly seen at tournaments); other files are ignored. The case of the file extension doesn’t matter. Files with these extensions that are not actually ACBLscore games files will be ignored. Team events in games files will also be ignored.

The -d switch may be repeated if you have game files in more than one directory (folder). Individual game files may also be specified. Example:

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -d C:\ACBLSCOR\OLDGAMES C:\Users\Matt\Documents\120719.ACA -pl player.txt -pr pair.pxt -pm payoff.txt

Restricting the game files and events examined

Once you have selected the games files to consider you may restrict which ones are actually processed by using the -s, -dy, and -y switches. For example, to examine only Thursday evening games, run the following:

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -dy thu -s E -pl player.txt -pr pair.pxt -pm payoff.txt

The -dy switch can take a comma separated list of days or sessions. The -s switch can take multiple session letters (not comma separated). For example, -dy mon,tue,wed,thu,fri -s MA will consider only morning and afternoon sessions, excluding the weekends.

The -y switch restricts to a comma separated list of years, e.g. -y 2011,2012 to restrict to files from 2011 and 2012. Comma separated year restriction may include a range, e.g. -y 2009-2012 will restrict to files from 2009 to 2012. This form is more convenient than the equivalent -y 2009,2010,2011,2012.

The -s switch assumes the game files have the standard YYMMDD.AC{A,E,M,L,B} naming format. The -dy and -y switches first check the date implied by the YYMMDD.AC{A,E,M,L,B} naming format. However, game files generated for sectionals and regionals usually do not have this format. When a nonstandard format such as 21EVE.ACE is encountered, the -dy and -y switches are applied by checking each event date inside the game file.

Games file can contain multiple events. Use the -ul switch to apply a restriction based on the upper masterpoint limit of the game. Use 0 or 'open' for open events. Use 'limited' for all limited games. -ul limited is the opposite of -ul open. The following examples collect the results for all open and 0-500 masterpoint games respectively in 2012 and 2013.

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -y 2012-2013 -ul open -pl player-open.txt -pr pair-open.txt -pm payoff-open.txt

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -y 2012-2013 -ul 500 -pl player-500mp.txt -pr pair-500mp.pxt -pm payoff-500mp.txt

The -e switch may be used to select events based on their order in the game files. For example if you always setup an open game and then a limited game, -e 1 would select only the open game. The use of the -e switch is discouraged; use the -ul switch instead.

The -cb switch accepts a comma separated list of club names or club numbers and ignores games files or USEBIO files that are not from one of the clubs specified. For example, -cb "Soledad Club" or -cb 236521 will restrict to game file from the Soledad Club. Note the use of quotes because Soledad Club is two words. Club names are matched in a case insensitive manner.

The -sc switch accepts a comma separated list of ACBL sanction numbers e.g. -sc S1305111 for the May 2013 La Jolla sectional or -sc R1204034 for the April 2012 San Diego regional, and ignore games files that are not from one of the tournaments specified by the list of sanction numbers. Use 'sectionals' or 'regionals' to select all files from the corresponding tournament type, for example -sc sectionals,regionals will select all sectional and regional files.

If both the -cb and -sc switch are used, game files meeting either the club or sanction criterion are accepted, subject to the other restriction stated above.

Minimum session cuts

The player output may be restricted to players who have played at least a certain number of sessions using the -mn switch. The partnership output may be restricted to partnerships which have played at a certain number of sessions using the -ms switch. When the -ms switch is used, the payoff matrix output and pair-pair correlation output will also be limited to interactions where both partnerships have met the minimum sessions cut. The -ms switch makes it easy to cut the data down to regular partnerships.

Minimum percentage cut

The player and pair output may also be restricted to players and partnerships meeting or exceeding a set percentage. Use the -lp switch (“low percentage”) to specify this percentage.

Minimum comparisons cut

The pair-pair correlation output may be limited to correlations based on a minimum number of board comparisons. Use the -mc switch (“minimum comparisons”) to specify this minimum.

Tally of upper limits

The -ll (“list limits’) switch dumps a tally of how often each upper limit is seen in all matchpoint pair events examined to STDERR. This can be useful in selecting value(s) to supply to the -ul switch.

Note: it is quite common for some directors to setup a 299er game with an upper limit of 299 while others set it at 300. Therefore if you want to select all your 299er events, you probably want to use -ul 299,300. Similar things happen at other cutoffs. The -ll switch can help sort this out.

Slam details

The -sd (“slam details”) switch, adds three columns to the partnership output file (see below), breaking out slams counts by type.

Masterpoint totals from ACBL monthly databases

The -mp (“masterpoints”) switch adds column(s) to the player output file listing each player’s total number of masterpoints. These are the player’s total masterpoints from the monthly ACBL database. This is different from the mpsum column which only reflects the total masterpoints acquired in the events examined. The monthly ACBL masterpoint database(s) to consult may be specified by supplying a comma separated list in the format YYMM where YY is the two digit year and MM is the two digit month. For example -mp 1204,1310 will attach the masterpoint holdings as of April 2012 and October 2013 and the columns will be named “mp1204” and “mp1310” respectively. Masterpoint databases are available from May 2009 to the present with the exception of 0907, 0911, and 1202 databases.

The partnership file will contain two sets of identically named masterpoint columns for the first and second players in partnership respectively.

If the -mp switch is supplied without an argument, masterpoint databases will be attached for the starting and ending month of the time period covered by the game files examined after accounting for any filtering performed by the -y and -dy switches. If the ending month is the same as the current month and the current date is less than the 15th of the month, the database for the preceding month will be used instead. This is because the ACBL does not release each month’s masterpoint database until at least the 7th of the month and possibly as late at the 10th of the month depending on when the weekend falls. A few extra days are allowed for an archived copy to be made in the format that the Payoff Matrix software uses.

If the -mp switch is supplied without an argument and all games files examined are from a single month, only one masterpoint column is created so as to avoid redundancy.

Field strength, 70+% results, and other statistics

If the -mp switch is used, the field strength will be shown on the command line output. The field strength is the average masterpoint holding of all participants in all events examined, weighted by the number of time each participant plays. Both the arithmetic and geometric means are computed. In a geometric mean, the mean is taken in a logarithmic manner. For example, the geometric mean of two players with 10 and 1000 MP respectively, is 100 MP not 505 MP. Less experienced players drag down the geometric mean more than the arithmetic mean. A field with a high geometric mean should in principle be uniformly fairly tough and offer few gifts. The masterpoint value for each player is taken the from the latest month supplied to the -mp switch or the final month of the period examined if no arguments are supplied to the -mp switch.

The total number of unique players, unique pairs, and pair-pair interactions encountered is always displayed. If N pairs are encountered, there are at most N × (N-1) / 2 possible pair-pair interactions, though some interactions may be impossible occur because they have a player in common. The percentage shown in parentheses is the fraction of the N × (N-1) / 2 possible pair-pair interactions seen. If this number is low, the payoff matrix will be sparse and you may want to use the -ms switch to reduce the number of pairs and hence pair-pair interactions to be considered.

The number total number of times pairs have a 70+% result in a session is shown, along with the percent chance that a pair will achieve a 70+% session. Similarly the number of events where at least one pair achieves a 70+% result in the event is shown, along with the percent chance that at least one pair will do so.

Examining partnership correlations

If you want to see which partnerships play in a similar manner, try:

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -cr correlation.txt

No two partnerships seated the same direction, no matter how consistent their behavior, will achieve exactly the same results because they face different opponents on each board where they are compared. Even similarly strong pairs may not achieve similar results on boards. For example one strong pair may be excellent at bidding slams and finding slim games while another strong pair may be excellent at interfering in their opponent’s auctions and frequently wielding the axe.

Exactly how to compute partnership correlation is debatable. The Payoff Matrix uses two methods. The simplest computes how often the two partnership achieve the same raw score, e.g. +420. The second computes the mean of the absolute difference of the two percentages on each board. For example, if pair 1 achieves 50%, 90% and 40% on the first three boards and pair 2 achieves 40%, 30% and 60% on those same boards, the computation is:

( | 50 − 40 | + | 90 − 30 | + | 40 − 60 | ) / 3 = (10 + 60 + 20) / 3 = 30%

For people who like math terms, this is an L1-norm. The choice of an L1-norm as opposed to say an r2 correlation from a linear regression may seem odd. But remember that the nature of matchpoint scoring yields an approximately flat distribution of results from a “bottom” board to a “top” board. An L2-norm overly punishes disparate results, given the underlying distribution of those results.

A short bit of elementary calculus shows that the average distance between two randomly chosen points on the line segment [0 1] is 1/3. Actual matchpoint events deviate from this continuous model in two ways. When the number of comparisons is small, e.g. from a three table Howell movement,the average distance between results increases when all results on the board are distinct. For example, if the results on a board are 0%, 50%, and 100%, the average distance between results is (100% + 50% + 50%) / 3 = 67%, an extreme case. However, ties on a board pulls the average distance down. On a completely flat board, the distance between all results is 0%. On a board with two equally common results, such that there are clusters of 25% and 75% results, the average is 25% since half the time it is 50% and half the time it is zero. (Technically, it is slightly higher because a pair is never compared to itself.)

Although data sets should be examined individually, I’ve found that for decent sized game, i.e. ones that use Mitchell Movements, the mean distance between partnerships is very close to 33% as predicted by the simple continuous line model above. Pairs with significantly lower values are correlated in their behavior and pairs with significantly higher values are anti-correlated, assuming the results are based on a sufficient number of comparisons.

USEBIO support

USEBIO is a standard for tournament results used in Europe which is well documented on the English Bridge Union website. The acronym stands for Universal Standard for Exchange of Bridge Information Over XML. The documentation includes a DTD as all serious XML based standards should.

The Payoff Matrix 1.0.7 and later include USEBIO support. Include the -ub (“USEBIO”) switch to specify that your input files are in USEBIO format. As with ACBLscore game files, individual USEBIO files may be specified on the command line or entire directories of USEBIO may be processed with the -d switch. Only files with the .xml extension are examined and XML files which do not state USEBIO as the DOCTYPE are ignored.

The -y and -dy switches still apply to USEBIO files but the -s switch does not (and is ignored). The -cb switch is matched to the <CLUB_NAME> and <CLUB_ID_NUMBER> elements in the USEBIO file. The -sc switch is ignored. The -ul switch does not apply because the USEBIO format does not seem to allow for stratification or at least I have not seen any USEBIO with stratification. The irrelevance of the -ul switch implies the irrelevance of the -ll switch. All other options still apply.

Here is a simple example:

perl payoffmatrix.pl -ub -d C:\USEBIO -pl player.txt -pr pair.pxt -pm payoff.txt

This processes all USEBIO XML files in the folder C:\USEBIO.

Output Files

The Payoff Matrix Perl program generates tab delimited text for players, partnerships, and partnership-partnership interactions (the “payoff matrix”) via the -pl, -pr, and -pm command line switch respectively. The -js switch generates a JavaScript variable assignment useful for showing visual payoff matrices on a web page.

All the tab delimited output file include either ACBL player numbers or unique identifiers based on ACBL player numbers. Players who do not have an ACBL player number are assigned an artificial player number in the range 100001–999999 (six digits) using a hashing algorithm based on the player’s full name. This ensures the same artificial player numbers are assigned regardless of which game files are processed (except in the extremely rare event of a hash collision). Use the -sa (“sequential assignment’) switch if you want non-ACBL members to be assigned artificial player numbers sequentially starting at 1 as they are encountered, the method used prior to the 1.0.6 release. ‘Mentor’ is assigned the artificial number 100000. Artificial player numbers assigned via remote (wireless) scoring devices are preserved after dropping the leading pound sign, e.g. #123 → 123, except in the rare case of a collision with an artificial number already assigned.

Player output file

Player File Tab-Delimited Columns
NameDescription
pnum Player number
fname First name
lname Last name
fullname Full name
cnt Number of sessions played
pct Average percentage across all sessions
meanerr Error on the average percentage, i.e. std ⁄ sqrt(cnt)
std Standard deviation of the percentage across all sessions
pctmax Highest percentage across all sessions
mpsum Total masterpoints earned across all sessions
mpavg Average masterpoints earned per session
mpYYMM Player’s masterpoint total at a given month, e.g. “mp1204” means the masterpoint total as of April 2012. One or more columns of this form will be included if the -mp switch is used. Masterpoint columns will always be chronological. Field is empty if a player is not an ACBL member, had not joined the ACBL before the month selected, or the ACBL was notified of their death before the month selected. Inactive or lapsed members are still included.

The player file is sorted by decreasing percentage (“pct” column).

Partnership output file

Partnership File Tab-Delimited Columns
NameDescription
ix Rank from highest to lowest partnership percentage (1…N)
pnum1 Player number of first player
pnum2 Player number of second player. Always greater than pnum1.
fullname1 Full name of first player
fullname2 Full name of second player
cnt Number of sessions played by partnership
pct Average partnership percentage across all sessions
meanerr Error on the average percentage, i.e. std ⁄ sqrt(cnt)
std Standard deviation of the partnership percentage across all sessions, i.e. std ⁄ sqrt(cnt)
pctmax Highest partnership percentage across all sessions
mpsum Total masterpoints earned by each member of partnership across all sessions
mpavg Average masterpoints earned per session
slamcnt Number of slams contracts made by partnership
slamavg Average number of slams contracts made per session, i.e. slamcnt ⁄ cnt
rulecnt Number of complex rulings made involving this partnership
slamNT* Number of no-trump slam contracts made by partnership
slamMJ* Number of major suit slam contracts made by partnership
slamMN* Number of minor suit slam contracts made by partnership
mpYYMM Player’s masterpoint total at a given month, e.g. “mp1204” means the masterpoint total as of April 2012. Two sets of one or more columns of this form will be included if the -mp switch is used. The sets correspond to the first and second players in the partnership. Masterpoint columns will always be chronological within each set.

*These three fields are only present if the -sd (slam details) switch is supplied.

The partnership file is sorted by decreasing partnership percentage (“pct” column). Each partnership is only listed once with pnum1 in the partnership having the lower player number. Check both the pnum1 and pnum2 or the fullname1 and fullname2 columns to find all partnerships for a given player.

The slamcnt column list the total number of slams bid and successfully made by the partnership. This tally is based on raw scores, e.g. +980, that are valid slam scores given the vulnerability. This method is imperfect because some slams scores can be achieved via non-slam contracts. Most of the cases are crazy contracts like 2♣/* making five overtricks non-vulnerable (+980). However, few cases might occasionally occur, e.g. 4/♠ doubled vulnerable, making an overtrick (+1010) or 4/♠ redoubled vulnerable making on the nose (+920). Nevertheless it is reasonable to assume these cases will not significantly contaminate the slam total.

Presumably better partnerships have a higher slam average both due to better bidding and better card play (see analysis). Slams are not that rare. Double dummy, an amazing 13.6% of hands contain a slam (or grand slam). Half this time there is a slam for your side (both sides have a slam only 0.01% of the time). This means there are an average of 1.84 slams for your side in a 27 board session. They might not all be biddable and some may be anti-percentage. However, there are many hands where the slam fails on double dummy defense but the defense must find the right lead or defend very carefully. Strong players will test their opponents by bidding some slams that technical marginal but on which their opponents are likely to go wrong. Poisson statistics show that in a 27 board session, your side has no double dummy slams only 16% of the time, one slam 29% of the time, two slams 27% of the time, three slams 16% of the time, and four or more slams 12% of the time. Is your partnership bidding and making enough slams? Read more.

The rulecnt column tallies how often a partnership was involved in a complex director ruling. Here a complex ruling is defined as a ruling that resulted in at least one direction being assigned an Ave+, Ave, or Ave- score or resulted in a different score being assigned to each direction, a “split score”. These rulings usually involve unauthorized information (UI) or misinformation about a bidding agreement. The rulecnt column is not an assessment of blame; it may have been the other partnership at the table that caused the problem. Boards that are not played (NP), usually because there was not enough time left in the round, are not counted towards the rulecnt total. The output does not include a ruleavg column though it is readily computed.

Payoff Matrix output file

Payoff Matrix File Tab-Delimited Columns
NameDescription
ix1 Rank of first partnership in the partnership interaction. Matches ix column in partnership output file.
ix2 Rank of second partnership in the partnership interaction. Matches ix column in partnership output file.
pair_id1 Unique identifier for first partnership. Has form 'pnum1+pnum2' where pnum1 < pnum2.
pair_id2 Unique identifier for second partnership. Has form 'pnum1+pnum2' where pnum1 < pnum2.
pair_name1 Name of first partnership. Has form 'fullname1 - fullname2'
pair_name2 Name of second partnership. Has form 'fullname1 - fullname2'
cnt Number of boards where the two partnerships have met.
pct Average percentage of first partnership on all boards in this interaction. Subtract this from 100 to get the average percentage of the second partnership in this interaction.
meanerr Error on the average percentage, i.e. std ⁄ sqrt(cnt)
std Standard deviation of the percentage, i.e. std ⁄ sqrt(cnt)
disparity This is the advantage in percent that one pair holds over another. For example if pct is 55% then the interaction is 55% to 45% and disparity is 10%, the difference between 55% and 45%. The disparity column is always positive for convenient sorting by extreme results. Examine the pct column to figure out which partnership has the advantage.
relperf Relative performance of first partnership versus expectations. For example, say the first and second partnerships average 54% and 50% against the field respectively. One would expect the first pair to achieve a 54% when they meet (4% above average). If the partnership interaction is 55% then they are achieving a 5% advantage which is 1% better than expected. The relperf column reports this value. Negative values indicate under-performance.

More generally, relperf = (pctinteraction - 50) - (pctpair1 - pctpair2), where the first term is the observed advantage and the second term is the expected advantage based on the two partnership’s average percentages against the field.

The payoff matrix file is sorted in order of decreasing payoff (disparity) between the two partnerships. Each partnership interaction is only listed once. Check both the ix1 and ix2, the pair_id1 and pair_id2, or the pair_name1 and pair_name2 columns to find all interactions for a given partnership. The full partnership matrix is anti-symmetric; flip relperf and subtract pct from 100% to view things from the other partnership’s perspective.

Correlation output file

Correlation File Tab-Delimited Columns
NameDescription
ix1 Rank of first partnership in the partnership interaction. Matches ix column in partnership output file.
ix2 Rank of second partnership in the partnership interaction. Matches ix column in partnership output file.
pair_id1 Unique identifier for first partnership. Has form 'pnum1+pnum2' where pnum1 < pnum2.
pair_id2 Unique identifier for second partnership. Has form 'pnum1+pnum2' where pnum1 < pnum2.
pair_name1 Name of first partnership. Has form 'fullname1 - fullname2'
pair_name2 Name of second partnership. Has form 'fullname1 - fullname2'
cnt Number of boards where the two partnerships have sat the same direction within the same event (not necessarily the same section of the event).
meanpctdiff Average difference of the absolute value of the matchpoint percentage difference achieved by the two pairs on each board
pctsame Percent of time the two pairs achieve the same score on a board, e.g. both pairs achieve +420. This determination is based solely on the raw score rather than the contract as the latter is not recorded in the ACBLscore game files.
pct1 Average percentage across all events for the first partnership (same as pct field in Partnership File above).
pct2 Average percentage across all events for the second partnership (same as pct field in Partnership File above).

The correlation file is sorted in order of increasing meanpctdiff, such that the most correlated partnerships are shown first. Each partnership correlation is only listed once. Check both the ix1 and ix2, the pair_id1 and pair_id2, or the pair_name1 and pair_name2 columns to find all correlations for a given partnership. The full partnership correlation matrix is symmetric.

Presenting the Payoff Matrix in HTML

The Payoff Matrix software can generate output files to enable a sophisticated visual display of the payoff matrix in HTML. The output file include both images and also JavaScript code containing payoff matrix data for a hovering tooltip over the payoff images.

Generating images

The regular and under/overperform payoff matrix images are generated with the -ip (“image payoff”) and -io (“image over/under”) switches respectively. Here is a complex example used to generate the La Jolla Unit results.

perl payoffmatrix.pl -d C:\ACBLSCOR\GAMEFILE -ms 10 -y 2012-2013 -ul open -pl U526-2012-2013-players.txt -pr U526-2012-2013-min-10-pairs.txt -pm U526-2012-2013-min-10-payoff-matrix.txt -mp 1201,1311 -px 16 -lc 10 -ip U526-2012-2013-min-10-sessions-16px-pm.png -io U526-2012-2013-min-10-sessions-16px-ou.png -js U526-2012-2013-min-10-payoff-matrix.js

The part of the command line in blue generates the output files for HTML display. In this example, the -px (“pixel’) switch is specified to indicate that each element of the payoff matrix will be shown as a 16 × 16 pixel square in the output images. If the -px switch is not used, the size of each square will be adjusted so as to keep the total image size around 600 × 600 pixels so long as each square is not less than 6 × 6 pixels in order to provide some room for the pair names along each axis. It is best to use the -ms (“minimum sessions”) switch to reduce the number of partnerships; otherwise the matrix will be very large and unappealingly sparse. In this example, the minimum session cut is set at 10 and the output images filenames reflect this minimum and the pixel size; this isn’t necessary but it does help keep track of the files when many closely related cases are generated.

Images are always written in PNG format regardless of the file extension given to the filename. If the file extension is not .png (case insensitive), a PNG file is still created but a warning is printed to STDERR.

The -lc (“low confidence’) switch defines the minimum number of boards required to avoid flagging a matrix element with a pink X to indicate the statistics are based on a small number of boards. If the -lc switch is not used, no flagging will be done.

The dynamic range of the blue to yellow color map may be adjusted with the -dp (“dynamic (range) payoff”) and -do (“dynamic (range) over/underperform”) switches respectively. Both values default to 30. This means the payoff matrix squares range from 20% (solid blue) to 80% (solid yellow) and the over/underperform matrix squares range from -30% (solid blue) to 30% (solid yellow). Lowering the dynamic range brings out more details near the center values of 50% and 0% respectively but clips more data at the extremities.

The -js switch generates the JavaScript file explained in the next section.

JavaScript output file

The JavaScript output file assigns the pair and payoff matrix data to an element of an associative array where the key is the based on the output filename. For example, if the output filename is U526-2012-2013-min-10.js the output will look like the following:

payoffMatrix["U526-2012-2013-min-10"] = {"pairs" : {…}, "pm": {…}};

Note: As a convenience (or quirky inconvenience depending on your point of view), a trailing “-payoff-matrix” immediately before the file extension, will be stripped in generating the key for the associative array. That is how U526-2012-2013-min-10-payoff-matrix.js becomes U526-2012-2013-min-10. The file path and file extension are always stripped.

Yes, technically JavaScript does not have true associative arrays like Perl. This code actually defines a method on an existing array defined in payoffmatrix.js. There are some theoretical drawbacks to this approach but it is good enough for my purposes. The idea is to be able to cleanly keep each dataset in a separate file which can then be loaded into a webpage along with the payoffmatrix.js and payoffmatrix.css files.

Putting it all together

The HTML snippet below demonstrates how to put it all together.

<head>

<link type="text/css" rel="stylesheet" href="/css/payoffmatrix.css">
<script type="text/javascript" src="/js/payoffmatrix.js"></script>

<!-- Datasets for each payoff matrix (load after payoffmatrix.js) -->
<script type="text/javascript" src="/Analysis/Payoff-Matrix/U526-2012-2013-min-10-payoff-matrix.js"></script>

</head>

Then displaying a Payoff Matrix in HTML is as simple as:

<div class="pm-div" width: height: 850px; 1000px;">

<img src="/Analysis/Payoff-Matrix/U526-2012-2013-min-10-sessions-16px-pm.png" width="592" height="592" alt="payoff matrix" class="pm-img" style="left: 200px; top: 250px;" id="U526-2012-2013-min-10-pp" onload="pm_addPairNames(this, 'U526-2012-2013-min-10', 'pm-x-name', 'pm-y-name');" onmouseover="pm_tooltip.show(this, 'U526-2012-2013-min-10');" onmousemove="pm_tooltip.move(event, this, 'U526-2012-2013-min-10', 'pp', 1);" onmouseout="pm_tooltip.hide();">

</div>

where the payoff matrix dataset referenced in blue matches the id of one loaded in the JavaScript data file generated by the -js switch. Note: depending on the size of the payoff matrix image and the length of the pair names, it may be necessary to adjust the values in green above. The first purple parameter, pp indicates that the tooltip should emphasize the interaction percentage ("partnership percentage"). A value of 'ou' indicates that the tooltip should emphasize the over/under-performance. Choose the option that matches the data shown on the image used. The second purple parameter is the width of the border in pixels around the image. Here it is 1 as defined by the pm-img class.

Version history

Older versions the Payoff Matrix Program can be downloaded by clicking on the download arrow next to the version. The latest version is also always available from the Download Now button at the top of the page.

VersionDateMajor Changes
⇓ 1.0.1008-Dec-2015
  • Update player name if a new name for same player number is encountered in an event with a later event date, e.g. result of marriage, divorce, or a typo when name is manually entered into ACBLscore.
  • Replace artificial player IDs with ACBL player number if ACBL player number is found for a player with the same name as the one assigned an artificial ID.
⇓ 1.0.925-Nov-2015
  • Added pair-pair correlation calculation (-cr switch).
⇓ 1.0.801-May-2014
  • Added field strength calculation when -mp switch is used. Result is shown on the command line window.
  • Statistics for pairs with a 70+% result, and events where at least one pair has a 70+% results are shown on the command line window.
⇓ 1.0.711-Apr-2014
  • Added initial support for USEBIO XML (used in Europe). Feature requested by Neville Richards from Wales.
  • Added -cb and -sc switches to filter by club names, club numbers, ACBL sanction numbers, or by all regionals and/or all sectionals.
  • Filtering based on year (-y), day of week (-dy) is now also applied to files without the standard YYMMDD.{A,E,M,L} game files naming scheme used for club game files. This means the cuts are supported for sectional and regional game files which usually have names like 21EVE.ACE, and for other modified naming schemes.
  • The -ul switch can now take the value limited to select all limited events.
⇓ 1.0.606-Mar-2014
  • Tightened checking of sections so that only Pairs sections with Matchpoint scoring are processed. Fixes a divide by zero crash reported when trying to process an IMP Pairs section and will prevent other unpredictable behavior (issue reported by Bill Clough).
  • Added more reporting for how many game files were not processed due to cuts imposed by the user via the -y, -dy, -s, and -ul switches and also how many sections were not processed because they were not Matchpoint Pairs sections.
  • Changed algorithm for assigning artificial player numbers to non-ACBL members. Also properly handle artificial player number assigned via remote (wireless) scoring devices, i.e. #123 in ACBLscore game files (Issue reported by Bill Clough).
⇓ 1.0.525-Nov-2013
  • Added ability to generate payoff matrix images from the Perl script, rendering the Matlab code unnecessary (uses GD Perl package).
  • Fixed definition of relperf as it appears in both the pair-pair interaction tab delimited text file (generated by the -pm switch) and in the JavaScript output (generated by the -js switch). Previous definition was seriously flawed.
  • Added payoffmatrix.js and payoffmatrix.css files to the distribution.
  • Fixed broken -dy switch (regression in 1.0.2 when automatic package downloading was added).
  • Slightly improved argument checking.
⇓ 1.0.420-Nov-2013
  • Added -mp switch. It attaches columns to the player and partnership output file listing the player’s masterpoint totals at the months, i.e. year and month, requested.
  • Eliminated some Perl warnings which did not affect program output.
⇓ 1.0.308-Nov-2013
  • Added -ll switch. It dumps a tally of how often each upper limit is seen in all the pair events examined. This is useful for selecting values for the -ul switch.
  • Added -sd switch. It adds columns to partnership output breaking slam counts down by no-trump, major suit, and minor suit slams.
  • Slam tallying now accounts for the vulnerability on the board. This significantly reduces the already rare chance of false positives from infrequent non-slam contracts.
⇓ 1.0.227-Oct-2013
  • Added -mn switch to limit list of players to those playing a minimum number of sessions (feature requested by Charles Babcock).
  • Added -lp switch to limit list of players and partnerships to those whose average is meets or exceed a set number (feature requested by Charles Babcock).
  • Code now downloads Perl packages as needed using PPM when Perl is run on Windows using the ActiveState build.
  • Added exit codes for clear program termination status.
⇓ 1.0.124-Oct-2013
  • Added pctmax column to player and partnership output files (feature requested by Charles Babcock).
⇓ 1.0.003-Oct-2013 Original release.

Files included in the software distribution

The current program archive contains the files listed in the table below.

FilenamePurpose
payoffmatrix.plPerl program to generate tab delimited text files
payoffmatrixim.mMatlab program to generate payoff matrix images from tab delimited files produced by payoffmatrix.pl. Not needed from version 1.0.5 onward but included for reference.
Changelog.txtRevision history
payoffmatrix.jsJavaScript file for displaying payoff matrix images in HTML with pairs on each axis and with the tooltip.
payoffmatrix.cssCSS file for displaying payoff matrix images in HTML with pairs on each axis and with the tooltip.

Command Line Help

Command line arguments inside [ ] are optional; for example [-pl plfname] means the -pl switch is optional but that if it is specified, a filename must also be specified.

To do anything useful, some ACBLscore game files or USEBIO XML must be specified either individually, or more commonly by specifying a directory of ACBLscore game files, e.g. -d C:\ACBLSCOR\GAMEFILE. The -d switch may be repeated to include multiple directories of ACBLscore game files.

  Usage: $bname [fname...] [-d dirname] [-pl plfname] [-pr prfname]
         [-pm pmfname] [-cr crfname] [-js jsfname] [-s list] [-dy list]
         [-y list] [-cb list] [-sc list] [-ul list] [-e list] [-mp list]
         [-mn #] [-ms #] [-mc #] [-lp #] [-ll] [-ip ipfname] [-io iofname]
         [-dp #] [-do #] [-px #] [-lc #] [-v #] [-vr] [-sa] [-ub]

  fname  : Input filename(s), i.e. ACBLscore game files or USEBIO files
  dname  : Directory name (processes all games files in the directory)
           The -d option may be repeated to specify multiple directories.

  Output files
    -pl : List of players and their statistics
    -pr : List of partnerships and their statistics
    -pm : Payoff matrix data (partnership-partnership interaction)
    -cr : Correlation matrix data (partnership-partnership correlations)
    -js : JavaScript variable assignment useful for HTML matrix display
    -ip : Payoff matrix image (regular presentation)
    -io : Payoff matrix image (over/underperform presentation)
        
  General options
    -v  : Set verbosity level. 0 -> Quiet mode (minimize command line output)
          2 -> Detailed. Default is 1. Meaningful up to 4.
    -vr : Show version
    -sd : Dump full slam details in pair file
    -ll : Dump a list of all upper limits encountered and how many events
          have each upper limit.
    -mp : Comma separated list of monthly masterpoint total columns to attach
          to player and partnerships file output. Format is YYMM, e.g. use
          1102,1310 to attach the Feb 2011 and Oct 2013 masterpoint holdings.
          If no list is supplied, masterpoint totals from start and end of
          time period covered by the game files will be attached.
    -sa : Use old sequential assignment (1..N) instead of new hash based
          method when assigning artificial player numbers.
                                  
  Game file filtering options
    -s  : List of sessions (M = morning, A = afternoon, E = evening, L = late)
          to examine, e.g. AE. If not specified, all sessions are examined.
    -dy : Comma separated list of days to examine: mon, tue, wed, thu,
          fri, sat, sun. If not specified, all days are examined.
    -y  : Comma separated list of years to examine. Ranges may also be
          specified, e.g. 2007-2009,2011
    -cb : Comma separated list of club numbers or club names (case insensitive)
          to examine.
    -sc : Comma separated list of tournaments to examine based on their
          sanction numbers, e.g. S1305111. The special designators, 
          'sectionals' and 'regionals' mean all sectionals and all regionals
          respectively. If neither -cb or -sc is specified, no filtering is
          done.
                    
  Event filtering options
    -ul : Comma separated list of masterpoint upper limits for events to
          examine. Use 'open' or 0 for events with no upper limit. Use
          'limited' to examine all limited events.   
    -e  : Comma separated list of event indices to examine. For example,
          if game files always have an open event and may optionally have
          a limited event as the second event then -e 1 will limit the
          examination to the open event. -ul is usually the better switch.
          
  Result filtering options
    -mn : Minimum number of sessions that a player must play in to be
          reported in the player list (-pl) output.
    -ms : Minimum number of sessions that a pair must play in to be reported
          in partnership list (-pr), payoff matrix (-pm), and pair-pair
          correlation (-cr) output.
    -mc : Minimum number of comparisons between two partnerships to be reported
          in the pair-pair correlation output.
    -lp : Lowest player/partnership percentage to include in the player list
          (-pl) and partnership list (-pr) output.
          
  Image generation options
    -px : Number of pixels in each direction for each cell
    -dp : Dynamic range for regular payoff matrix color map
    -do : Dynamic range for the over/underperform payoff matrix color map
          (defaults are both 30 => 20 to 80% and -30 to 30% respectively)
    -lc : Minimum boards in a pair-pair interaction to avoid red-X flagging

  Computes the partnership payoff matrix by directly scanning ACBLscore game
  files or USEBIO XML files. Also computes player and partnership statistics
  and pair-pair correlation statistics. Can generate images of the payoff
  matrix and JavaScript support code for HTML presentation.

  Online documentation is located at:
  http://www.lajollabridge.com/Software/Payoff-Matrix/Payoff-Matrix-About.htm