synthesizer.emission_models.visualise_network

A submodule for visualising emission model networks.

An EmissionModel describes a network of models connected by the operations which turn one emission into another. This submodule draws that network, which is the only practical way to understand a model of any size.

The whole network is drawn, not just the models reachable from a single root. This matters because related models are roots in their own right, and expanding a parameter variation attaches all but one of its variants as related models.

The drawing is a layered diagram, read bottom to top in the direction the emission flows. It is built in the usual four stages:

  1. Each model is placed on a row directly below the model which consumes it, so a grid extraction sits under whatever uses it. This keeps the diagram narrow; collecting every extraction onto a single bottom row instead makes the widest row as wide as the number of grids, which no amount of styling can rescue.

  2. Rows are ordered by the barycentre of each model’s neighbours to reduce edge crossings, with a placeholder standing in for each row an edge passes through. The placeholders reserve an empty column, so a long edge always has somewhere to run.

  3. Columns are straightened, so chains of models line up rather than fanning.

  4. Edges are routed as orthogonal elbows through the reserved columns, turning only in the gaps between rows. An edge therefore cannot cross a box.

Everything is measured and laid out in points, the units the boxes are drawn in, so boxes cannot overlap regardless of the figure size. By default the figure is sized to fit the network; if a figure size is given, the labels are scaled down to fit it instead.

Passing layout=”dot” hands the layering and placement to graphviz instead, which is worth trying on dense networks. That needs pydot and the graphviz binary.

Example usage:

model.plot_emission_graph()
model.plot_emission_graph(layout="dot")
model.plot_emission_graph(show_variants=True)

Note that EmissionModel.plot_emission_graph is a thin wrapper around the function of the same name here, so this module does not usually need to be imported directly.

Functions

synthesizer.emission_models.visualise_network.plot_emission_graph(model_tree, root=None, show=True, fontsize=10, figsize=None, layout='layered', show_variants=False, min_fontsize=6.0)[source]

Plot the network of models defining an emission.

The whole network is drawn, including related models, which are roots in their own right. It reads bottom to top, in the direction the emission flows, with each model sitting below whatever consumes it.

Parameters:

  • model_tree (EmissionModel) – The model whose network is being drawn.

  • root (str) – If given, only this model and the models it depends on are drawn.

  • show (bool) – Whether to show the plot.

  • fontsize (int) – The fontsize to use for the labels. This is reduced if the network doesn’t fit the figure.

  • figsize (tuple) – The size of the figure to plot (width, height). By default the figure is sized to fit the network.

  • layout (str) – Either “layered” (the default), which needs only networkx, or “dot”, which lays the network out with graphviz and needs pydot and the graphviz binary.

  • show_variants (bool) – Whether to draw every parameter variant as its own node. By default each family of variants is collapsed into a single node badged with the number of models it stands for, since an expansion of any size produces more models than can be read at once. This has no effect on a model which was never expanded.

  • min_fontsize (float) – The size below which labels stop being readable. A network which cannot fit the figure with labels this big grows the figure rather than shrinking them further, so a big network stays as readable as a small one. Pass 0 to let the labels shrink as far as needed.

Returns:

The figure containing the plot. ax (matplotlib.axes.Axes): The axis containing the plot.

Return type:

fig (matplotlib.figure.Figure)