ioftools / networkxMiCe / networkxmaster / doc / release / api_0.99.rst @ 5cef0f13
History  View  Annotate  Download (8.26 KB)
1 
************************ 

2 
Version 0.99 API changes 
3 
************************ 
4  
5 
The version networkx0.99 is the penultimate release before 
6 
networkx1.0. We have bumped the version from 0.37 to 0.99 to 
7 
indicate (in our unusual version number scheme) that this is a major 
8 
change to NetworkX. 
9  
10 
We have made some significant changes, detailed below, to NetworkX 
11 
to improve performance, functionality, and clarity. 
12  
13 
Version 0.99 requires Python 2.4 or greater. 
14  
15 
Please send comments and questions to the networkxdiscuss mailing list. 
16 
http://groups.google.com/group/networkxdiscuss 
17  
18 
Changes in base classes 
19 
======================= 
20  
21 
The most significant changes are in the graph classes. 
22 
We have redesigned the Graph() and DiGraph() classes 
23 
to optionally allow edge data. 
24 
This change allows Graph and DiGraph to naturally represent 
25 
weighted graphs and to hold arbitrary information on edges. 
26  
27 
 Both Graph and DiGraph take an optional argument weighted=TrueFalse. 
28 
When weighted=True the graph is assumed to have numeric edge data 
29 
(with default 1). The Graph and DiGraph classes in earlier versions 
30 
used the Python None as data (which is still allowed as edge data). 
31  
32 
 The Graph and DiGraph classes now allow self loops. 
33  
34 
 The XGraph and XDiGraph classes are removed and replaced with 
35 
MultiGraph and MultiDiGraph. MultiGraph and MultiDiGraph 
36 
optionally allow parallel (multiple) edges between two nodes. 
37  
38 
The mapping from old to new classes is as follows:: 
39  
40 
 Graph > Graph (self loops allowed now, default edge data is 1) 
41 
 DiGraph > DiGraph (self loops allowed now, default edge data is 1) 
42 
 XGraph(multiedges=False) > Graph 
43 
 XGraph(multiedges=True) > MultiGraph 
44 
 XDiGraph(multiedges=False) > DiGraph 
45 
 XDiGraph(multiedges=True) > MultiDiGraph 
46  
47  
48 
Methods changed 
49 
 
50  
51 
edges() 
52 
^^^^^^^ 
53 
New keyword data=TrueFalse keyword determines whether to return 
54 
twotuples (u,v) (False) or threetuples (u,v,d) (True) 
55  
56  
57 
delete_node() 
58 
^^^^^^^^^^^^^ 
59 
The preferred name is now remove_node(). 
60  
61  
62 
delete_nodes_from() 
63 
^^^^^^^^^^^^^^^^^^^ 
64 
No longer raises an exception on an attempt to delete a node not in 
65 
the graph. The preferred name is now remove_nodes_from(). 
66  
67  
68 
delete_edge() 
69 
^^^^^^^^^^^^^^ 
70 
Now raises an exception on an attempt to delete an edge not in the graph. 
71 
The preferred name is now remove_edge(). 
72  
73  
74 
delete_edges_from() 
75 
^^^^^^^^^^^^^^^^^^^ 
76 
The preferred name is now remove_edges_from(). 
77  
78  
79 
add_edge() 
80 
^^^^^^^^^^ 
81 
The add_edge() method no longer accepts an edge tuple (u,v) 
82 
directly. The tuple must be unpacked into individual nodes. 
83  
84 
>>> import networkx as nx 
85 
>>> u='a' 
86 
>>> v='b' 
87 
>>> e=(u,v) 
88 
>>> G=nx.Graph() 
89 

90 
Old 
91  
92 
>>> # G.add_edge((u,v)) # or G.add_edge(e) 
93  
94 
New 
95  
96 
>>> G.add_edge(*e) # or G.add_edge(*(u,v)) 
97  
98 
The * operator unpacks the edge tuple in the argument list. 
99  
100 
Add edge now has 
101 
a data keyword parameter for setting the default (data=1) edge 
102 
data. 
103 

104 
>>> # G.add_edge('a','b','foo') # add edge with string "foo" as data 
105 
>>> # G.add_edge(1,2,5.0) # add edge with float 5 as data 
106 

107  
108  
109 
add_edges_from() 
110 
^^^^^^^^^^^^^^^^ 
111 
Now can take list or iterator of either 2tuples (u,v), 
112 
3tuples (u,v,data) or a mix of both. 
113  
114 
Now has data keyword parameter (default 1) for setting the edge data 
115 
for any edge in the edge list that is a 2tuple. 
116  
117  
118 
has_edge() 
119 
^^^^^^^^^^ 
120 
The has_edge() method no longer accepts an edge tuple (u,v) 
121 
directly. The tuple must be unpacked into individual nodes. 
122  
123 
Old: 
124  
125 
>>> # G.has_edge((u,v)) # or has_edge(e) 
126  
127 
New: 
128  
129 
>>> G.has_edge(*e) # or has_edge(*(u,v)) 
130 
True 
131 

132 
The * operator unpacks the edge tuple in the argument list. 
133  
134 
get_edge() 
135 
^^^^^^^^^^ 
136 
Now has the keyword argument "default" to specify 
137 
what value to return if no edge is found. If not specified 
138 
an exception is raised if no edge is found. 
139 

