Repository: networkx/networkx

Issue:
relabel_nodes on MultiGraphs does not preserve both edges when two nodes are replaced by one
When the graph contains edges (0,1) and (0,2), and I relabel both 1 and 2 to 3, I expected two edges from (0,3) but only one node is preserved.

Multi*Graph supports parallel edges between nodes and I expected it to preserve both edges when "merging" the two old nodes together.

Tested on both networkx 2.4 and the latest version on master.

```python
import networkx as nx

G = nx.MultiDiGraph([(0,1),(0,2)])
G[0][1][0]["value"] = "a"
G[0][2][0]["value"] = "b"

print(G[0])
# Output:
# {1: {0: {'value': 'a'}}, 2: {0: {'value': 'b'}}}

mapping = {1:3, 2:3}

nx.relabel_nodes(G, mapping, copy=False)

print(G[0])
# Output:
# {3: {0: {'value': 'b'}}}
# Expected:
# {3: {0: {'value': 'a'}, 1: {'value': 'b'}}}
```


Discussion:
This is fixed if you insert this at line 139 in networkx/relabel.py:
```python
for i, (tail, head, key, data) in enumerate(new_edges):
    if head in G[tail] and key in G[tail][head]:
        next_key = max(k for k in G[tail][head]) + 1
        new_edges[i] = (tail, head, next_key, data)
```
Of course, I am not sure if this is actually the desired behaviour.
Good catch! The relabel should have preserved both values 'a' and 'b'.
Feel free to submit a pull request with a fix for this.
This fix assumes that key can be maximized and added to 1. Keys do not have to be numeric.
Perhaps something like:
```python
newkey = 0
current_keys = G[tail][head]
while newkey not in current_keys:
    newkey += 1
```
There may be other better ways to do this.
Actually, upon further reflection -- it might be better to explicitly combine nodes...
That is, we might want to impose node_contraction and not let the relabel_nodes function change the graph connections.

What do you think?
@dschult I understand what you mean, it makes the intention of the programmer clearer. But I think a casual user of networkx (like myself!) would expect the relabel_nodes operation on a MultiGraph to not silently drop all the other edges except one.

Also, node_contraction only contracts two nodes at once, but a fixed relabel_nodes would be able to handle as many nodes and edges as the programmer wants to merge together. It's a minor point and could probably be done by writing some glue code, but it is more convenient. 
Yes, it seems that the convenience and flexibility of ```relabel_nodes``` may offset the disadvantages.  We will need a fairly strong statement in the docstring about how this relabeling affects the nodes when more than one is relabeled to the same object. 

This sounds good to me.

Resolving patch:
diff --git a/networkx/relabel.py b/networkx/relabel.py
--- a/networkx/relabel.py
+++ b/networkx/relabel.py
@@ -13,7 +13,7 @@ def relabel_nodes(G, mapping, copy=True):
 
     mapping : dictionary
        A dictionary with the old labels as keys and new labels as values.
-       A partial mapping is allowed.
+       A partial mapping is allowed. Mapping 2 nodes to a single node is allowed.
 
     copy : bool (optional, default=True)
        If True return a copy, or if False relabel the nodes in place.
@@ -64,6 +64,27 @@ def relabel_nodes(G, mapping, copy=True):
     >>> list(H)
     [0, 1, 4]
 
+    In a multigraph, relabeling two or more nodes to the same new node
+    will retain all edges, but may change the edge keys in the process:
+
+    >>> G = nx.MultiGraph()
+    >>> G.add_edge(0, 1, value="a")  # returns the key for this edge
+    0
+    >>> G.add_edge(0, 2, value="b")
+    0
+    >>> G.add_edge(0, 3, value="c")
+    0
+    >>> mapping = {1: 4, 2: 4, 3: 4}
+    >>> H = nx.relabel_nodes(G, mapping, copy=True)
+    >>> print(H[0])
+    {4: {0: {'value': 'a'}, 1: {'value': 'b'}, 2: {'value': 'c'}}}
+
+    This works for in-place relabeling too:
+
+    >>> G = nx.relabel_nodes(G, mapping, copy=False)
+    >>> print(G[0])
+    {4: {0: {'value': 'a'}, 1: {'value': 'b'}, 2: {'value': 'c'}}}
+
     Notes
     -----
     Only the nodes specified in the mapping will be relabeled.
