Some suggestions on quantecon.game_theory.normal_form_game

[Guo-Zhang]

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

[jstac]

@Guo-Zhang Thanks for your thoughts. These parts of the library were written by very smart people who I respect a lot. I will leave it to them to see if they want to accept any of your suggestions.

For these kinds of applications, the thing that we value the most is well written code that implements algorithms, or pull requests that improve those algorithms.

[Guo-Zhang]

Thanks for your reply. I am very impressed by the algorithms. However, the implement is only part of the open source program. Whether it is easy to use depends on not only the implements, but also the friendly interfaces and tutorials. For open source programs, people will always care whether it is easy to use, otherwise they will change to another packages or write codes by themselves. We write open source programs because we want others to use them. A good interface can also attract people to contribute them. What's more, good APIs and good organizations of the pacakges help people to find where they can contribute. Therefore, in my opinion, interfaces and documentations are more important than algorithms, especially in the early development of the packages.

[cc7768]

Hi @Guo-Zhang. This is great -- Thanks for giving us some feedback. We are always looking for constructive feedback from people using the code. I think what @jstac probably had in mind in his response, was that while ideas/suggestions are useful, what is often more useful is implementing the ideas/suggestions and letting them go through the pull request process. Having concrete changes in the code/documentation allows us to capture the vision of the comments better and then have a discussion about whether we think those changes are improvements.

It seems like a lot of what you have in mind for the documentation could be captured by moving some of the documentation for normal_form_game to the top level of the game theory documentation instead of being hidden under normal_form_game. That seems like a sensible change.

As for the names, I think you are right that games doesn't lose any information from game_theory (and as a bonus it would better mimic the corresponding Julia library), but I disagree that normal doesn't lose any information from normal_form_game (there are many different things that the word normal can refer to). I believe at one point (though I can't find it anywhere) we had some discussion about how to name some of the things in the game_theory code and, if I remember correctly, that @oyamad made very convincing arguments in favor of being explicit with the naming. In my opinion, some of these names help me associate it better with the relevant material.

I think the API suggestion you have in mind is already implemented. At least if I run import quantecon as qe then qe.game_theory.Player works. Our current approach breaks tools into subpackages, so I think we'd like to keep the game theory code separate from the core quantecon code -- Similar in idea to things like scipy.interpolate, scipy.linalg, etc...

I'm having difficulty picturing what you have in mind for the suggestion related to using NDFrame instead of a list of players. I am hesitant to move away from using lists, but would be open to being convinced otherwise. As far as adding plotting methods, I would be interested to see what you had in mind (a demonstrative notebook could be helpful), but, just as an fyi, we are in the process of removing matplotlib as a dependency.

Of course I am always open to changing my mind if people disagree. @oyamad, @shizejin, and @mmcky will also have insightful comments to this discussion.

[oyamad]

@Guo-Zhang Thanks for the feedback.

For the API, if you do something like

import quantecon.game_theory as gt

it will be even shorter as gt.Player.

Adding labels to the actions, as in MarkovChain/DiGraph and DiscreteDP, will be helpful.

I too am curious about your plot method to visualize a game. A demonstrating notebook would be helpful.

[Guo-Zhang]

@cc7768 Thanks very much. I am going to explain more about my ideas.
First, I agree that normal lose information, but games.normal can show that it is a normal form game. Python allows prob.normal and games.normal in order to make the names shorter and clearer, and avoid problems by namespace. So I think it's better to use short names to make it more Pythonic. Long name is something like R or C.
As you have seen, people use linalg instead of linear_algebra so that the name is shorter. It is useful when you have a lot of small calculation with command line instead of .py files. I agreed the ideas about subpackage like scipy.
For the input payoffs, the best way is to allow different data structures including lists, tuples, dicts, numpy.array, pandas.DataFrame, etc. It will need a good design with low-level interfaces.
NDFrame is a data structure created by pandas. You can think it as a numpy.array with labels by not number but the columns.
I am sorry that I didn't make the "plot" method clearly. What I want to express is the payoff matrices and game tree in our game theory textbooks. It can be also implemented by a better print method. I will try to plot or print some example these days.

[Guo-Zhang]

@jstac @cc7768 @oyamad Sorry for the late reply. I searched for all possible methods, but no good way to plot them directly because of the poor implements of visualization in Python. Here I write a very simple sample:
https://github.com/Guo-Zhang/pyecon/blob/master/games/demonstrating.ipynb
Hope it can express part of my thinking.

It seems that if I want to express it clearly, I have to redefine a whole data structure for high-dimensional payoffs matrix and game tree structure. I am searching for good implements.