#

Note

This documents the development version of NetworkX. Documentation for the current release can be found here.

#

Migration guide from 1.X to 2.0

This is a guide for people moving from NetworkX 1.X to NetworkX 2.0

Any issues with these can be discussed on the mailing list.

At the bottom of this document we discuss how to create code that will work with both NetworkX v1.x and v2.0.

We have made some major changes to the methods in the Multi/Di/Graph classes. The methods changed are explained with examples below.

With the release of NetworkX 2.0 we are moving to a view/iterator reporting API. We have changed many methods from reporting lists or dicts to iterating over the information. Most of the changes in this regard are in the base classes. Methods that used to return containers now return views (inspired from dictionary views in Python) and methods that returned an iterator have been removed. The methods which create new graphs have changed in the depth of data copying. G.subgraph/edge_subgraph/reverse/to_directed/to_undirected are affected. Many now have options for view creation instead of copying data. The depth of the data copying may have also changed.

One View example is G.nodes (or G.nodes()) which now returns a dict-like NodeView while G.nodes_iter() has been removed. Similarly for views with G.edges and removing G.edges_iter. The Graph attributes G.node and G.edge have been removed in favor of using G.nodes[n] and G.edges[u, v]. Finally, the selfloop methods and add_path/star/cycle have been moved from graph methods to networkx functions.

We expect that these changes will break some code. We have tried to make them break the code in ways that raise exceptions, so it will be obvious that code is broken.

There are also a number of improvements to the codebase outside of the base graph classes. These are too numerous to catalog here, but a couple obvious ones include:

  • centering of nodes in drawing/nx_pylab,

  • iterator vs dict output from a few shortest_path routines


Some demonstrations:

>>> import networkx as nx
>>> G = nx.complete_graph(5)
>>> G.nodes  # for backward compatibility G.nodes() works as well
NodeView((0, 1, 2, 3, 4))

You can iterate through G.nodes (or G.nodes())

>>> for node in G.nodes:
...     print(node)
0
1
2
3
4

If you want a list of nodes you can use the Python list function

>>> list(G.nodes)
[0, 1, 2, 3, 4]

G.nodes is set-like allowing set operations. It is also dict-like in that you can look up node data with G.nodes[n]['weight']. You can still use the calling interface G.nodes(data='weight') to iterate over node/data pairs. In addition to the dict-like views keys/values/items, G.nodes has a data-view G.nodes.data(‘weight’). The new EdgeView G.edges has similar features for edges.

By adding views NetworkX supports some new features like set operations on views.

>>> H = nx.Graph()
>>> H.add_nodes_from([1, 'networkx', '2.0'])
>>> G.nodes & H.nodes  # finding common nodes in 2 graphs
{1}
>>> # union of nodes in 2 graphs
>>> G.nodes | H.nodes  
{0, 1, 2, 3, 4, 'networkx', '2.0'}

Similarly, G.edges now returns an EdgeView instead of a list of edges and it also supports set operations.

>>> G.edges  # for backward compatibility G.nodes() works as well
EdgeView([(0, 1), (0, 2), (0, 3), (0, 4), (1, 2), (1, 3), (1, 4), (2, 3), (2, 4), (3, 4)])
>>> list(G.edges)
[(0, 1), (0, 2), (0, 3), (0, 4), (1, 2), (1, 3), (1, 4), (2, 3), (2, 4), (3, 4)]

G.degree now returns a DegreeView. This is less dict-like than the other views in the sense that it iterates over (node, degree) pairs, does not provide keys/values/items/get methods. It does provide lookup G.degree[n] and (node, degree) iteration. A dict keyed by nodes to degree values can be easily created if needed as dict(G.degree).

>>> G.degree  # for backward compatibility G.degree() works as well
DegreeView({0: 4, 1: 4, 2: 4, 3: 4, 4: 4})
>>> G.degree([1, 2, 3])
DegreeView({1: 4, 2: 4, 3: 4})
>>> list(G.degree([1, 2, 3]))
[(1, 4), (2, 4), (3, 4)]
>>> dict(G.degree([1, 2, 3]))
{1: 4, 2: 4, 3: 4}
>>> G.degree
DegreeView({0: 4, 1: 4, 2: 4, 3: 4, 4: 4})
>>> list(G.degree)
[(0, 4), (1, 4), (2, 4), (3, 4), (4, 4)]
>>> dict(G.degree)
{0: 4, 1: 4, 2: 4, 3: 4, 4: 4}

