Go Review Partner documentation

Software purpose

Go Review Partner ("GRP") is a tool to help analyze and review your games of go (weiqi, baduk) using bots.

GRP is not yet another SGF editor, it won't allow you to view or modify (adding variations or comments) an existing SGF file.

Instead, it takes one existing SGF and "feed it" to a bot (currently, GnuGo, Leela and Ray are supported) then has the bot give its "opinion" on the best moves to play for each game position. GRP proposes a nice interface to review all those data.

Game review work-flow

Basically, it's a two step process:

Analysis of SGF by a bot

Simply speaking, this consists in picking the SGF file from inside the GRP software, selecting a bot for the analysis, then have it perform the analysis.

You also have the possibility to select a specific range of move to perform the analysis, or only one color.

Beware, the analysis can take quite a bit of time. The higher your level, the higher you want the bot to be stronger to give valuable insight on your game. So if you want the bot to spend 20 second to review each of the game moves, and if it was a 250 moves game, the be ready to wait for more than 2 hours.

Also, the analysis will give a lot of work to your computer during this time, so it migh become really unresponsive, to the point you might not be able to use it!

So go ahead, grab a cup of tea/coffee, have a nap, play a few games on-line, do some tsumego, whatever... then came back to your computer when the analysis is completed.

So what will your computer be doing during all this time? It depends of the bot you selected for the analysis, but generally speaking, it will stop at each moves of your game, then ask itself what moves it would play for that position. In fact, it will probably come up with more than one move, and for each of those moves, it will also have a follow up sequence as it imagines the game would proceed from that point. Usually, additional informations (like win rate) are provided for all those variation.

During the analysis, all that information is gathered and consolidated by GRP and used to produce a new SGF file, that is renamed as RSGF (Reviewed SGF). So if the original game file was name my_game.sgf, then the resulting RSGF file will be named my_game.rsgf

See the Running analysis section for more information.

Review of that RSGF file using GRP interface

So when the analysis is completed, you end up with and RSGF file.

In fact, this is a valid SGF file, but believe me, you don't want to open it with your usual SGF editor. The reason for that is that the analysis will have produced a very big game tree: imagine that for each of the 250 moves of your game, 5 variations have been added (each variation being ~10 moves deep), then it will be very painful to review it using a standard SGF editor.

Still want to open it with your usual SGF editor? Sure! No big deal, rename the file from .rsgf to .sgf and have a look for yourself.

When to much information is available, the way to present it and navigate through it is critical. And so GRP comes with an interface adapted to those RSGF files.

See the Game review section for more information.

Installation and running

In fact, it is not really possible to install GRP so far, it's a standalone application that come without installator. So there are two ways to run GRP:

Running from the sources

Running GRP from the sources is not as complicated as it seems. There is not "compilation" needed, and in fact, this is the recommended way to run it if your are a bit comfortable with computers.

Installing python and TkInter

GRP is programmed using python 2, so you will need python 2 to run or your computer. GRP also uses the TkInter library to display its graphical interface, so make sure to have that installed as well.

Downloading and running from the sources

At this point, you will want to download the sources for GRP. They are hosted on github at https://github.com/pnprog/goreviewpartner, look for the green button "Clone or download" and then "Download ZIP". That zip should be named "goreviewpartner-master". Unzip it wherever you think is appropriate.

Finally, you have to run GRP:

GRP is now hopefully working, you will have to set it up to use one or more bots. See the Settings section for more information.

Running from a bundled download

This is the recommended way if you are using a Microsoft operating system, and don't want to download bots and set up GRP yourself. You will find download links from the project main page at https://github.com/pnprog/goreviewpartner.

Download the ZIP archives, unzip it wherever you think is appropriate, then run GoReviewPartner.exe

Main panel

Here is what you will see when launching GRP:

alt text

Run *.sgf analysis will lead you to select a SGF on your computer and run an analysis on this file. See the Running analysis section for more information.

In a very similar way, Download *.sgf for analysis will lead you to enter the URL for a SGF file, then download it from the network on your computer and run an analysis on this file. This comes handy for modern Go servers like OGS that provide direct download link to the games. It avoids you the intermediate step to save the file first, and then open it from inside GRP. See the Running analysis section for more information.

Open *.rsgf for analysis will lead you to select a RSGF file from your computer and open it for review. See the Game review section for more information.

Settings is where you define the bots to use for analysis, some of their working parameters, and a few other settings for GRP. If you are running GRP from the sources (not from a bundled download) then setting GRP is a necessary step prior to any game analysis and review. See the Settings section for more information.

Settings

Here is what you will see when opening the Settings panel of GRP:

alt text

It is currently divided in 3 parts:

Review settings

Below are the 3 settings available for this section, together with their meanings:

Fuzzy Stones

This parameter defines how accurately the stones are positioned on the goban intersection. A value of 0 means perfect placement. You probably do not want to go for values higher than 0.3

Below is what it looks for different values:

fuzzy = 0 fuzzy = 0.2 fuzzy = 0.5 fuzzy = 1
alt text alt text alt text alt text

Real Game sequence deepness

This parameter defines how many moves from the actual game you want to be previewed on the left goban during review. You can compare the results of having this value set at 5 or set at 20 on the two following pictures:

Real game sequence deepness = 5

alt text

Real game sequence deepness = 20

alt text

Goban/screen ratio

This parameter define the size of the goban displayed, as the ratio between the goban size (in pixel) and the screen height in (pixel).

So a value of 0.5 means the goban width and height equal half of the screen height (or width, whichever is the smallest one).

Currently, resizing of the windows with mouse does not work.

Ray settings

