Math Genealogy

Build advisor/advisee genealogy graphs from the Mathematics Genealogy Project. Give it one or more record IDs and it produces a PDF (or PNG/SVG) of the academic family tree.

This is a Python 3 modernization of thearn/math-genealogy by Tristan Hearn (@thearn), which is now retired and was Python 2 only. The rewrite keeps the same idea but drops the heavy dependency stack: it now relies only on the Python standard library plus two external command-line tools.

How it works

1. Geneagrapher (ggrapher) fetches the genealogy data for a person and writes a Graphviz .dot file.
2. Graphviz (dot) renders that .dot file into a PDF, PNG, or SVG.

Passing several IDs at once lets Geneagrapher merge them into a single graph, with shared advisors de-duplicated automatically.

Install

You need Python 3.8+ and the two command-line tools below. There are no third-party Python packages to install.

# 1. Geneagrapher (provides the `ggrapher` command)
pip install geneagrapher

# 2. Graphviz (provides the `dot` command) -- install the system package
sudo apt-get install graphviz        # Debian / Ubuntu
brew install graphviz                # macOS
choco install graphviz               # Windows

Verify both are on your PATH:

ggrapher --version
dot -V

Usage

Find a person's ID at the end of their Mathematics Genealogy Project URL (e.g. mathgenealogy.org/id.php?id=190349 → 190349).

# A single person's ancestry, as PDF (the default)
python build_genealogy.py 190349

# Several output formats at once are possible
python build_genealogy.py 190349 -o pdf png svg

# Several people merged into one combined graph
python build_genealogy.py 190349 153758 59331 339067 231787 

# Descendants instead of advisors (-t a = ancestors, d = descendants, ad = both)
python build_genealogy.py 190349 -t ad

Output files are written to the current directory, named after the ID(s) — e.g. 190349.pdf or 18231-190349.pdf for a combined graph. The fetched .dot files are cached in your system temp directory and reused on subsequent runs.

Options

Flag	Description	Default
mathid	One or more Mathematics Genealogy Project IDs (positional)	required
-o, --output	Output format(s): pdf, png, svg	pdf
-t, --traversal	Graph direction: a advisors/ancestors, d descendants, ad both	a

Credits

• Original project: thearn/math-genealogy by Tristan Hearn.
• Data tool: Geneagrapher by David Alber.
• Source data: the Mathematics Genealogy Project.

License

Licensed under the Apache License, Version 2.0, retained from the original project. See LICENSE.txt.