alph - altair for your graph

A Python library using Altair for declarative, data-driven network visualisation.

Why

Tidy, legible graph visualisations can be elusive. Alph helps by bringing together effective styling, layout and pruning options from across the Python ecosystem.

How it works

1. Get your data into a NetworkX Graph
2. Pick a network layout function, or bring your own node coordinates
3. Define node and edge style attributes
4. Plot using a simple function call

Best bet is probably to dive straight into the examples, and come back to the API documentation below as needed.

Features

• plot any NetworkX Graph
• support for any layout expressed as a NetworkX pos structure (a dict like {node_id: (x,y), ...})
• several readily accessible and tuneable layout functions (see example)
• Altair-style data driven node and edge styling - size, colour, stroke, opacity, scales, conditionals and more
• convenience args for node labels, halos
• experimental 1-level "combo" node support

Installation

Minimal

pip install alph

Recommended

1. for graphviz layout support, install graphviz on your platform - e.g. brew install graphviz on Mac, sudo apt install libgraphviz-dev graphviz on Colab, Debian, Ubuntu etc - or download the installer

2. Install alph with graphviz support:

   pip install "alph[graphviz]"
   

3. Install the ForceAtlas2 layout library from our fork, along with cython for speedup

   pip install cython "git+https://github.com/connectedcompany/forceatlas2.git"
   

Why is the ForceAtlas2 install separate?

ForceAtlas2 is a classic, user feedback led layout algorithm from the Gephi team, and the ForceAtlas2 library implementation is an excellent, performant Python port. There are two things to be aware of:

1. GPL licence - the ForceAtlas2 library, and some of the works it is derived from, are GPL licensed - hence care is needed when distributing and linking to it. We thus intend to keep its install optional long term. Since alph uses a plugin design for layout providers, this is straightforward for us to accommodate, and maintain explicit separation for use cases where GPL is an issue.

2. Our fork - recently, releases of the library have been sporadic - though there is stated intent for regular maintenance to resume. In the meantime, we've created a temporary fork to be able to roll in changes. Currently, our fork incorporates a simple change that enables deterministic layouts.

Usage

Simply call the alph function with desired options.

Minimally, given a weighted network G:

from alph import alph

G = ...
alph(G, weight_attr="weight")

Examples

See examples. Here's an overview:

• Some of the supported layouts (from the layouts gallery example):

• Use of geolocation coordinates for graph layout, (from the flight routes example):

• Basic styling (from the styling example):

• A styled interaction network (from the dolphins example):

• "Combo"-style layout (experimental) - category-driven node grouping with edge weight aggregation, from the Les Mis example:

API

Supported layout functions

• NetworkX layouts: Spring, Fruchterman-Reingold, etc
• NetworkX-wrapped graphviz layouts: dot, neato etc. You can use args for specific layouts - for example, for neato: args="-Goverlap=scale -Gstart=123"
• Gephi ForceAtlas2 based on the forceatlas2 Python implementation - see layout.py for configuration options, and this paper for more detail
• ForceAtlas implementation within scikit-network
• Any other that returns a NetworkX-style node positions dictionary

Supported arguments

Node args

Edge args

Tips

• Get to know your layout algos - especially the 2-3 most used ones. They can have a dramatic effect on the results. A combination of FA2, Spring and Fruchterman is extremely versatile if set up right.
• Pass seed to layout functions where possible, for repeatable layouts
• Set padding to ensure node elements stay within figure boundaries

Known limitations

• Node size attribute does not support all Altair options - currently only alt.value and alt.Size with linear domain and range scales. More can be added as needed.

  This is a design choice, made to not burden the user with calculating things like label and halo positions when node sizes vary. Will review this tradeoff based on in-use experience.

• One combo level currently supported

See also

• nx-altair is a nice project that takes a slightly different approach to combining NetworkX and Altair for network viz.