The degree of an individual node can be calculated by G.degree[node]. Similar changes have been made to in_degree and out_degree for directed graphs. If you want just the degree values, here are some options. They are shown for in_degree of a DiGraph, but similar ideas work for out_degree and degree

>>> DG = nx.DiGraph()
>>> DG.add_weighted_edges_from([(1, 2, 0.5), (3, 1, 0.75)])
>>> deg = DG.in_degree   # sets up the view
>>> [d for n, d in deg]   # gets all nodes' degree values
[1, 1, 0]
>>> (d for n, d in deg)    # iterator over degree values
<generator object <genexpr> ...>
>>> [deg[n] for n in [1, 3]]   # using lookup for only some nodes
[1, 0]
>>> for node, in_deg in dict(DG.in_degree).items():  # works for nx1 and nx2
...     print(node, in_deg)
1 1
2 1
3 0
>>> dict(DG.in_degree([1, 3])).values()    # works for nx1 and nx2
dict_values([1, 0])
>>> # DG.in_degree(nlist) creates a restricted view for only nodes in nlist.
>>> # but see the fourth option above for using lookup instead.
>>> list(d for n, d in DG.in_degree([1, 3]))
[1, 0]
>>> [len(nbrs) for n, nbrs in DG.pred.items()]  # probably slightly fastest for all nodes
[1, 1, 0]
>>> [len(DG.pred[n]) for n in [1, 3]]           # probably slightly faster for only some nodes
[1, 0]

If n is a node in G, then G.neighbors(n) returns an iterator.

>>> n = 1
>>> G.neighbors(n)
<dict_keyiterator object at ...>
>>> list(G.neighbors(n))
[0, 2, 3, 4]

DiGraphViews behave similar to GraphViews, but have a few more methods.

>>> D = nx.DiGraph()
>>> D.add_edges_from([(1, 2), (2, 3), (1, 3), (2, 4)])
>>> D.nodes
NodeView((1, 2, 3, 4))
>>> list(D.nodes)
[1, 2, 3, 4]
>>> D.edges
OutEdgeView([(1, 2), (1, 3), (2, 3), (2, 4)])
>>> list(D.edges)
[(1, 2), (1, 3), (2, 3), (2, 4)]
>>> D.in_degree[2]
1
>>> D.out_degree[2]
2
>>> D.in_edges
InEdgeView([(1, 2), (2, 3), (1, 3), (2, 4)])
>>> list(D.in_edges())
[(1, 2), (2, 3), (1, 3), (2, 4)]
>>> D.out_edges(2)
OutEdgeDataView([(2, 3), (2, 4)])
>>> list(D.out_edges(2))
[(2, 3), (2, 4)]
>>> D.in_degree
InDegreeView({1: 0, 2: 1, 3: 2, 4: 1})
>>> list(D.in_degree)
[(1, 0), (2, 1), (3, 2), (4, 1)]
>>> D.successors(2)
<dict_keyiterator object at ...>
>>> list(D.successors(2))
[3, 4]
>>> D.predecessors(2)
<dict_keyiterator object at ...>
>>> list(D.predecessors(2))
[1]

The same changes apply to MultiGraphs and MultiDiGraphs.


The order of arguments to set_edge_attributes and set_node_attributes has changed. The position of name and values has been swapped, and name now defaults to None. The previous call signature of (graph, name, value) has been changed to (graph, value, name=None). The new style allows for name to be omitted in favor of passing a dictionary of dictionaries to values.

A simple method for migrating existing code to the new version is to explicitly specify the keyword argument names. This method is backwards compatible and ensures the correct arguments are passed, regardless of the order. For example the old code

>>> G = nx.Graph([(1, 2), (1, 3)])
>>> nx.set_node_attributes(G, 'label', {1: 'one', 2: 'two', 3: 'three'})  
>>> nx.set_edge_attributes(G, 'label', {(1, 2): 'path1', (2, 3): 'path2'})  

Will cause TypeError: unhashable type: 'dict' in the new version. The code can be refactored as

>>> G = nx.Graph([(1, 2), (1, 3)])
>>> nx.set_node_attributes(G, name='label', values={1: 'one', 2: 'two', 3: 'three'})
>>> nx.set_edge_attributes(G, name='label', values={(1, 2): 'path1', (2, 3): 'path2'})

