Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""Base class for MultiDiGraph."""
3from copy import deepcopy
4from functools import cached_property
6import networkx as nx
7from networkx import convert
8from networkx.classes.coreviews import MultiAdjacencyView
9from networkx.classes.digraph import DiGraph
10from networkx.classes.multigraph import MultiGraph
11from networkx.classes.reportviews import (
12 DiMultiDegreeView,
13 InMultiDegreeView,
14 InMultiEdgeView,
15 OutMultiDegreeView,
16 OutMultiEdgeView,
17)
18from networkx.exception import NetworkXError
20__all__ = ["MultiDiGraph"]
23class MultiDiGraph(MultiGraph, DiGraph):
24 """A directed graph class that can store multiedges.
26 Multiedges are multiple edges between two nodes. Each edge
27 can hold optional data or attributes.
29 A MultiDiGraph holds directed edges. Self loops are allowed.
31 Nodes can be arbitrary (hashable) Python objects with optional
32 key/value attributes. By convention `None` is not used as a node.
34 Edges are represented as links between nodes with optional
35 key/value attributes.
37 Parameters
38 ----------
39 incoming_graph_data : input graph (optional, default: None)
40 Data to initialize graph. If None (default) an empty
41 graph is created. The data can be any format that is supported
42 by the to_networkx_graph() function, currently including edge list,
43 dict of dicts, dict of lists, NetworkX graph, 2D NumPy array, SciPy
44 sparse matrix, or PyGraphviz graph.
46 multigraph_input : bool or None (default None)
47 Note: Only used when `incoming_graph_data` is a dict.
48 If True, `incoming_graph_data` is assumed to be a
49 dict-of-dict-of-dict-of-dict structure keyed by
50 node to neighbor to edge keys to edge data for multi-edges.
51 A NetworkXError is raised if this is not the case.
52 If False, :func:`to_networkx_graph` is used to try to determine
53 the dict's graph data structure as either a dict-of-dict-of-dict
54 keyed by node to neighbor to edge data, or a dict-of-iterable
55 keyed by node to neighbors.
56 If None, the treatment for True is tried, but if it fails,
57 the treatment for False is tried.
59 attr : keyword arguments, optional (default= no attributes)
60 Attributes to add to graph as key=value pairs.
62 See Also
63 --------
64 Graph
65 DiGraph
66 MultiGraph
68 Examples
69 --------
70 Create an empty graph structure (a "null graph") with no nodes and
71 no edges.
73 >>> G = nx.MultiDiGraph()
75 G can be grown in several ways.
77 **Nodes:**
79 Add one node at a time:
81 >>> G.add_node(1)
83 Add the nodes from any container (a list, dict, set or
84 even the lines from a file or the nodes from another graph).
86 >>> G.add_nodes_from([2, 3])
87 >>> G.add_nodes_from(range(100, 110))
88 >>> H = nx.path_graph(10)
89 >>> G.add_nodes_from(H)
91 In addition to strings and integers any hashable Python object
92 (except None) can represent a node, e.g. a customized node object,
93 or even another Graph.
95 >>> G.add_node(H)
97 **Edges:**
99 G can also be grown by adding edges.
101 Add one edge,
103 >>> key = G.add_edge(1, 2)
105 a list of edges,
107 >>> keys = G.add_edges_from([(1, 2), (1, 3)])
109 or a collection of edges,
111 >>> keys = G.add_edges_from(H.edges)
113 If some edges connect nodes not yet in the graph, the nodes
114 are added automatically. If an edge already exists, an additional
115 edge is created and stored using a key to identify the edge.
116 By default the key is the lowest unused integer.
118 >>> keys = G.add_edges_from([(4, 5, dict(route=282)), (4, 5, dict(route=37))])
119 >>> G[4]
120 AdjacencyView({5: {0: {}, 1: {'route': 282}, 2: {'route': 37}}})
122 **Attributes:**
124 Each graph, node, and edge can hold key/value attribute pairs
125 in an associated attribute dictionary (the keys must be hashable).
126 By default these are empty, but can be added or changed using
127 add_edge, add_node or direct manipulation of the attribute
128 dictionaries named graph, node and edge respectively.
130 >>> G = nx.MultiDiGraph(day="Friday")
131 >>> G.graph
132 {'day': 'Friday'}
134 Add node attributes using add_node(), add_nodes_from() or G.nodes
136 >>> G.add_node(1, time="5pm")
137 >>> G.add_nodes_from([3], time="2pm")
138 >>> G.nodes[1]
139 {'time': '5pm'}
140 >>> G.nodes[1]["room"] = 714
141 >>> del G.nodes[1]["room"] # remove attribute
142 >>> list(G.nodes(data=True))
143 [(1, {'time': '5pm'}), (3, {'time': '2pm'})]
145 Add edge attributes using add_edge(), add_edges_from(), subscript
146 notation, or G.edges.
148 >>> key = G.add_edge(1, 2, weight=4.7)
149 >>> keys = G.add_edges_from([(3, 4), (4, 5)], color="red")
150 >>> keys = G.add_edges_from([(1, 2, {"color": "blue"}), (2, 3, {"weight": 8})])
151 >>> G[1][2][0]["weight"] = 4.7
152 >>> G.edges[1, 2, 0]["weight"] = 4
154 Warning: we protect the graph data structure by making `G.edges[1,
155 2, 0]` a read-only dict-like structure. However, you can assign to
156 attributes in e.g. `G.edges[1, 2, 0]`. Thus, use 2 sets of brackets
157 to add/change data attributes: `G.edges[1, 2, 0]['weight'] = 4`
158 (for multigraphs the edge key is required: `MG.edges[u, v,
159 key][name] = value`).
161 **Shortcuts:**
163 Many common graph features allow python syntax to speed reporting.
165 >>> 1 in G # check if node in graph
166 True
167 >>> [n for n in G if n < 3] # iterate through nodes
168 [1, 2]
169 >>> len(G) # number of nodes in graph
170 5
171 >>> G[1] # adjacency dict-like view mapping neighbor -> edge key -> edge attributes
172 AdjacencyView({2: {0: {'weight': 4}, 1: {'color': 'blue'}}})
174 Often the best way to traverse all edges of a graph is via the neighbors.
175 The neighbors are available as an adjacency-view `G.adj` object or via
176 the method `G.adjacency()`.
178 >>> for n, nbrsdict in G.adjacency():
179 ... for nbr, keydict in nbrsdict.items():
180 ... for key, eattr in keydict.items():
181 ... if "weight" in eattr:
182 ... # Do something useful with the edges
183 ... pass
185 But the edges() method is often more convenient:
187 >>> for u, v, keys, weight in G.edges(data="weight", keys=True):
188 ... if weight is not None:
189 ... # Do something useful with the edges
190 ... pass
192 **Reporting:**
194 Simple graph information is obtained using methods and object-attributes.
195 Reporting usually provides views instead of containers to reduce memory
196 usage. The views update as the graph is updated similarly to dict-views.
197 The objects `nodes`, `edges` and `adj` provide access to data attributes
198 via lookup (e.g. `nodes[n]`, `edges[u, v, k]`, `adj[u][v]`) and iteration
199 (e.g. `nodes.items()`, `nodes.data('color')`,
200 `nodes.data('color', default='blue')` and similarly for `edges`)
201 Views exist for `nodes`, `edges`, `neighbors()`/`adj` and `degree`.
203 For details on these and other miscellaneous methods, see below.
205 **Subclasses (Advanced):**
207 The MultiDiGraph class uses a dict-of-dict-of-dict-of-dict structure.
208 The outer dict (node_dict) holds adjacency information keyed by node.
209 The next dict (adjlist_dict) represents the adjacency information
210 and holds edge_key dicts keyed by neighbor. The edge_key dict holds
211 each edge_attr dict keyed by edge key. The inner dict
212 (edge_attr_dict) represents the edge data and holds edge attribute
213 values keyed by attribute names.
215 Each of these four dicts in the dict-of-dict-of-dict-of-dict
216 structure can be replaced by a user defined dict-like object.
217 In general, the dict-like features should be maintained but
218 extra features can be added. To replace one of the dicts create
219 a new graph class by changing the class(!) variable holding the
220 factory for that dict-like structure. The variable names are
221 node_dict_factory, node_attr_dict_factory, adjlist_inner_dict_factory,
222 adjlist_outer_dict_factory, edge_key_dict_factory, edge_attr_dict_factory
223 and graph_attr_dict_factory.
225 node_dict_factory : function, (default: dict)
226 Factory function to be used to create the dict containing node
227 attributes, keyed by node id.
228 It should require no arguments and return a dict-like object
230 node_attr_dict_factory: function, (default: dict)
231 Factory function to be used to create the node attribute
232 dict which holds attribute values keyed by attribute name.
233 It should require no arguments and return a dict-like object
235 adjlist_outer_dict_factory : function, (default: dict)
236 Factory function to be used to create the outer-most dict
237 in the data structure that holds adjacency info keyed by node.
238 It should require no arguments and return a dict-like object.
240 adjlist_inner_dict_factory : function, (default: dict)
241 Factory function to be used to create the adjacency list
242 dict which holds multiedge key dicts keyed by neighbor.
243 It should require no arguments and return a dict-like object.
245 edge_key_dict_factory : function, (default: dict)
246 Factory function to be used to create the edge key dict
247 which holds edge data keyed by edge key.
248 It should require no arguments and return a dict-like object.
250 edge_attr_dict_factory : function, (default: dict)
251 Factory function to be used to create the edge attribute
252 dict which holds attribute values keyed by attribute name.
253 It should require no arguments and return a dict-like object.
255 graph_attr_dict_factory : function, (default: dict)
256 Factory function to be used to create the graph attribute
257 dict which holds attribute values keyed by attribute name.
258 It should require no arguments and return a dict-like object.
260 Typically, if your extension doesn't impact the data structure all
261 methods will inherited without issue except: `to_directed/to_undirected`.
262 By default these methods create a DiGraph/Graph class and you probably
263 want them to create your extension of a DiGraph/Graph. To facilitate
264 this we define two class variables that you can set in your subclass.
266 to_directed_class : callable, (default: DiGraph or MultiDiGraph)
267 Class to create a new graph structure in the `to_directed` method.
268 If `None`, a NetworkX class (DiGraph or MultiDiGraph) is used.
270 to_undirected_class : callable, (default: Graph or MultiGraph)
271 Class to create a new graph structure in the `to_undirected` method.
272 If `None`, a NetworkX class (Graph or MultiGraph) is used.
274 **Subclassing Example**
276 Create a low memory graph class that effectively disallows edge
277 attributes by using a single attribute dict for all edges.
278 This reduces the memory used, but you lose edge attributes.
280 >>> class ThinGraph(nx.Graph):
281 ... all_edge_dict = {"weight": 1}
282 ...
283 ... def single_edge_dict(self):
284 ... return self.all_edge_dict
285 ...
286 ... edge_attr_dict_factory = single_edge_dict
287 >>> G = ThinGraph()
288 >>> G.add_edge(2, 1)
289 >>> G[2][1]
290 {'weight': 1}
291 >>> G.add_edge(2, 2)
292 >>> G[2][1] is G[2][2]
293 True
294 """
296 # node_dict_factory = dict # already assigned in Graph
297 # adjlist_outer_dict_factory = dict
298 # adjlist_inner_dict_factory = dict
299 edge_key_dict_factory = dict
300 # edge_attr_dict_factory = dict
302 def __init__(self, incoming_graph_data=None, multigraph_input=None, **attr):
303 """Initialize a graph with edges, name, or graph attributes.
305 Parameters
306 ----------
307 incoming_graph_data : input graph
308 Data to initialize graph. If incoming_graph_data=None (default)
309 an empty graph is created. The data can be an edge list, or any
310 NetworkX graph object. If the corresponding optional Python
311 packages are installed the data can also be a 2D NumPy array, a
312 SciPy sparse array, or a PyGraphviz graph.
314 multigraph_input : bool or None (default None)
315 Note: Only used when `incoming_graph_data` is a dict.
316 If True, `incoming_graph_data` is assumed to be a
317 dict-of-dict-of-dict-of-dict structure keyed by
318 node to neighbor to edge keys to edge data for multi-edges.
319 A NetworkXError is raised if this is not the case.
320 If False, :func:`to_networkx_graph` is used to try to determine
321 the dict's graph data structure as either a dict-of-dict-of-dict
322 keyed by node to neighbor to edge data, or a dict-of-iterable
323 keyed by node to neighbors.
324 If None, the treatment for True is tried, but if it fails,
325 the treatment for False is tried.
327 attr : keyword arguments, optional (default= no attributes)
328 Attributes to add to graph as key=value pairs.
330 See Also
331 --------
332 convert
334 Examples
335 --------
336 >>> G = nx.Graph() # or DiGraph, MultiGraph, MultiDiGraph, etc
337 >>> G = nx.Graph(name="my graph")
338 >>> e = [(1, 2), (2, 3), (3, 4)] # list of edges
339 >>> G = nx.Graph(e)
341 Arbitrary graph attribute pairs (key=value) may be assigned
343 >>> G = nx.Graph(e, day="Friday")
344 >>> G.graph
345 {'day': 'Friday'}
347 """
348 # multigraph_input can be None/True/False. So check "is not False"
349 if isinstance(incoming_graph_data, dict) and multigraph_input is not False:
350 DiGraph.__init__(self)
351 try:
352 convert.from_dict_of_dicts(
353 incoming_graph_data, create_using=self, multigraph_input=True
354 )
355 self.graph.update(attr)
356 except Exception as err:
357 if multigraph_input is True:
358 raise nx.NetworkXError(
359 f"converting multigraph_input raised:\n{type(err)}: {err}"
360 )
361 DiGraph.__init__(self, incoming_graph_data, **attr)
362 else:
363 DiGraph.__init__(self, incoming_graph_data, **attr)
365 @cached_property
366 def adj(self):
367 """Graph adjacency object holding the neighbors of each node.
369 This object is a read-only dict-like structure with node keys
370 and neighbor-dict values. The neighbor-dict is keyed by neighbor
371 to the edgekey-dict. So `G.adj[3][2][0]['color'] = 'blue'` sets
372 the color of the edge `(3, 2, 0)` to `"blue"`.
374 Iterating over G.adj behaves like a dict. Useful idioms include
375 `for nbr, datadict in G.adj[n].items():`.
377 The neighbor information is also provided by subscripting the graph.
378 So `for nbr, foovalue in G[node].data('foo', default=1):` works.
380 For directed graphs, `G.adj` holds outgoing (successor) info.
381 """
382 return MultiAdjacencyView(self._succ)
384 @cached_property
385 def succ(self):
386 """Graph adjacency object holding the successors of each node.
388 This object is a read-only dict-like structure with node keys
389 and neighbor-dict values. The neighbor-dict is keyed by neighbor
390 to the edgekey-dict. So `G.adj[3][2][0]['color'] = 'blue'` sets
391 the color of the edge `(3, 2, 0)` to `"blue"`.
393 Iterating over G.adj behaves like a dict. Useful idioms include
394 `for nbr, datadict in G.adj[n].items():`.
396 The neighbor information is also provided by subscripting the graph.
397 So `for nbr, foovalue in G[node].data('foo', default=1):` works.
399 For directed graphs, `G.succ` is identical to `G.adj`.
400 """
401 return MultiAdjacencyView(self._succ)
403 @cached_property
404 def pred(self):
405 """Graph adjacency object holding the predecessors of each node.
407 This object is a read-only dict-like structure with node keys
408 and neighbor-dict values. The neighbor-dict is keyed by neighbor
409 to the edgekey-dict. So `G.adj[3][2][0]['color'] = 'blue'` sets
410 the color of the edge `(3, 2, 0)` to `"blue"`.
412 Iterating over G.adj behaves like a dict. Useful idioms include
413 `for nbr, datadict in G.adj[n].items():`.
414 """
415 return MultiAdjacencyView(self._pred)
417 def add_edge(self, u_for_edge, v_for_edge, key=None, **attr):
418 """Add an edge between u and v.
420 The nodes u and v will be automatically added if they are
421 not already in the graph.
423 Edge attributes can be specified with keywords or by directly
424 accessing the edge's attribute dictionary. See examples below.
426 Parameters
427 ----------
428 u_for_edge, v_for_edge : nodes
429 Nodes can be, for example, strings or numbers.
430 Nodes must be hashable (and not None) Python objects.
431 key : hashable identifier, optional (default=lowest unused integer)
432 Used to distinguish multiedges between a pair of nodes.
433 attr : keyword arguments, optional
434 Edge data (or labels or objects) can be assigned using
435 keyword arguments.
437 Returns
438 -------
439 The edge key assigned to the edge.
441 See Also
442 --------
443 add_edges_from : add a collection of edges
445 Notes
446 -----
447 To replace/update edge data, use the optional key argument
448 to identify a unique edge. Otherwise a new edge will be created.
450 NetworkX algorithms designed for weighted graphs cannot use
451 multigraphs directly because it is not clear how to handle
452 multiedge weights. Convert to Graph using edge attribute
453 'weight' to enable weighted graph algorithms.
455 Default keys are generated using the method `new_edge_key()`.
456 This method can be overridden by subclassing the base class and
457 providing a custom `new_edge_key()` method.
459 Examples
460 --------
461 The following all add the edge e=(1, 2) to graph G:
463 >>> G = nx.MultiDiGraph()
464 >>> e = (1, 2)
465 >>> key = G.add_edge(1, 2) # explicit two-node form
466 >>> G.add_edge(*e) # single edge as tuple of two nodes
467 1
468 >>> G.add_edges_from([(1, 2)]) # add edges from iterable container
469 [2]
471 Associate data to edges using keywords:
473 >>> key = G.add_edge(1, 2, weight=3)
474 >>> key = G.add_edge(1, 2, key=0, weight=4) # update data for key=0
475 >>> key = G.add_edge(1, 3, weight=7, capacity=15, length=342.7)
477 For non-string attribute keys, use subscript notation.
479 >>> ekey = G.add_edge(1, 2)
480 >>> G[1][2][0].update({0: 5})
481 >>> G.edges[1, 2, 0].update({0: 5})
482 """
483 u, v = u_for_edge, v_for_edge
484 # add nodes
485 if u not in self._succ:
486 if u is None:
487 raise ValueError("None cannot be a node")
488 self._succ[u] = self.adjlist_inner_dict_factory()
489 self._pred[u] = self.adjlist_inner_dict_factory()
490 self._node[u] = self.node_attr_dict_factory()
491 if v not in self._succ:
492 if v is None:
493 raise ValueError("None cannot be a node")
494 self._succ[v] = self.adjlist_inner_dict_factory()
495 self._pred[v] = self.adjlist_inner_dict_factory()
496 self._node[v] = self.node_attr_dict_factory()
497 if key is None:
498 key = self.new_edge_key(u, v)
499 if v in self._succ[u]:
500 keydict = self._adj[u][v]
501 datadict = keydict.get(key, self.edge_attr_dict_factory())
502 datadict.update(attr)
503 keydict[key] = datadict
504 else:
505 # selfloops work this way without special treatment
506 datadict = self.edge_attr_dict_factory()
507 datadict.update(attr)
508 keydict = self.edge_key_dict_factory()
509 keydict[key] = datadict
510 self._succ[u][v] = keydict
511 self._pred[v][u] = keydict
512 nx._clear_cache(self)
513 return key
515 def remove_edge(self, u, v, key=None):
516 """Remove an edge between u and v.
518 Parameters
519 ----------
520 u, v : nodes
521 Remove an edge between nodes u and v.
522 key : hashable identifier, optional (default=None)
523 Used to distinguish multiple edges between a pair of nodes.
524 If None, remove a single edge between u and v. If there are
525 multiple edges, removes the last edge added in terms of
526 insertion order.
528 Raises
529 ------
530 NetworkXError
531 If there is not an edge between u and v, or
532 if there is no edge with the specified key.
534 See Also
535 --------
536 remove_edges_from : remove a collection of edges
538 Examples
539 --------
540 >>> G = nx.MultiDiGraph()
541 >>> nx.add_path(G, [0, 1, 2, 3])
542 >>> G.remove_edge(0, 1)
543 >>> e = (1, 2)
544 >>> G.remove_edge(*e) # unpacks e from an edge tuple
546 For multiple edges
548 >>> G = nx.MultiDiGraph()
549 >>> G.add_edges_from([(1, 2), (1, 2), (1, 2)]) # key_list returned
550 [0, 1, 2]
552 When ``key=None`` (the default), edges are removed in the opposite
553 order that they were added:
555 >>> G.remove_edge(1, 2)
556 >>> G.edges(keys=True)
557 OutMultiEdgeView([(1, 2, 0), (1, 2, 1)])
559 For edges with keys
561 >>> G = nx.MultiDiGraph()
562 >>> G.add_edge(1, 2, key="first")
563 'first'
564 >>> G.add_edge(1, 2, key="second")
565 'second'
566 >>> G.remove_edge(1, 2, key="first")
567 >>> G.edges(keys=True)
568 OutMultiEdgeView([(1, 2, 'second')])
570 """
571 try:
572 d = self._adj[u][v]
573 except KeyError as err:
574 raise NetworkXError(f"The edge {u}-{v} is not in the graph.") from err
575 # remove the edge with specified data
576 if key is None:
577 d.popitem()
578 else:
579 try:
580 del d[key]
581 except KeyError as err:
582 msg = f"The edge {u}-{v} with key {key} is not in the graph."
583 raise NetworkXError(msg) from err
584 if len(d) == 0:
585 # remove the key entries if last edge
586 del self._succ[u][v]
587 del self._pred[v][u]
588 nx._clear_cache(self)
590 @cached_property
591 def edges(self):
592 """An OutMultiEdgeView of the Graph as G.edges or G.edges().
594 edges(self, nbunch=None, data=False, keys=False, default=None)
596 The OutMultiEdgeView provides set-like operations on the edge-tuples
597 as well as edge attribute lookup. When called, it also provides
598 an EdgeDataView object which allows control of access to edge
599 attributes (but does not provide set-like operations).
600 Hence, ``G.edges[u, v, k]['color']`` provides the value of the color
601 attribute for the edge from ``u`` to ``v`` with key ``k`` while
602 ``for (u, v, k, c) in G.edges(data='color', default='red', keys=True):``
603 iterates through all the edges yielding the color attribute with
604 default `'red'` if no color attribute exists.
606 Edges are returned as tuples with optional data and keys
607 in the order (node, neighbor, key, data). If ``keys=True`` is not
608 provided, the tuples will just be (node, neighbor, data), but
609 multiple tuples with the same node and neighbor will be
610 generated when multiple edges between two nodes exist.
612 Parameters
613 ----------
614 nbunch : single node, container, or all nodes (default= all nodes)
615 The view will only report edges from these nodes.
616 data : string or bool, optional (default=False)
617 The edge attribute returned in 3-tuple (u, v, ddict[data]).
618 If True, return edge attribute dict in 3-tuple (u, v, ddict).
619 If False, return 2-tuple (u, v).
620 keys : bool, optional (default=False)
621 If True, return edge keys with each edge, creating (u, v, k,
622 d) tuples when data is also requested (the default) and (u,
623 v, k) tuples when data is not requested.
624 default : value, optional (default=None)
625 Value used for edges that don't have the requested attribute.
626 Only relevant if data is not True or False.
628 Returns
629 -------
630 edges : OutMultiEdgeView
631 A view of edge attributes, usually it iterates over (u, v)
632 (u, v, k) or (u, v, k, d) tuples of edges, but can also be
633 used for attribute lookup as ``edges[u, v, k]['foo']``.
635 Notes
636 -----
637 Nodes in nbunch that are not in the graph will be (quietly) ignored.
638 For directed graphs this returns the out-edges.
640 Examples
641 --------
642 >>> G = nx.MultiDiGraph()
643 >>> nx.add_path(G, [0, 1, 2])
644 >>> key = G.add_edge(2, 3, weight=5)
645 >>> key2 = G.add_edge(1, 2) # second edge between these nodes
646 >>> [e for e in G.edges()]
647 [(0, 1), (1, 2), (1, 2), (2, 3)]
648 >>> list(G.edges(data=True)) # default data is {} (empty dict)
649 [(0, 1, {}), (1, 2, {}), (1, 2, {}), (2, 3, {'weight': 5})]
650 >>> list(G.edges(data="weight", default=1))
651 [(0, 1, 1), (1, 2, 1), (1, 2, 1), (2, 3, 5)]
652 >>> list(G.edges(keys=True)) # default keys are integers
653 [(0, 1, 0), (1, 2, 0), (1, 2, 1), (2, 3, 0)]
654 >>> list(G.edges(data=True, keys=True))
655 [(0, 1, 0, {}), (1, 2, 0, {}), (1, 2, 1, {}), (2, 3, 0, {'weight': 5})]
656 >>> list(G.edges(data="weight", default=1, keys=True))
657 [(0, 1, 0, 1), (1, 2, 0, 1), (1, 2, 1, 1), (2, 3, 0, 5)]
658 >>> list(G.edges([0, 2]))
659 [(0, 1), (2, 3)]
660 >>> list(G.edges(0))
661 [(0, 1)]
662 >>> list(G.edges(1))
663 [(1, 2), (1, 2)]
665 See Also
666 --------
667 in_edges, out_edges
668 """
669 return OutMultiEdgeView(self)
671 # alias out_edges to edges
672 @cached_property
673 def out_edges(self):
674 return OutMultiEdgeView(self)
676 out_edges.__doc__ = edges.__doc__
678 @cached_property
679 def in_edges(self):
680 """A view of the in edges of the graph as G.in_edges or G.in_edges().
682 in_edges(self, nbunch=None, data=False, keys=False, default=None)
684 Parameters
685 ----------
686 nbunch : single node, container, or all nodes (default= all nodes)
687 The view will only report edges incident to these nodes.
688 data : string or bool, optional (default=False)
689 The edge attribute returned in 3-tuple (u, v, ddict[data]).
690 If True, return edge attribute dict in 3-tuple (u, v, ddict).
691 If False, return 2-tuple (u, v).
692 keys : bool, optional (default=False)
693 If True, return edge keys with each edge, creating 3-tuples
694 (u, v, k) or with data, 4-tuples (u, v, k, d).
695 default : value, optional (default=None)
696 Value used for edges that don't have the requested attribute.
697 Only relevant if data is not True or False.
699 Returns
700 -------
701 in_edges : InMultiEdgeView or InMultiEdgeDataView
702 A view of edge attributes, usually it iterates over (u, v)
703 or (u, v, k) or (u, v, k, d) tuples of edges, but can also be
704 used for attribute lookup as `edges[u, v, k]['foo']`.
706 See Also
707 --------
708 edges
709 """
710 return InMultiEdgeView(self)
712 @cached_property
713 def degree(self):
714 """A DegreeView for the Graph as G.degree or G.degree().
716 The node degree is the number of edges adjacent to the node.
717 The weighted node degree is the sum of the edge weights for
718 edges incident to that node.
720 This object provides an iterator for (node, degree) as well as
721 lookup for the degree for a single node.
723 Parameters
724 ----------
725 nbunch : single node, container, or all nodes (default= all nodes)
726 The view will only report edges incident to these nodes.
728 weight : string or None, optional (default=None)
729 The name of an edge attribute that holds the numerical value used
730 as a weight. If None, then each edge has weight 1.
731 The degree is the sum of the edge weights adjacent to the node.
733 Returns
734 -------
735 DiMultiDegreeView or int
736 If multiple nodes are requested (the default), returns a `DiMultiDegreeView`
737 mapping nodes to their degree.
738 If a single node is requested, returns the degree of the node as an integer.
740 See Also
741 --------
742 out_degree, in_degree
744 Examples
745 --------
746 >>> G = nx.MultiDiGraph()
747 >>> nx.add_path(G, [0, 1, 2, 3])
748 >>> G.degree(0) # node 0 with degree 1
749 1
750 >>> list(G.degree([0, 1, 2]))
751 [(0, 1), (1, 2), (2, 2)]
752 >>> G.add_edge(0, 1) # parallel edge
753 1
754 >>> list(G.degree([0, 1, 2])) # parallel edges are counted
755 [(0, 2), (1, 3), (2, 2)]
757 """
758 return DiMultiDegreeView(self)
760 @cached_property
761 def in_degree(self):
762 """A DegreeView for (node, in_degree) or in_degree for single node.
764 The node in-degree is the number of edges pointing into the node.
765 The weighted node degree is the sum of the edge weights for
766 edges incident to that node.
768 This object provides an iterator for (node, degree) as well as
769 lookup for the degree for a single node.
771 Parameters
772 ----------
773 nbunch : single node, container, or all nodes (default= all nodes)
774 The view will only report edges incident to these nodes.
776 weight : string or None, optional (default=None)
777 The edge attribute that holds the numerical value used
778 as a weight. If None, then each edge has weight 1.
779 The degree is the sum of the edge weights adjacent to the node.
781 Returns
782 -------
783 If a single node is requested
784 deg : int
785 Degree of the node
787 OR if multiple nodes are requested
788 nd_iter : iterator
789 The iterator returns two-tuples of (node, in-degree).
791 See Also
792 --------
793 degree, out_degree
795 Examples
796 --------
797 >>> G = nx.MultiDiGraph()
798 >>> nx.add_path(G, [0, 1, 2, 3])
799 >>> G.in_degree(0) # node 0 with degree 0
800 0
801 >>> list(G.in_degree([0, 1, 2]))
802 [(0, 0), (1, 1), (2, 1)]
803 >>> G.add_edge(0, 1) # parallel edge
804 1
805 >>> list(G.in_degree([0, 1, 2])) # parallel edges counted
806 [(0, 0), (1, 2), (2, 1)]
808 """
809 return InMultiDegreeView(self)
811 @cached_property
812 def out_degree(self):
813 """Returns an iterator for (node, out-degree) or out-degree for single node.
815 out_degree(self, nbunch=None, weight=None)
817 The node out-degree is the number of edges pointing out of the node.
818 This function returns the out-degree for a single node or an iterator
819 for a bunch of nodes or if nothing is passed as argument.
821 Parameters
822 ----------
823 nbunch : single node, container, or all nodes (default= all nodes)
824 The view will only report edges incident to these nodes.
826 weight : string or None, optional (default=None)
827 The edge attribute that holds the numerical value used
828 as a weight. If None, then each edge has weight 1.
829 The degree is the sum of the edge weights.
831 Returns
832 -------
833 If a single node is requested
834 deg : int
835 Degree of the node
837 OR if multiple nodes are requested
838 nd_iter : iterator
839 The iterator returns two-tuples of (node, out-degree).
841 See Also
842 --------
843 degree, in_degree
845 Examples
846 --------
847 >>> G = nx.MultiDiGraph()
848 >>> nx.add_path(G, [0, 1, 2, 3])
849 >>> G.out_degree(0) # node 0 with degree 1
850 1
851 >>> list(G.out_degree([0, 1, 2]))
852 [(0, 1), (1, 1), (2, 1)]
853 >>> G.add_edge(0, 1) # parallel edge
854 1
855 >>> list(G.out_degree([0, 1, 2])) # counts parallel edges
856 [(0, 2), (1, 1), (2, 1)]
858 """
859 return OutMultiDegreeView(self)
861 def is_multigraph(self):
862 """Returns True if graph is a multigraph, False otherwise."""
863 return True
865 def is_directed(self):
866 """Returns True if graph is directed, False otherwise."""
867 return True
869 def to_undirected(self, reciprocal=False, as_view=False):
870 """Returns an undirected representation of the digraph.
872 Parameters
873 ----------
874 reciprocal : bool (optional)
875 If True only keep edges that appear in both directions
876 in the original digraph.
877 as_view : bool (optional, default=False)
878 If True return an undirected view of the original directed graph.
880 Returns
881 -------
882 G : MultiGraph
883 An undirected graph with the same name and nodes and
884 with edge (u, v, data) if either (u, v, data) or (v, u, data)
885 is in the digraph. If both edges exist in digraph and
886 their edge data is different, only one edge is created
887 with an arbitrary choice of which edge data to use.
888 You must check and correct for this manually if desired.
890 See Also
891 --------
892 MultiGraph, copy, add_edge, add_edges_from
894 Notes
895 -----
896 This returns a "deepcopy" of the edge, node, and
897 graph attributes which attempts to completely copy
898 all of the data and references.
900 This is in contrast to the similar D=MultiDiGraph(G) which
901 returns a shallow copy of the data.
903 See the Python copy module for more information on shallow
904 and deep copies, https://docs.python.org/3/library/copy.html.
906 Warning: If you have subclassed MultiDiGraph to use dict-like
907 objects in the data structure, those changes do not transfer
908 to the MultiGraph created by this method.
910 Examples
911 --------
912 >>> G = nx.path_graph(2) # or MultiGraph, etc
913 >>> H = G.to_directed()
914 >>> list(H.edges)
915 [(0, 1), (1, 0)]
916 >>> G2 = H.to_undirected()
917 >>> list(G2.edges)
918 [(0, 1)]
919 """
920 graph_class = self.to_undirected_class()
921 if as_view is True:
922 return nx.graphviews.generic_graph_view(self, graph_class)
923 # deepcopy when not a view
924 G = graph_class()
925 G.graph.update(deepcopy(self.graph))
926 G.add_nodes_from((n, deepcopy(d)) for n, d in self._node.items())
927 if reciprocal is True:
928 G.add_edges_from(
929 (u, v, key, deepcopy(data))
930 for u, nbrs in self._adj.items()
931 for v, keydict in nbrs.items()
932 for key, data in keydict.items()
933 if v in self._pred[u] and key in self._pred[u][v]
934 )
935 else:
936 G.add_edges_from(
937 (u, v, key, deepcopy(data))
938 for u, nbrs in self._adj.items()
939 for v, keydict in nbrs.items()
940 for key, data in keydict.items()
941 )
942 return G
944 def reverse(self, copy=True):
945 """Returns the reverse of the graph.
947 The reverse is a graph with the same nodes and edges
948 but with the directions of the edges reversed.
950 Parameters
951 ----------
952 copy : bool optional (default=True)
953 If True, return a new DiGraph holding the reversed edges.
954 If False, the reverse graph is created using a view of
955 the original graph.
956 """
957 if copy:
958 H = self.__class__()
959 H.graph.update(deepcopy(self.graph))
960 H.add_nodes_from((n, deepcopy(d)) for n, d in self._node.items())
961 H.add_edges_from(
962 (v, u, k, deepcopy(d))
963 for u, v, k, d in self.edges(keys=True, data=True)
964 )
965 return H
966 return nx.reverse_view(self)