draw_tree

Game tree drawing tool for publication-ready extensive form Game Theory games. Generates TikZ code, LaTeX documents, PDFs, and PNGs.

• Reads .ef format files with layout formatting which can be created via Game Theory Explorer. See specs.pdf for details.
• Also can read .efg format generated by Gambit, which will be converted to .ef internally, applying a default layout before rendering.

⚠️⚠️⚠️ Warning: draw_tree is currently in early development. ⚠️⚠️⚠️

draw_tree was originally developed by Bernhard von Stengel at the London School of Economics. It is being developed further as part of the Gambit project out of The Alan Turing Institute.

Table of Contents

• Installation
• Requirements
• CLI
• Python API
• Rendering in Jupyter Notebooks
• Developer docs: Testing

Installation

Clone the repo and install the package using pip:

git clone https://github.com/gambitproject/draw_tree
cd draw_tree
pip install -e .

Requirements

• Python 3.10+ (tested on 3.13)
• LaTeX with TikZ (for PDF/PNG generation)
• (optional) ImageMagick or Ghostscript or Poppler (for PNG generation)

Installing LaTeX

Note: PDF and PNG generation require pdflatex to be installed and available in PATH. Tested methods have a ✅ next to them. Methods include:

• macOS:
  • Install MacTEX ✅
  • brew install --cask mactex
• Ubuntu:
  • sudo apt-get install texlive-full ✅
• Windows: Install MiKTeX

PNG generation

PNG generation will default to using any of ImageMagick or Ghostscript or Poppler that are installed. If none are installed, try one of the following:

• macOS:
  • brew install imagemagick
  • brew install ghostscript
  • brew install poppler
• Ubuntu:
  • sudo apt-get install imagemagick
  • sudo apt-get install ghostscript
  • sudo apt-get install poppler-utils
• Windows: Install ImageMagick or Ghostscript from their websites

CLI

By default, draw_tree generates TikZ code and prints it to standard output. There are also options to generate a complete LaTeX document, a PDF or a PNG directly, either by specifying the desired format or by using the output filename extension:

draw_tree games/example.ef                                 # Prints TikZ code to stdout
draw_tree games/example.ef --tex                           # Creates example.tex
draw_tree games/example.ef --output=custom.tex             # Creates custom.tex
draw_tree games/example.ef --pdf                           # Creates example.pdf
draw_tree games/example.ef --png                           # Creates example.png
draw_tree games/example.ef --png --dpi=600                 # Creates high-res example.png (72-2400, default: 300)
draw_tree games/example.ef --output=mygame.png scale=0.8   # Creates mygame.png with 0.8 scaling (0.01 to 100)

Python API

You can also use draw_tree as a Python library:

from draw_tree import generate_tex, generate_pdf, generate_png
generate_tex('games/example.ef')                                    # Creates example.tex
generate_tex('games/example.ef', output_tex='custom.tex')           # Creates custom.tex
generate_pdf('games/example.ef')                                    # Creates example.pdf
generate_png('games/example.ef')                                    # Creates example.png
generate_png('games/example.ef', dpi=600)                           # Creates high-res example.png (72-2400, default: 300)
generate_png('games/example.ef', output_png='mygame.png', scale_factor=0.8)    # Creates mygame.png with 0.8 scaling (0.01 to 100)

Rendering in Jupyter Notebooks

In a Jupyter notebook, run:

from draw_tree import draw_tree
draw_tree('games/example.ef')

⚠️⚠️⚠️ Warning: Images do not render correctly in notebooks opened in VSCode; open notebooks in Jupyter Lab. ⚠️⚠️⚠️

Developer docs: Testing

The project includes a comprehensive test suite using pytest. To run the tests:

Run all tests:

pytest tests/ -v

Run tests with coverage:

pytest tests/ --cov=draw_tree --cov-report=html