Documentation examples for keep_rows and id_map

[jeromekelleher]

We need some examples to help illustrate how to use keep_rows and the id_map well. Here's one example (taken from the tests in #2707)

See also #2529

  def test_delete_unreferenced_nodes(self):
        # 2.00┊   4   ┊
        #     ┊ ┏━┻┓  ┊
        # 1.00┊ ┃  3  ┊
        #     ┊ ┃ ┏┻┓ ┊
        # 0.00┊ 0 1 2 ┊
        #     0       1
        ts = tskit.Tree.generate_balanced(3).tree_sequence
        tables = ts.dump_tables()
        edges = tables.edges
        nodes = tables.nodes
        edges.keep_rows(nodes.time[edges.parent] <= 1)
        # 2.00┊       ┊
        #     ┊       ┊
        # 1.00┊    3  ┊
        #     ┊   ┏┻┓ ┊
        # 0.00┊ 0 1 2 ┊
        #     0       1
        ref_count = np.bincount(edges.child, minlength=len(nodes))
        ref_count += np.bincount(edges.parent, minlength=len(nodes))
        assert list(ref_count) == [0, 1, 1, 2, 0]
        id_map = nodes.keep_rows(ref_count > 0)
        assert list(id_map) == [-1, 0, 1, 2, -1]
        assert len(nodes) == 3
        # Remap the edges IDs
        edges.child = id_map[edges.child]
        edges.parent = id_map[edges.parent]
        ts = tables.tree_sequence()
        assert ts.num_trees == 1
        assert ts.first().parent_dict == {0: 2, 1: 2}

[jeromekelleher]

This would belong in the "Manipulating Data" section in #2709