Some suggestions on quantecon.game_theory.normal_form_game

Documentation

• Doucumentation should be a guidance to the high level interface. It should tell people how you design it and how to use it. It should not be organized by the order of the design but not the order of API. The API list can be list seperately after the documentation, but not the main parts of it.

Names

• The names can be simpler so that it can be easiler to use. Python allows you to use same name in the different modules and packages, to overcome the name problems in procedure-oriented programming. For example, game_thoery can change to games. It will not lose information, but we can think it more Pythonic because games are objects, but theory itself is more abstract. And normal_form_game can be normal

API

• We can add the high-level interface into the top of the package or subpackage. For example, quantecon.game_theory.normal_form_game.Player can be quantecon.games.Player or even quantecon.Player. (The formal one may be better to read.)

Implements

• The input data are Python lists. It is easy to calculate the result, but not easy to understand the game itself. We can create a object like NDFrame from pandas to label the actions and players. Then we can try to make a query method like game.Alice and game['Alice'] to look at Alice's payoffs, and game.action1 or game['action1] to look at the payoffs of action1. (They are not difficult to implement by Python.)
• We can add a plot method to visualize the game. (The problem is that high-dimension is not easy to plot. Maybe some high-dimension visualization methods can be used.)

My contracts:

• Guo Zhang
• zhangguo@stu.xmu.edu.cn

Start by reading the quantecon.game_theory.normal_form_game entry point and its surrounding package documentation and API. The issue proposes several independent changes—documentation structure, renaming, a higher-level interface, labeled data, and plotting—but does not define a bounded scope or tests for completion.