gdMetriX is a Python library and NetworkX extension for computing graph drawing quality metrics — also known as graph layout aesthetics, readability metrics, or graph embedding quality measures. It implements peer-reviewed metrics from the graph drawing and information visualization literature (crossing number, crossing density, symmetry, node distribution, edge orthogonality, angular resolution, and more) so you can quantitatively evaluate, compare, and benchmark graph layouts and graph drawing algorithms.

📖 Full documentation · 📦 PyPI package · 📄 Cite the paper · 🕹️ Try the live graph editor

If you draw, lay out, embed, or visualize graphs and networks — and need to answer "how good is this layout?" — gdMetriX gives you a ready-made, tested toolkit instead of re-implementing graph drawing metrics from papers yourself:

• Drop-in NetworkX integration — works directly with networkx.Graph / DiGraph objects and node pos attributes, no custom graph format required.
• Broad metric coverage — crossings, area & boundary, node distribution, edge directions, and symmetry metrics, each backed by a citation to the original publication.
• Benchmark datasets included — one-line access to the Graph Layout Benchmark Datasets, so you can evaluate algorithms on real-world graphs (subway maps, code dependency graphs, Rome graphs, chess openings, SteinLib, and more) without manually downloading and parsing data.
• Built for research — used to support reproducible evaluation of graph layout / graph embedding algorithms; citable via a Dagstuhl / LIPIcs publication.

Typical use cases: evaluating graph layout/graph drawing algorithms, comparing force-directed vs. orthogonal vs. hierarchical layouts, scoring auto-generated diagrams, building graph visualization quality dashboards, and academic research in graph drawing and network visualization.

• Installation
• Examples
• Implemented metrics
• Loading benchmark datasets
• Interactive graph editor
• Documentation
• Contributing
• Citing
• License

gdMetriX requires Python 3.9 or higher.

Before installing, make sure you have the latest version of pip installed:

python -m pip install --upgrade pip

To install the package using pip use the following command:

pip install gdMetriX

gdMetriX works with the graph classes of networkX. For more details on how to work with networkX, please refer to their documentation.

For all graph drawing metrics, gdMetriX needs node positions, which is expected as a tuple with the attribute name ' pos'. You can set the attributes using networkX:

import networkx as nx
import gdMetriX

g = nx.Graph()
g.add_node('nodeA')
g.add_node('nodeB')
pos = {'nodeA': (0, 3.5), 'nodeB': (-3, 3)}
nx.set_node_attributes(g, pos)

Alternatively you can also set the position for a individual vertex:

g.add_node('nodeC', pos=(0, 0))

For a complete list of implemented metrics, please refer to the documentation.

For an example, in order to calculate the number of crossings, use:

crossings = gdMetriX.get_crossings(g)
print(len(crossings))

The node positions are automatically read from the graph. You can also supply them directly:

pos = {'nodeA': (0, 3.5), 'nodeB': (-3, 3), 'nodeC': (0, 0)}
crossings = gdMetriX.get_crossings(g, pos=pos)
print(len(crossings))

Other graph drawing metrics follow the same pattern — for example, crossing density, edge orthogonality and reflective symmetry:

crossing_quality = gdMetriX.crossing_density(g)
orthogonality = gdMetriX.edge_orthogonality(g)
symmetry_score = gdMetriX.reflective_symmetry(g)

gdMetriX implements graph drawing quality metrics across five categories. Each metric links to its implementation and the publication it is based on in the full metrics reference.

gdMetriX also includes supporting utilities for graph drawing research: planarization, position normalization, combinatorial embeddings, ordered neighborhoods, and heatmap generation for local metrics. See the additional features reference for details.

gdMetriX supports the automatic import of graph drawing datasets. The datasets are collected from the Graph Layout Benchmark Datasets project from the Northeastern University Visualization Lab easily accessible for networkX.

The project aims to collect datasets used for graph layout algorithms and make them available for long-term access. The graphs are stored on the Open Science Foundation platform.

Information about the individual datasets can be found at the project homepage.

To get a list of all available datasets:

available_datasets = gdMetriX.get_available_datasets()
print(available_datasets)
# ['subways', 'code', 'rome', 'chess', 'steinlib', ...]

To iterate over all graphs of a given dataset, simply call gdMetriX.iterate_dataset():

for graph in gdMetriX.iterate_dataset('subways'):
    print(graph.nodes())

Want to try gdMetriX without writing any code? The live interactive graph editor lets you draw or import a graph in your browser and see gdMetriX's quality metrics (crossings, symmetry, node distribution, edge orthogonality, and more) calculated and updated live as you edit the layout.

The full API reference, tutorial notebooks, and the complete list of implemented graph drawing metrics are available at livus.github.io/gdMetriX.

Contributions are welcome! Whether it's a new metric, a bug fix, a documentation improvement, or a new dataset integration, feel free to open an issue or pull request. New to the project? Start with an issue labeled "good first issue".

If you find this project useful for your work, consider citing the corresponding Dagstuhl publication.

@InProceedings{nollenburg_et_al:LIPIcs.GD.2024.45,
  author    = {N\"ollenburg, Martin and R\"oder, Sebastian and Wallinger, Markus},
  title     = {{GdMetriX - A NetworkX Extension For Graph Drawing Metrics}},
  booktitle = {32nd International Symposium on Graph Drawing and Network Visualization (GD 2024)},
  pages     = {45:1--45:3},
  series    = {Leibniz International Proceedings in Informatics (LIPIcs)},
  ISBN      = {978-3-95977-343-0},
  ISSN      = {1868-8969},
  year      = {2024},
  volume    = {320},
  editor    = {Felsner, Stefan and Klein, Karsten},
  publisher = {Schloss Dagstuhl -- Leibniz-Zentrum f\"ur Informatik},
  address   = {Dagstuhl, Germany},
  doi       = {10.4230/LIPIcs.GD.2024.45}
}

The project is distributed under the GNU General Public License Version 3.