Stats argsort (#521)

* added argsort to stats

* added unit tests

docs/source/api/recipes/recipes.ipynb

@@ -732,8 +732,8 @@
     "m, n = 10, 20\n",
     "p = 0.5\n",
     "\n",
-    "G = nx.triangular_lattice_graph(m,n, with_positions=True)\n",
-    "pos = nx.get_node_attributes(G, 'pos')\n",
+    "G = nx.triangular_lattice_graph(m, n, with_positions=True)\n",
+    "pos = nx.get_node_attributes(G, \"pos\")\n",
     "\n",
     "mapping = {i: list(G.nodes)[i] for i in range(0, len(list(G.nodes)))}\n",
     "inv_mapping = {v: k for k, v in mapping.items()}\n",
@@ -783,12 +783,12 @@
     "    lens += tup[1].values()\n",
     "\n",
     "# remove lengths 0 for self-loops\n",
-    "lens = [i for i in lens if i!=0] \n",
+    "lens = [i for i in lens if i != 0]\n",
     "\n",
     "# replace inf by 0 for disconnected nodes\n",
-    "lens = [0 if i==np.inf else i for i in lens] \n",
+    "lens = [0 if i == np.inf else i for i in lens]\n",
     "\n",
-    "avg_shortest_path = np.sum(lens) / (N * (N-1))\n",
+    "avg_shortest_path = np.sum(lens) / (N * (N - 1))\n",
     "print(\"The average shortest path length is\", avg_shortest_path)"
    ]
   }

tests/drawing/test_draw.py

@@ -650,6 +650,8 @@ def test_issue_515(edgelist8):
 
     with warnings.catch_warnings():
         warnings.simplefilter("error")
-        ax, (node_coll, edge_coll) = xgi.draw_multilayer(H, node_fc=["black"] * H.num_nodes)
+        ax, (node_coll, edge_coll) = xgi.draw_multilayer(
+            H, node_fc=["black"] * H.num_nodes
+        )
 
     plt.close("all")

tests/stats/test_nodestats.py

@@ -234,6 +234,12 @@ def test_aggregates(edgelist1, edgelist2, edgelist8):
     assert H.nodes.degree.min() == 1
     assert H.nodes.degree.argmax() == 6
     assert H.nodes.degree.argmin() == 1
+    assert H.nodes.degree.argsort() == list(H.nodes.filterby("degree", 1)) + list(
+        H.nodes.filterby("degree", 2)
+    )
+    assert H.nodes.degree.argsort(reverse=True) == list(
+        H.nodes.filterby("degree", 2)
+    ) + list(H.nodes.filterby("degree", 1))
     assert H.nodes.degree.sum() == 9
     assert round(H.nodes.degree.mean(), 3) == 1.125
     assert round(H.nodes.degree.std(), 3) == 0.331
@@ -244,6 +250,9 @@ def test_aggregates(edgelist1, edgelist2, edgelist8):
     assert H.nodes.degree.min() == 1
     assert H.nodes.degree.argmax() == 4
     assert H.nodes.degree.argmin() == 1
+    assert H.nodes.degree.argsort() == list(H.nodes.filterby("degree", 1)) + list(
+        H.nodes.filterby("degree", 2)
+    )
     assert H.nodes.degree.sum() == 7
     assert round(H.nodes.degree.mean(), 3) == 1.167
     assert round(H.nodes.degree.std(), 3) == 0.373
@@ -254,6 +263,13 @@ def test_aggregates(edgelist1, edgelist2, edgelist8):
     assert H.nodes.degree.min() == 2
     assert H.nodes.degree.argmax() == 0
     assert H.nodes.degree.argmin() == 5
+    assert H.nodes.degree.argsort() == list(H.nodes.filterby("degree", 2)) + list(
+        H.nodes.filterby("degree", 3)
+    ) + list(H.nodes.filterby("degree", 4)) + list(
+        H.nodes.filterby("degree", 5)
+    ) + list(
+        H.nodes.filterby("degree", 6)
+    )
     assert H.nodes.degree.sum() == 26
     assert round(H.nodes.degree.mean(), 3) == 3.714
     assert round(H.nodes.degree.std(), 3) == 1.385

xgi/stats/__init__.py

@@ -272,6 +272,25 @@ def argmax(self):
         d = self.asdict()
         return max(d, key=d.get)
 
+    def argsort(self, reverse=False):
+        """Get the list of IDs sorted by stat value.
+
+        When values are not unique, the order of the IDs
+        is preserved.
+
+        Parameters
+        ----------
+        reverse : bool
+            Whether the sorting should be ascending or descending.
+
+        Returns
+        -------
+        list
+            The IDs sorted in ascending or descending order.
+        """
+        d = self.asdict()
+        return sorted(d, key=d.get, reverse=reverse)
+
 
 class NodeStat(IDStat):
     """An arbitrary node-quantity mapping.