From a8a320b9a1126f8ce6590e3f320264c6d2b06249 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Thu, 4 Aug 2022 04:47:40 -0600 Subject: docstring updates for `union`, `disjoint_union`, and `compose` (#5892) * docstring updates - union - disjoint_union - compose * fix broken link to Graph.update() --- networkx/algorithms/operators/binary.py | 75 +++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/networkx/algorithms/operators/binary.py b/networkx/algorithms/operators/binary.py index fcd5933e..7ea3d77a 100644 --- a/networkx/algorithms/operators/binary.py +++ b/networkx/algorithms/operators/binary.py @@ -15,14 +15,16 @@ __all__ = [ def union(G, H, rename=(None, None), name=None): - """Return the union of graphs G and H. + """Combine graphs G and H. The names of nodes must be unique. + + A name collision between the graphs will raise an exception. + + A renaming facility is provided to avoid name collisions. - Graphs G and H must be disjoint after the renaming takes place, - otherwise an exception is raised. Parameters ---------- - G,H : graph + G, H : graph A NetworkX graph rename : tuple , default=(None, None) @@ -40,14 +42,23 @@ def union(G, H, rename=(None, None), name=None): ------- U : A union graph with the same type as G. + See Also + -------- + compose + :func:`~networkx.Graph.update` + disjoint_union + Notes ----- - To force a disjoint union with node relabeling, use - disjoint_union(G,H) or convert_node_labels_to integers(). + To combine graphs that have common nodes, consider compose(G, H) + or the method, Graph.update(). - Graph, edge, and node attributes are propagated from G and H - to the union graph. If a graph attribute is present in both - G and H the value from H is used. + disjoint_union() is similar to union() except that it avoids name clashes + by relabeling the nodes with sequential integers. + + Edge and node attributes are propagated from G and H to the union graph. + Graph attributes are also propagated, but if they are present in both G and H, + then the value from H is used. Examples -------- @@ -59,9 +70,7 @@ def union(G, H, rename=(None, None), name=None): >>> U.edges EdgeView([('G0', 'G1'), ('G0', 'G2'), ('G1', 'G2'), ('H0', 'H1'), ('H0', 'H3'), ('H1', 'H3'), ('H1', 'H2')]) - See Also - -------- - disjoint_union + """ if name is not None: import warnings @@ -76,9 +85,9 @@ def union(G, H, rename=(None, None), name=None): def disjoint_union(G, H): - """Return the disjoint union of graphs G and H. + """Combine graphs G and H. The nodes are assumed to be unique (disjoint). - This algorithm forces distinct integer node labels. + This algorithm automatically relabels nodes to avoid name collisions. Parameters ---------- @@ -89,6 +98,12 @@ def disjoint_union(G, H): ------- U : A union graph with the same type as G. + See Also + -------- + union + compose + :func:`~networkx.Graph.update` + Notes ----- A new graph is created, of the same class as G. It is recommended @@ -97,9 +112,15 @@ def disjoint_union(G, H): The nodes of G are relabeled 0 to len(G)-1, and the nodes of H are relabeled len(G) to len(G)+len(H)-1. - Graph, edge, and node attributes are propagated from G and H - to the union graph. If a graph attribute is present in both - G and H the value from H is used. + Renumbering forces G and H to be disjoint, so no exception is ever raised for a name collision. + To preserve the check for common nodes, use union(). + + Edge and node attributes are propagated from G and H to the union graph. + Graph attributes are also propagated, but if they are present in both G and H, + then the value from H is used. + + To combine graphs that have common nodes, consider compose(G, H) + or the method, Graph.update(). Examples -------- @@ -277,10 +298,12 @@ def symmetric_difference(G, H): def compose(G, H): - """Returns a new graph of G composed with H. + """Compose graph G with H by combining nodes and edges into a single graph. + + The node sets and edges sets do not need to be disjoint. - Composition is the simple union of the node sets and edge sets. - The node sets of G and H do not need to be disjoint. + Composing preserves the attributes of nodes and edges. + Attribute values from H take precedent over attribute values from G. Parameters ---------- @@ -289,17 +312,25 @@ def compose(G, H): Returns ------- - C: A new graph with the same type as G + C: A new graph with the same type as G + + See Also + -------- + :func:`~networkx.Graph.update` + union + disjoint_union Notes ----- It is recommended that G and H be either both directed or both undirected. - Attributes from H take precedent over attributes from G. For MultiGraphs, the edges are identified by incident nodes AND edge-key. This can cause surprises (i.e., edge `(1, 2)` may or may not be the same in two graphs) if you use MultiGraph without keeping track of edge keys. + If combining the attributes of common nodes is not desired, consider union(), + which raises an exception for name collisions. + Examples -------- >>> G = nx.Graph([(0, 1), (0, 2)]) -- cgit v1.2.1