@@ -77,6 +98,13 @@ def relabel_nodes(G, mapping, copy=True):
     graph is not possible in-place and an exception is raised.
     In that case, use copy=True.
 
+    If a relabel operation on a multigraph would cause two or more
+    edges to have the same source, target and key, the second edge must
+    be assigned a new key to retain all edges. The new key is set
+    to the lowest non-negative integer not already used as a key
+    for edges between these two nodes. Note that this means non-numeric
+    keys may be replaced by numeric keys.
+
     See Also
     --------
     convert_node_labels_to_integers
@@ -136,6 +164,15 @@ def _relabel_inplace(G, mapping):
                     (new if old == source else source, new, key, data)
                     for (source, _, key, data) in G.in_edges(old, data=True, keys=True)
                 ]
+            # Ensure new edges won't overwrite existing ones
+            seen = set()
+            for i, (source, target, key, data) in enumerate(new_edges):
+                if (target in G[source] and key in G[source][target]):
+                    new_key = 0 if not isinstance(key, (int, float)) else key
+                    while (new_key in G[source][target] or (target, new_key) in seen):
+                        new_key += 1
+                    new_edges[i] = (source, target, new_key, data)
+                    seen.add((target, new_key))
         else:
             new_edges = [
                 (new, new if old == target else target, data)
@@ -156,10 +193,25 @@ def _relabel_copy(G, mapping):
     H.add_nodes_from(mapping.get(n, n) for n in G)
     H._node.update((mapping.get(n, n), d.copy()) for n, d in G.nodes.items())
     if G.is_multigraph():
-        H.add_edges_from(
+        new_edges = [
             (mapping.get(n1, n1), mapping.get(n2, n2), k, d.copy())
             for (n1, n2, k, d) in G.edges(keys=True, data=True)
-        )
+        ]
+
+        # check for conflicting edge-keys
+        undirected = not G.is_directed()
+        seen_edges = set()
+        for i, (source, target, key, data) in enumerate(new_edges):
+            while (source, target, key) in seen_edges:
+                if not isinstance(key, (int, float)):
+                    key = 0
+                key += 1
+            seen_edges.add((source, target, key))
+            if undirected:
+                seen_edges.add((target, source, key))
+            new_edges[i] = (source, target, key, data)
+
+        H.add_edges_from(new_edges)
     else:
         H.add_edges_from(
             (mapping.get(n1, n1), mapping.get(n2, n2), d.copy())


Test patch:
diff --git a/networkx/tests/test_relabel.py b/networkx/tests/test_relabel.py
--- a/networkx/tests/test_relabel.py
+++ b/networkx/tests/test_relabel.py
@@ -183,3 +183,109 @@ def test_relabel_selfloop(self):
         G = nx.MultiDiGraph([(1, 1)])
         G = nx.relabel_nodes(G, {1: 0}, copy=False)
         assert_nodes_equal(G.nodes(), [0])
+
+#    def test_relabel_multidigraph_inout_inplace(self):
+#        pass
+    def test_relabel_multidigraph_inout_merge_nodes(self):
+        for MG in (nx.MultiGraph, nx.MultiDiGraph):
+            for cc in (True, False):
+                G = MG([(0, 4), (1, 4), (4, 2), (4, 3)])
+                G[0][4][0]["value"] = "a"
+                G[1][4][0]["value"] = "b"
+                G[4][2][0]["value"] = "c"
+                G[4][3][0]["value"] = "d"
+                G.add_edge(0, 4, key="x", value="e")
+                G.add_edge(4, 3, key="x", value="f")
+                mapping = {0: 9, 1: 9, 2: 9, 3: 9}
+                H = nx.relabel_nodes(G, mapping, copy=cc)
+                # No ordering on keys enforced
+                assert {"value": "a"} in H[9][4].values()
+                assert {"value": "b"} in H[9][4].values()
+                assert {"value": "c"} in H[4][9].values()
+                assert len(H[4][9]) == 3 if G.is_directed() else 6
+                assert {"value": "d"} in H[4][9].values()
+                assert {"value": "e"} in H[9][4].values()
+                assert {"value": "f"} in H[4][9].values()
+                assert len(H[9][4]) == 3 if G.is_directed() else 6
+
+    def test_relabel_multigraph_merge_inplace(self):
+        G = nx.MultiGraph([(0, 1), (0, 2), (0, 3), (0, 1), (0, 2), (0, 3)])
+        G[0][1][0]["value"] = "a"
+        G[0][2][0]["value"] = "b"
+        G[0][3][0]["value"] = "c"
+        mapping = {1: 4, 2: 4, 3: 4}
+        nx.relabel_nodes(G, mapping, copy=False)
+        # No ordering on keys enforced
+        assert {"value": "a"} in G[0][4].values()
+        assert {"value": "b"} in G[0][4].values()
+        assert {"value": "c"} in G[0][4].values()
+
+    def test_relabel_multidigraph_merge_inplace(self):
+        G = nx.MultiDiGraph([(0, 1), (0, 2), (0, 3)])
+        G[0][1][0]["value"] = "a"
+        G[0][2][0]["value"] = "b"
+        G[0][3][0]["value"] = "c"
+        mapping = {1: 4, 2: 4, 3: 4}
+        nx.relabel_nodes(G, mapping, copy=False)
+        # No ordering on keys enforced
+        assert {"value": "a"} in G[0][4].values()
+        assert {"value": "b"} in G[0][4].values()
+        assert {"value": "c"} in G[0][4].values()
+
+    def test_relabel_multidigraph_inout_copy(self):
+        G = nx.MultiDiGraph([(0, 4), (1, 4), (4, 2), (4, 3)])
+        G[0][4][0]["value"] = "a"
+        G[1][4][0]["value"] = "b"
+        G[4][2][0]["value"] = "c"
+        G[4][3][0]["value"] = "d"
+        G.add_edge(0, 4, key="x", value="e")
+        G.add_edge(4, 3, key="x", value="f")
+        mapping = {0: 9, 1: 9, 2: 9, 3: 9}
+        H = nx.relabel_nodes(G, mapping, copy=True)
+        # No ordering on keys enforced
+        assert {"value": "a"} in H[9][4].values()
+        assert {"value": "b"} in H[9][4].values()
+        assert {"value": "c"} in H[4][9].values()
+        assert len(H[4][9]) == 3
+        assert {"value": "d"} in H[4][9].values()
+        assert {"value": "e"} in H[9][4].values()
+        assert {"value": "f"} in H[4][9].values()
+        assert len(H[9][4]) == 3
+
+    def test_relabel_multigraph_merge_copy(self):
+        G = nx.MultiGraph([(0, 1), (0, 2), (0, 3)])
+        G[0][1][0]["value"] = "a"
+        G[0][2][0]["value"] = "b"
+        G[0][3][0]["value"] = "c"
+        mapping = {1: 4, 2: 4, 3: 4}
+        H = nx.relabel_nodes(G, mapping, copy=True)
+        assert {"value": "a"} in H[0][4].values()
+        assert {"value": "b"} in H[0][4].values()
+        assert {"value": "c"} in H[0][4].values()
+
+    def test_relabel_multidigraph_merge_copy(self):
+        G = nx.MultiDiGraph([(0, 1), (0, 2), (0, 3)])
+        G[0][1][0]["value"] = "a"
+        G[0][2][0]["value"] = "b"
+        G[0][3][0]["value"] = "c"
+        mapping = {1: 4, 2: 4, 3: 4}
+        H = nx.relabel_nodes(G, mapping, copy=True)
+        assert {"value": "a"} in H[0][4].values()
+        assert {"value": "b"} in H[0][4].values()
+        assert {"value": "c"} in H[0][4].values()
+
+    def test_relabel_multigraph_nonnumeric_key(self):
+        for MG in (nx.MultiGraph, nx.MultiDiGraph):
+            for cc in (True, False):
+                G = nx.MultiGraph()
+                G.add_edge(0, 1, key="I", value="a")
+                G.add_edge(0, 2, key="II", value="b")
+                G.add_edge(0, 3, key="II", value="c")
+                mapping = {1: 4, 2: 4, 3: 4}
+                nx.relabel_nodes(G, mapping, copy=False)
+                assert {"value": "a"} in G[0][4].values()
+                assert {"value": "b"} in G[0][4].values()
+                assert {"value": "c"} in G[0][4].values()
+                assert 0 in G[0][4]
+                assert "I" in G[0][4]
+                assert "II" in G[0][4]