High Level API

In this notebook, we will walk through the high level nxviz API.

The intent here is to provide a convenient (albeit restrictive) way to build graph visualizations for exploratory analysis purposes. Our goal is to help you declaratively visualize a network using one of the rational visualizations provided. The design is intentionally quite restrictive; customizations are limited to what you can compose together.

You should treat these the way you would use the plotting package seaborn: to get you a quick overview of your data without being bogged down by the details of how things are placed on the screen. If you want finer-grained control, then you may wish to drop down to the mid-level or low-level API instead.

How to read this notebook

Treat this notebook as a gallery of examples. As with all declarative APIs, it's important to know the structure of the graph. We're showing you the exact source code for graph construction, and the graph's corresponding node and edge tables, to make things easier to read.

%config InlineBackend.figure_format = 'retina'
%load_ext autoreload
%autoreload 2

from random import choice

import matplotlib.pyplot as plt
import networkx as nx
import numpy as np

import nxviz as nv
from nxviz import annotate, highlights
from nxviz.plots import despine, rescale, respine

/home/runner/work/nxviz/nxviz/nxviz/__init__.py:33: UserWarning: 
nxviz has a new API! Version 0.7.4 onwards, the old class-based API is being
deprecated in favour of a new API focused on advancing a grammar of network
graphics. If your plotting code depends on the old API, please consider
pinning nxviz at version 0.7.4, as the new API will break your old code.

To check out the new API, please head over to the docs at
https://ericmjl.github.io/nxviz/ to learn more. We hope you enjoy using it!

(This deprecation message will go away in version 1.0.)

  warnings.warn(

Example Graph

We're going to use an example graph, the erdos-renyi graph, to illustrate.

Source code

Here's the source code for graph generation.

G = nx.erdos_renyi_graph(n=71, p=0.1)
for n, d in G.nodes(data=True):
    G.nodes[n]["group"] = choice(["a", "b", "c"])
    G.nodes[n]["value"] = np.random.exponential()

np.random.seed(44)
for u, v, d in G.edges(data=True):
    G.edges[u, v]["edge_value"] = np.random.exponential()

from random import choice

u, v = choice(list(G.edges()))

Node table

from nxviz.utils import edge_table, node_table

node_table(G)

	group	value
0	c	0.213805
1	c	1.784391
2	a	0.073540
3	c	0.403458
4	a	0.458212
...	...	...
66	a	0.770954
67	a	1.606752
68	b	0.074074
69	a	0.719427
70	a	0.679490

71 rows × 2 columns

edge_table(G)

	edge_value	source	target
0	1.800854	0	10
1	1.800854	10	0
2	0.110704	0	14
3	0.110704	14	0
4	1.365083	0	21
...	...	...	...
501	0.918417	67	66
502	0.485085	67	68
503	0.485085	68	67
504	0.900958	69	70
505	0.900958	70	69

506 rows × 3 columns

Hive Plot

Here's a Hive Plot view of the graph.

The Hive plot is appropriate here, because we have one categorical variables with three values by which we can group our nodes.

Here's one example where we group the nodes by their group attribute, sort and colour them by their value attribute, and set the transparency of an aged based on the edge's edge_value attribute. We also annotate the grouping on the hive plot.

ax = nv.hive(
    G,
    group_by="group",
    sort_by="value",
    node_color_by="value",
    edge_alpha_by="edge_value",
)
annotate.hive_group(G, group_by="group", offset=np.pi / 12)

Here's an alternative visualization where we group and colour the nodes by their group attribute, ignoring the value attribute on the nodes and the edge_value attribute on the edges.

ax = nv.hive(G, group_by="group", node_color_by="group")
annotate.hive_group(G, group_by="group")
highlights.hive_node(G, u, group_by="group")
highlights.hive_node(G, v, group_by="group")
highlights.hive_edge(G, u, v, group_by="group")

The same consistent API applies to the other plot types.

Arc Plot

ax = nv.arc(
    G, group_by="group", node_color_by="group", edge_alpha_by="edge_value"
)
annotate.arc_group(G, group_by="group", ha="center", rotation=0)
highlights.arc_node(G, u, group_by="group")
highlights.arc_node(G, v, group_by="group")
highlights.arc_edge(G, source=u, target=v, group_by="group")

Circos Plot

ax = nv.circos(
    G, group_by="group", node_color_by="group", edge_alpha_by="edge_value"
)
annotate.circos_group(G, group_by="group")

highlights.circos_edge(G, u, v, group_by="group")
highlights.circos_node(G, u, group_by="group")
highlights.circos_node(G, v, group_by="group", color="blue")

Matrix Plot

fig, ax = plt.subplots(figsize=(7, 7))
ax = nv.matrix(
    G,
    group_by="group",
    sort_by="value",
    node_color_by="group",
    edge_alpha_by="edge_value",
)
annotate.matrix_group(G, group_by="group")
annotate.matrix_block(G, group_by="group", color_by="group", alpha=0.1)
highlights.matrix_node(G, u, group_by="group", sort_by="value")
highlights.matrix_node(G, v, group_by="group", sort_by="value", color="blue")
highlights.matrix_row(G, u, group_by="group", sort_by="value")
highlights.matrix_row(G, v, group_by="group", sort_by="value", axis="y", color="blue")

highlights.matrix_edge(G, u, v, group_by="group", sort_by="value")