Package: geneagrapher
GeneagrapherGeneagrapher is a tool for building mathematician advisor-advisee
genealogies using information from theMathematics Genealogy
Project. The output is either a DOT
file, which can be used byGraphvizto
visualize the graph, or a JSON structure that you can consume with
other software tools. Here's an example of a genealogy built by
Geneagrapher and visualized using Graphviz:To use this package, you will need to have a Python interpreter on
your system and install this package. Additionally, if you want to
generate the graph visualization you will need another tool (e.g.,Graphviz).If you want to build a math genealogy more easily, you may want to
look at theGeneagrapher
notebook. That
Observable notebook creates geneagraphs in your browser.If you want to consume records from the Math Genealogy Project in your
own software, you may be interested ingeneagrapher-core.Basic ConceptsThe input to the Geneagrapher is a set of starting nodes and traversal
directions. Multiple starting nodes may be provided (to produce the
combined graph for an academic department's students and professors,
for instance).Starting NodesEach individual stored in the Mathematics Genealogy Project's website
has a unique integer as an identifier, and this identifier is what is
passed to the Geneagrapher to specify a starting node. The identifier
is contained in the URL for records in the Mathematics Genealogy
Project website. For example,Carl
Gaußis ID 18231 andLeonhard Euleris ID
38586.Before running the Geneagrapher, go to theMathematics Genealogy
Projectand gather the identifiers of
the starting nodes for the graph you want to build.Traversal DirectionsFor each starting node, you instruct Geneagrapher to traverse in the
advisor direction, the descendant (i.e., student) direction, or
both. For example, if you want to build the graph of a mathematician
and all of their students, you would specify the descendant traversal
direction for that starting node.SyntaxWhen running Geneagrapher, you provide starting nodes on the command
line. The syntax for doing this isNODE_ID:TRAVERSAL_DIRECTION,
whereTRAVERSAL_DIRECTIONisa | d, andaanddindicate
advisor and descendant traversal, respectively. Here are some
examples:Carl Gauß and his advisor graph:18231:a.Carl Gauß and his descendant graph:18231:d.Carl Gauß and his advisor and descendant graphs:18231:ad.InstallationTo install Geneagrapher, you must have Python >= 3.8.1. Geneagrapher
is installed by pip. If your system does not have pip, see the
instructionshere.Once pip is available on your system, install Geneagrapher with:pip install geneagrapherUsageYou can get help by doingggrapher --helpProcessing the DOT FileTo process the generated DOT file,Graphvizis needed. Graphviz installs
several programs for processing DOT files. For the Geneagrapher, use
thedotprogram. Let's look at an example.If the Geneagrapher has generated a file named "graph.dot", a PNG file
containing the graph can be created with the following command.dot -Tpng graph.dot > graph.pngThat's really all there is to it. Almost.By default,dotrenders an image with 96dpi. This may not look great
on high-resolution displays, so you might want to increase the
resolution. You can do this with the-Gdpiflag. For instance, to
produce a PNG with 150dpi, you can dodot -Tpng -Gdpi=150 graph.dot > graph.pngGraphviz can also generate other formats, such as PDF and SVG.ExamplesNote: the Mathematics Genealogy Project data changes over time, so if
the examples below are re-run, the results may look different. The
commands, however, will be the same.Single Node Ancestry: Theodor ZwingerTo produce the ancestry DOT file for Theodor Zwinger and save it in
the file zwinger.dot, run the commandggrapher -o zwinger.dot 125148:aMultiple Node Ancestry: Petrus Ryff and Theodor ZwingerTo produce the combined ancestry DOT file for Petrus Ryff and Theodor
Zwinger and save it in the file ryff_zwinger.dot, run the commandggrapher -o ryff_zwinger.dot 125148:a 130248:aSingle Node Descendant Graph: Haskell CurryTo produce the descendant DOT file for Haskell Curry and save it in
the file curry.dot, run the commandggrapher -o curry.dot 7398:dNote that descendant graphs often have a lot of "fan out".Technical DetailsPrevious versions of Geneagrapher made requests directly to the
Mathematics Genealogy Project and built the graph in the
application. The current version of Geneagrapher, however, makes
requests to an intermediate service that is built usinggeneagrapher-core. This
backend service assembles requested graphs and maintains a cache of
records.While the shared cache substantially reduces the number of requests
from individuals running Geneagrapher (or theGeneagrapher
notebook) and
speeds up the graph-building process, it also creates an opportunity
for inconsistency between information in the Mathematics Genealogy
Project and the cache. This can happen when records are updated in the
Mathematics Genealogy Project. Such inconsistencies will automatically
be resolved when cached values expire.