Some methods have been moved from the base graph class into the main namespace. These are: G.add_path, G.add_star, G.add_cycle, G.number_of_selfloops, G.nodes_with_selfloops, and G.selfloop_edges. They are replaced by nx.path_graph(G, ...) nx.add_star(G, ...), nx.selfloop_edges(G), etc. For backward compatibility, we are leaving them as deprecated methods.


With the new GraphViews (SubGraph, ReversedGraph, etc) you can’t assume that G.__class__() will create a new instance of the same graph type as G. In fact, the call signature for __class__ differs depending on whether G is a view or a base class. For v2.x you should use G.fresh_copy() to create a null graph of the correct type—ready to fill with nodes and edges.

Graph views can also be views-of-views-of-views-of-graphs. If you want to find the original graph at the end of this chain use G.root_graph. Be careful though because it may be a different graph type (directed/undirected) than the view.


topolgical_sort no longer accepts reverse or nbunch arguments. If nbunch was a single node source, then the same effect can now be achieved using the subgraph operator:

nx.topological_sort(G.subgraph(nx.descendants(G, nbunch)))

To achieve a reverse topological sort, the output should be converted to a list:

reversed(list(nx.topological_sort(G)))


Writing code that works for both versions

Methods set_node_attributes/get_node_attributes/set_edge_attributes/get_edge_attributes have changed the order of their keyword arguments name and values. So, to make it work with both versions you should use the keywords in your call.

>>> nx.set_node_attributes(G, values=1.0, name='weight')

Change any method with _iter in its name to the version without _iter. In v1 this replaces an iterator by a list, but the code will still work. In v2 this creates a view (which acts like an iterator).


Replace any use of G.edge with G.adj. The Graph attribute edge has been removed. The attribute G.adj is G.edge in v1 and will work with both versions.


If you use G.node.items() or similar in v1.x, you can replace it with G.nodes(data=True) which works for v2.x and v1.x. Iterating over G.node` as in for n in G.node: can be replaced with G, as in: for n in G:.


The Graph attribute node has moved its functionality to G.nodes, so code expected to work with v2.x should use G.nodes. In fact most uses of G.node can be replaced by an idiom that works for both versions. The functionality that can’t easily is: G.node[n]. In v2.x that becomes G.nodes[n] which doesn’t work in v1.x.

Luckily you can still use G.node[n] in v2.x when you want it to be able to work with v1.x too. We have left G.node in v2.x as a transition pointer to G.nodes. We envision removing G.node in v3.x (sometime in the future).


Copying node attribute dicts directly from one graph to another can corrupt the node data structure if not done correctly. Code such as the following:

>>> # dangerous in v1.x, not allowed in v2.x
>>> G.node[n] = H.node[n]  

used to work, even though it could cause errors if n was not a node in G. That code will cause an error in v2.x. Replace it with one of the more safe versions:

>>> G.node[n].update(H.node[n])  # works in both v1.x and v2.x
>>> G.nodes[n].update(H.nodes[n])  # works in v2.x

The methods removed from the graph classes and put into the main package namespace can be used via the associated deprecated methods. If you want to update your code to the new functions, one hack to make that work with both versions is to write your code for v2.x and add code to the v1 namespace in an ad hoc manner:

>>> if nx.__version__[0] == '1':
...     nx.add_path = lambda G, nodes: G.add_path(nodes)

Similarly, v2.x code that uses G.fresh_copy() or G.root_graph is hard to make work for v1.x. It may be best in this case to determine the graph type you want explicitly and call Graph/DiGraph/MultiGraph/MultiDiGraph directly.

Using Pickle with v1 and v2

The Pickle protocol does not store class methods, only the data. So if you write a pickle file with v1 you should not expect to read it into a v2 Graph. If this happens to you, read it in with v1 installed and write a file with the node and edge information. You can read that into a config with v2 installed and then add those nodes and edges to a fresh graph. Try something similar to this:

>>> # in v1.x
>>> pickle.dump([G.nodes(data=True), G.edges(data=True)], file)  
>>> # then in v2.x
>>> nodes, edges = pickle.load(file)  
>>> G = nx.Graph()  
>>> G.add_nodes_from(nodes)  
>>> G.add_edges_from(edges)