Repository: networkx/networkx

Issue:
`OrderedGraph.subgraph` does not maintain the order of the nodes
A subgraph built from a `OrderedGraph` should keep the order of the nodes, yet nodes in the subgraph are neither in the order of the initial graph, nor in the order of the selection. The issue can be seen from the following snippet:

```python
graph = nx.OrderedGraph()
nodes = list(range(10))
random.shuffle(nodes)
graph.add_nodes_from(nodes)  # key order is (7, 2, 1, 9, 0, 8, 6, 4, 3, 5)

# We create a selection in the same order as the initial graph keys
to_keep = [key for key in graph if key % 2 == 0]  # [2, 0, 8, 6, 4]
subgraph = graph.subgraph(to_keep)  # (0, 2, 4, 6, 8)

# We create a selection in a different order
subgraph = graph.subgraph([5, 3, 1])  # (1, 3, 5)
```

From what I see, the issue is due to `Graph.subgraph` passing the selection to `nx.filters.show_nodes` that transforms it to a set. The nodes in the subgraph are then in the order of the set; as sets do not preserve the order, the order of the initial graph if not preserved.


Discussion:
It is not clear whether a subgraph should preserve the order of the nodes of the original graph or the order of nodes provided to the command.

Perhaps it is best to simplify the API by using more basic commands to build what you want. e.g.

    SG=nx.OrderedGraph()
    SG.add_nodes_from(ordered_nodes)
    SG.add_edges_from((u, v) for (u, v) in G.edges() if u in SG if v in SG)

Is the better API a long list of methods each creating their specified subgraph orderings?
Or is it better to ask users to build their own?  
Perhaps we should remove the subgraph method entirely...
It may only be me, but I got very surprised when my subgraph was shuffled. It did cause a bug that was long to identify because I was assuming that the subgraph was in the same order as the initial graph since my initial graph was an `OrderedGraph`. Not having the `subgraph` method would also have been a surprise since `Graph` has a it and `OrderedGraph` is only a subclass of `Graph`.

In my case, the selection was in the same order as the nodes in the graph, so I indeed did not think about the two possible ordering options. Keeping the ordering of the selection would be consistent with how numpy do indexing; however, on the contrary to numpy indexing, subgraphs do not keep duplicates. Because of that, I think that keeping the order of the selection can be confusing when it involves duplicates, and that keeping the order of the graph should be preferred.

The choice of one option or the other is, I think, a question of documentation.
Let's fix the documentation.  See #2985

Resolving patch:
diff --git a/networkx/classes/ordered.py b/networkx/classes/ordered.py
--- a/networkx/classes/ordered.py
+++ b/networkx/classes/ordered.py
@@ -1,5 +1,10 @@
 """
 Consistently ordered variants of the default base classes.
+Note that if you are using Python 3.6, you shouldn't need these classes
+because the dicts in Python 3.6 are ordered.
+Note also that there are many differing expectations for the word "ordered"
+and that these classes may not provide the order you expect.
+The intent here is to give a consistent order not a particular order.
 
 The Ordered (Di/Multi/MultiDi) Graphs give a consistent order for reporting of
 nodes and edges.  The order of node reporting agrees with node adding, but for
@@ -8,6 +13,17 @@
 In general, you should use the default (i.e., unordered) graph classes.
 However, there are times (e.g., when testing) when you may need the
 order preserved.
+
+Special care is required when using subgraphs of the Ordered classes.
+The order of nodes in the subclass is not necessarily the same order
+as the original class.  In general it is probably better to avoid using
+subgraphs and replace with code similar to:
+
+    # instead of SG = G.subgraph(ordered_nodes)
+    SG=nx.OrderedGraph()
+    SG.add_nodes_from(ordered_nodes)
+    SG.add_edges_from((u, v) for (u, v) in G.edges() if u in SG if v in SG)
+
 """
 from collections import OrderedDict
 


Test patch: