Statistics
| Branch: | Revision:

iof-tools / networkxMiCe / networkx-master / 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 networkx-0.99 is the penultimate release before
6
networkx-1.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 networkx-discuss mailing list.
16
http://groups.google.com/group/networkx-discuss
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=True|False.
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=True|False keyword determines whether to return
54
   two-tuples (u,v) (False) or three-tuples (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 2-tuples (u,v),
112
   3-tuples (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 2-tuple.
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=False|True for weighted degree.
149

    
150
subgraph()
151
^^^^^^^^^^
152
   The argument inplace=False|True has been replaced with copy=True|False.     
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 dict-of-dict
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 list-of-lists 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
Self-loops
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 copied--subsequent 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