Ray (https://github.com/zakki/ray) is a strong bot, by Yuki Kobayashi, distributed under BSD License. Ray is still at its early stage of development, but is probably the strongest opensource Go AI at the moment.

If your computer is equipped with a powerful Nvidia GPU that can run SCUDA, then Ray is probably the bot you will want to use.

Versions 4.2.5 and above are supported.

Here are the settings available:

It is strongly advised you try running Ray using the command and parameters you provided into a terminal to ensure everything is working as intended. It should get you into its GTP mode, typing version then pressing enter should return its version.

Leela settings

Leela (https://www.sjeng.org/leela.html) is an other strong bot, by Gian-Carlo Pascutto. Leela saw a huge increase in strength following Google/Deepming publication in Nature, and in 2016 became the strongest Go bot free to download and use.

It fact, this is Leela that prompted me to start GoReviewPartner.

If your computer is equipped with a strong multi core CPU, or a strong GPU that can run OpenCL, then Leela is probably the bot you will want to use.

Version 10 is supported.

Here are the settings available:

It is strongly advised you try running Leela using the command and parameters you provided into a terminal to ensure everything is working as intended. It should get you into its GTP mode, typing version then pressing enter should return its version.

GnuGo settings

GnuGo (https://www.gnu.org/software/gnugo/) is a free program that plays the game Go.

Its strength is nowhere near that of Ray or Leela, but its analysis is still relevant if your strength is about 15kyu or weaker.

Beside, GnuGo runs well and fast on old computers (Ray and Leela won't run on 32-bit computers).

GnuGo is not using Monte Carlo methods (MTCS) so its behavior may feels much more human in those situations:

Version 3.8 is supported.

Here are the settings available:

It is strongly advised you try running GnuGo using the command and parameters you provided into a terminal to ensure everything is working as intended. It should get you into its GTP mode, typing version then pressing enter should return its version.

Running analysis

Running the analysis is a very straightforward process:

Selection of SGF is made from the main panel, either from a SGF on your computer (press the Run *.sgf analysis button) of either from a on-line SGF (press the Download *.sgf for analysis button). See the Main panel section for more information.

If you choose to download the SGF file directly from the network, you will be asked to write or paste the URL into that pop-up, then press the Get button:

alt text

GRP will then let you select the analysis parameters:

alt text

Bot to use for the analysis will display the bots currently configured (if no command was provided for a bot, it won't be listed).

Select a variation to be analysed let you choose which line of play to follow for the analysis. Typically, a game record SGF only contains one variation, but if a move was undo-ed during the game, this may have created a second branch. Pay attention to the number of moves for each branch to decide what branch to analyse. Other branches will be removed from the RSGF tree.

Select moves to be analysed let you chose the range of moves to analyse. You can analyse all of them, or only a subset of them. One or more move intervals can be indicated (ex: 10-20, 40,50-51,63,67).

Select colors to be analysed let you chose which player's move to be analysed. It is advised to analyse both Black and White, as this is necessary to produce comparison graphs.

When this is done, just press Start button to start the analysis:

alt text

The indicated remaining time is an approximation only. Once the analysis, is completed, GRP will propose to directly open the RSGF file in review mode:

alt text

Game review

To review an RSGF file, open it from the main panel Open *.rsgf for review button. This will open a double board interface:

alt text

Interface overview

Variations available

On both board, you will noticed letters (A, B, C...). Those are the different variation available for this game position. So the left board only contains one (that of the actual game). The variations on the right board are the variation provided by the bot, with A being the best variation (the one the bot would chose), then B, C... second and third best variation, and so on.

alt text

If no variation is available, this could be because:

The right board moves may have different colors:

Note that if the letter color is black (inside a red or blue circle) this indicates that this move was also the game actual move.

Displaying sequences

Move you mouse over one of the variation, and the complete sequence will be displayed with each move numerated.

alt text

Additional information for that line of play will be indicated in the comment box bellow the board.

If you want to follow the sequence move my move, then you can use your mouse scrolling wheel, it will display the moves one by one. Your keyboard Up and Down keys can be used as well.

Territories

GnuGo provides a territory map, and Leela provides an influence map. Both can be visualized by pressing the territories button. This button does not appear when those data are not available.

alt text

Captured stones are marked using a dot from the opposite color.

Graphs

Using the win rate values provided at each move allows to draw some interesting charts. GnuGo does not provide win rates, so no graphs are available when the analysis has been made from GnuGo.

Win rate graph

This graph consists in the successive values of win rates, from black perspective.

alt text

Click on one of the grey bar will bring to that position in the review panel.

When no bar are available, it means no data were provided, possibly because:

Comparison graphs

By comparing the win rate at one move (when the bot best move would be played) withthe win rate of the following move (the case when the actual game move was played), one can draw a comparison chart for each color.

This is a chart that indicate by how much the bot believes it could have played better than the human player, or eventually by how much the human player move was better than its own move.

alt text

On this graph:

So red means margin for improvement, and green means better the bot, from the bot point of view.

On the comparison graph above, the very last move win rate, when added the red quantity, now exceeds 50%, meaning that from the bot point of view, this move was a blunder that cost black the game.

Here is the corresponding white comparison graph:

alt text

Click on one of the grey bar will bring to that position in the review panel.

When no bar are available, it means no data were provided, possibly because:

Opening a move for manual analysis

During the game review, you might want to try out your own variation. This is made possible by using the open button.

This will open the game position in a new pop-up, where you are free to manually try other lines of play.

alt text

If the Needed for review option has been enabled for a bot (see the Settings section for more information.), you can ask it to play with you along the variation, and then check its answers to your different variations.