Reorder children in tree

.readthedocs.yml

@@ -1,10 +1,11 @@
 version: 2
 build:
-  image: latest
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.8"
 sphinx:
   configuration: docs/conf.py
 python:
-  version: 3.8
   install:
     - method: pip
       path: .

cassiopeia/data/CassiopeiaTree.py

@@ -702,6 +702,32 @@ def children(self, node: str) -> List[str]:
         """
         self.__check_network_initialized()
         return [v for v in self.__network.successors(node)]
+
+    def reorder_children(self, node: str, child_order: List[str]) -> None:
+        """Reorders the children of a particular node.
+
+        Args:
+            node: Node in the tree
+            child_order: A list with the new order of children for the node.
+
+        Raises:
+            CassiopeiaTreeError if the node of interest is a leaf that has not 
+                been instantiated, or if the new order of children is not a 
+                permutation of the original children.
+        """
+        self.__check_network_initialized()
+
+        if self.is_leaf(node):
+            raise CassiopeiaTreeError("Cannot reorder children of a leaf node.")
+
+        if set(child_order) != set(self.children(node)):
+            raise CassiopeiaTreeError("New order of children is not a" 
+                                        "permutation of the original children.")
+
+        self.__network.remove_edges_from(
+            [(node, child) for child in self.children(node)])
+        self.__network.add_edges_from(
+            [(node, child) for child in child_order])
 
     def __remove_node(self, node) -> None:
         """Private method to remove node from tree.

test/data_tests/cassiopeia_tree_test.py

@@ -1901,6 +1901,22 @@ def test_impute_deducible_missing_states(self):
             tree.get_character_states("3"), [0, 1, -1, 1, 0, 0, 1, -1, -1]
         )
 
+    def test_reorder_children(self):
+        tree = nx.DiGraph()
+        tree.add_nodes_from(["0", "1", "2", "3"])
+        tree.add_edges_from([("0", "1"), ("1", "2"), ("1", "3")])
+        tree = cas.data.CassiopeiaTree(tree=tree)
+        self.assertEqual(list(tree.children("1")), ["2", "3"])
+        # Test reorder leaf
+        with self.assertRaises(CassiopeiaTreeError):
+            tree.reorder_children("3", [])
+        # test with invalid children
+        with self.assertRaises(CassiopeiaTreeError):
+            tree.reorder_children("1", ["4"])
+        # test with valid children
+        tree.reorder_children("1", ["3", "2"])
+        self.assertEqual(list(tree.children("1")), ["3", "2"])
+
 
 if __name__ == "__main__":
     unittest.main()