140 
The fastest way to get edge data for edge (u,v) is to use G[u][v] 
141 
instead of G.get_edge(u,v) 
142  
143  
144 
degree_iter() 
145 
^^^^^^^^^^^^^ 
146 
The degree_iter method now returns an iterator over pairs of (node, 
147 
degree). This was the previous behavior of degree_iter(with_labels=true) 
148 
Also there is a new keyword weighted=FalseTrue for weighted degree. 
149  
150 
subgraph() 
151 
^^^^^^^^^^ 
152 
The argument inplace=FalseTrue has been replaced with copy=TrueFalse. 
153  
154 
Subgraph no longer takes create_using keyword. To change the graph 
155 
type either make a copy of 
156 
the graph first and then change type or change type and make 
157 
a subgraph. E.g. 
158  
159 
>>> G=nx.path_graph(5) 
160 
>>> H=nx.DiGraph(G.subgraph([0,1])) # digraph of copy of induced subgraph 
161  
162 
__getitem__() 
163 
^^^^^^^^^^^^^ 
164 
Getting node neighbors from the graph with G[v] now returns 
165 
a dictionary. 
166  
167 
>>> G=nx.path_graph(5) 
168 
>>> # G[0] 
169 
# {1: 1} 
170  
171 
To get a list of neighbors you can either use the keys of that 
172 
dictionary or use 
173  
174 
>>> G.neighbors(0) # doctest: +SKIP 
175 
[1] 
176 

177 
This change allows algorithms to use the underlying dictofdict 
178 
representation through G[v] for substantial performance gains. 
179 
Warning: The returned dictionary should not be modified as it may 
180 
corrupt the graph data structure. Make a copy G[v].copy() if you 
181 
wish to modify the dict. 
182  
183  
184 
Methods removed 
185 
 
186  
187 
info() 
188 
^^^^^^ 
189 
now a function 
190  
191 
>>> G=nx.Graph(name='test me') 
192 
>>> nx.info(G) # doctest: +SKIP 
193 
Name: test me 
194 
Type: Graph 
195 
Number of nodes: 0 
196 
Number of edges: 0 
197  
198  
199 
node_boundary() 
200 
^^^^^^^^^^^^^^^ 
201 
now a function 
202  
203 
edge_boundary() 
204 
^^^^^^^^^^^^^^^ 
205 
now a function 
206  
207 
is_directed() 
208 
^^^^^^^^^^^^^ 
209 
use the directed attribute 
210  
211 
>>> G=nx.DiGraph() 
212 
>>> # G.directed 
213 
# True 
214  
215 
G.out_edges() 
216 
^^^^^^^^^^^^^ 
217 
use G.edges() 
218  
219 
G.in_edges() 
220 
^^^^^^^^^^^^ 
221 
use 
222  
223 
>>> G = nx.DiGraph() 
224 
>>> R = G.reverse() 
225 
>>> R.edges() # doctest: +SKIP 
226 
[] 
227  
228 
or 
229  
230 
>>> [(v,u) for (u,v) in G.edges()] 
231 
[] 
232  
233 
Methods added 
234 
 
235  
236 
adjacency_list() 
237 
^^^^^^^^^^^^^^^^ 
238 
Returns a listoflists adjacency list representation of the graph. 
239  
240 
adjacency_iter() 
241 
^^^^^^^^^^^^^^^^ 
242 
Returns an iterator of (node, adjacency_dict[node]) over all 
243 
nodes in the graph. Intended for fast access to the internal 
244 
data structure for use in internal algorithms. 
245  
246  
247 
Other possible incompatibilities with existing code 
248 
=================================================== 
249  
250 
Imports 
251 
 
252 
Some of the code modules were moved into subdirectories. 
253  
254 
Import statements such as:: 
255  
256 
import networkx.centrality 
257 
from networkx.centrality import * 
258  
259 
may no longer work (including that example). 
260  
261 
Use either 
262  
263 
>>> import networkx # e.g. centrality functions available as networkx.fcn() 
264  
265 
or 
266  
267 
>>> from networkx import * # e.g. centrality functions available as fcn() 
268  
269 
Selfloops 
270 
 
271 
For Graph and DiGraph self loops are now allowed. 
272 
This might affect code or algorithms that add self loops 
273 
which were intended to be ignored. 
274  
275 
Use the methods 
276  
277 
 nodes_with_selfloops() 
278 
 selfloop_edges() 
279 
 number_of_selfloops() 
280  
281 
to discover any self loops. 
282  
283 
Copy 
284 
 
285 
Copies of NetworkX graphs including using the copy() method 
286 
now return complete copies of the graph. This means that all 
287 
connection information is copiedsubsequent changes in the 
288 
copy do not change the old graph. But node keys and edge 
289 
data in the original and copy graphs are pointers to the same data. 
290  
291 
prepare_nbunch 
292 
 
293 
Used internally  now called nbunch_iter and returns an iterator. 
294  
295  
296 
Converting your old code to Version 0.99 
297 
======================================== 
298  
299 
Mostly you can just run the code and python will raise an exception 
300 
for features that changed. Common places for changes are 
301  
302 
 Converting XGraph() to either Graph or MultiGraph 
303 
 Converting XGraph.edges() to Graph.edges(data=True) 
304 
 Switching some rarely used methods to attributes (e.g. directed) 
305 
or to functions (e.g. node_boundary) 
306 
 If you relied on the old default edge data being None, you will 
307 
have to account for it now being 1. 
308  
309 
You may also want to look through your code for places which could 
310 
improve speed or readability. The iterators are helpful with large 
311 
graphs and getting edge data via G[u][v] is quite fast. You may also 
312 
want to change G.neighbors(n) to G[n] which returns the dict keyed by 
313 
neighbor nodes to the edge data. It is faster for many purposes but 
314 
does not work well when you are changing the graph. 
315 