TreeSequence.tables returns ImmutableTableCollection

Author: benjeffery

.gitignore

@@ -6,4 +6,4 @@ python/benchmark/*.html
 .venv
 .env
 .vscode
-
+env

docs/python-api.md

@@ -64,20 +64,11 @@ The {class}`.TreeSequence` class provides access to underlying numerical
 data defined in the {ref}`data model<sec_data_model>` in two ways:
 
 1. Via the {attr}`.TreeSequence.tables` property and the
-    {ref}`Tables API<sec_tables_api_accessing_table_data>`
+    {ref}`Tables API<sec_tables_api_accessing_table_data>`.
+   Since version 1.0 this provides a direct, zero-copy, immutable view of the
+   underlying memory.
 2. Via a set of properties on the ``TreeSequence`` class that provide
-   direct and efficient access to the underlying memory.
-
-:::{warning}
-Accessing table data via {attr}`.TreeSequence.tables` can be very inefficient
-at the moment because accessing the `.tables` property incurs a **full copy**
-of the data model. While we intend to implement this as a read-only view
-in the future, the engineering involved is nontrivial, and so we recommend
-using the properties listed here like ``ts.nodes_time`` in favour of
-``ts.tables.nodes.time``.
-Please see [issue #760](https://github.com/tskit-dev/tskit/issues/760)
-for more information.
-:::
+   direct and efficient access to a single array in the underlying memory.
 
 
 ```{eval-rst}

python/CHANGELOG.rst

@@ -4,6 +4,10 @@
 
 **Breaking Changes**
 
+- `TreeSequence.tables` now returns a zero-copy immutable view of the tables.
+  To get a mutable copy, use `TreeSequence.dump_tables()`.
+  (:user:`benjeffery`, :pr:`3288`, :issue:`760`)
+  
 - For a tree seqeunce to be valid mutation parents in the table collection
   must be correct and consistent with the topology of the tree at each mutation site.
   ``TableCollection.tree_sequence()`` will raise a ``_tskit.LibraryError`` if this

python/lwt_interface/dict_encoding_testlib.py

@@ -132,7 +132,7 @@ def verify(self, tables):
 
     def test_simple(self):
         ts = msprime.simulate(10, mutation_rate=1, random_seed=2)
-        self.verify(ts.tables)
+        self.verify(ts.dump_tables())
 
     def test_empty(self):
         tables = tskit.TableCollection(sequence_length=1)
@@ -152,7 +152,7 @@ def test_sequence_length(self):
         ts = msprime.simulate(
             10, recombination_rate=0.1, mutation_rate=1, length=0.99, random_seed=2
         )
-        self.verify(ts.tables)
+        self.verify(ts.dump_tables())
 
     def test_migration(self):
         pop_configs = [msprime.PopulationConfiguration(5) for _ in range(2)]
@@ -164,7 +164,7 @@ def test_migration(self):
             record_migrations=True,
             random_seed=1,
         )
-        self.verify(ts.tables)
+        self.verify(ts.dump_tables())
 
     def test_example(self, tables):
         tables.metadata_schema = tskit.MetadataSchema(

python/lwt_interface/test_example_c_module.py

@@ -35,7 +35,7 @@ def test_example_receiving():
         example_c_module.example_receiving(lwt)
 
     # This tree sequence has one root so we get false
-    tables = msprime.simulate(10).tables
+    tables = msprime.simulate(10).dump_tables()
     lwt.fromdict(tables.asdict())
     assert not example_c_module.example_receiving(lwt)
 

python/tests/test_genotypes.py

@@ -863,7 +863,7 @@ def test_nonbinary_trees(self):
     def test_acgt_mutations(self):
         ts = msprime.simulate(10, mutation_rate=10)
         assert ts.num_sites > 0
-        tables = ts.tables
+        tables = ts.dump_tables()
         sites = tables.sites
         mutations = tables.mutations
         sites.set_columns(
@@ -883,23 +883,23 @@ def test_acgt_mutations(self):
 
     def test_fails_multiletter_mutations(self):
         ts = msprime.simulate(10, random_seed=2)
-        tables = ts.tables
+        tables = ts.dump_tables()
         tables.sites.add_row(0, "ACTG")
         tsp = tables.tree_sequence()
         with pytest.raises(TypeError):
             list(tsp.haplotypes())
 
     def test_fails_deletion_mutations(self):
         ts = msprime.simulate(10, random_seed=2)
-        tables = ts.tables
+        tables = ts.dump_tables()
         tables.sites.add_row(0, "")
         tsp = tables.tree_sequence()
         with pytest.raises(TypeError):
             list(tsp.haplotypes())
 
     def test_nonascii_mutations(self):
         ts = msprime.simulate(10, random_seed=2)
-        tables = ts.tables
+        tables = ts.dump_tables()
         tables.sites.add_row(0, chr(169))  # Copyright symbol
         tsp = tables.tree_sequence()
         with pytest.raises(TypeError):

python/tests/test_highlevel.py

@@ -1292,7 +1292,7 @@ def verify_edgesets(self, ts):
                     tskit.Edge(edgeset.left, edgeset.right, edgeset.parent, child)
                 )
         # squash the edges.
-        t = ts.dump_tables().nodes.time
+        t = ts.tables.nodes.time
         new_edges.sort(key=lambda e: (t[e.parent], e.parent, e.child, e.left))
 
         squashed = []
@@ -1916,24 +1916,20 @@ def test_load_tables(self, ts):
         with pytest.raises(
             _tskit.LibraryError, match="Table collection must be indexed"
         ):
-            assert tskit.TreeSequence.load_tables(tables).dump_tables().has_index()
+            assert tskit.TreeSequence.load_tables(tables).tables.has_index()
 
         # Tables not in tc, but rebuilt
-        assert (
-            tskit.TreeSequence.load_tables(tables, build_indexes=True)
-            .dump_tables()
-            .has_index()
-        )
+        assert tskit.TreeSequence.load_tables(
+            tables, build_indexes=True
+        ).tables.has_index()
 
         tables.build_index()
         # Tables in tc, not rebuilt
-        assert (
-            tskit.TreeSequence.load_tables(tables, build_indexes=False)
-            .dump_tables()
-            .has_index()
-        )
+        assert tskit.TreeSequence.load_tables(
+            tables, build_indexes=False
+        ).tables.has_index()
         # Tables in tc, and rebuilt
-        assert tskit.TreeSequence.load_tables(tables).dump_tables().has_index()
+        assert tskit.TreeSequence.load_tables(tables).tables.has_index()
 
     @pytest.mark.parametrize("ts", tsutil.get_example_tree_sequences())
     def test_html_repr(self, ts):
@@ -1958,14 +1954,14 @@ def test_bad_provenance(self, ts_fixture):
         assert "Could not parse provenance" in ts._repr_html_()
 
     def test_provenance_summary_html(self, ts_fixture):
-        tables = ts_fixture.tables
+        tables = ts_fixture.dump_tables()
         for _ in range(20):
             # Add a row with isotimestamp
             tables.provenances.add_row("foo", "bar")
         assert "... 15 more" in tables.tree_sequence()._repr_html_()
 
     def test_html_repr_limit(self, ts_fixture):
-        tables = ts_fixture.tables
+        tables = ts_fixture.dump_tables()
         d = {n: n for n in range(50)}
         d[0] = "N" * 200
         tables.metadata = d
@@ -2656,7 +2652,8 @@ def verify_tables_api_equality(self, ts):
             tables = ts.dump_tables()
             tables.simplify(samples=samples)
             tables.assert_equals(
-                ts.simplify(samples=samples).tables, ignore_timestamps=True
+                ts.simplify(samples=samples).dump_tables(),
+                ignore_timestamps=True,
             )
 
     @pytest.mark.parametrize("ts", tsutil.get_example_tree_sequences())
@@ -4012,7 +4009,7 @@ def test_first_last(self):
 
     def test_eq_different_tree_sequence(self):
         ts = msprime.simulate(4, recombination_rate=1, length=2, random_seed=42)
-        copy = ts.tables.tree_sequence()
+        copy = ts.dump_tables().tree_sequence()
         for tree1, tree2 in zip(ts.aslist(), copy.aslist()):
             assert tree1 != tree2
 
@@ -5608,6 +5605,21 @@ def test_ragged_array_not_supported(self, column):
         ):
             getattr(ts, column)
 
+    @pytest.mark.skipif(_tskit.HAS_NUMPY_2, reason="Test only on Numpy 1.X")
+    def test_tables_emits_warning(self):
+        tables = tskit.TableCollection(sequence_length=1)
+        ts = tables.tree_sequence()
+
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", UserWarning)
+            result = ts.tables
+
+        assert isinstance(result, tskit.TableCollection)
+        assert len(caught) == 1
+        warning = caught[0]
+        assert warning.category is UserWarning
+        assert "Immutable table views require tskit" in str(warning.message)
+
 
 class TestSampleNodesByPloidy:
     @pytest.mark.parametrize(

python/tests/test_ibd.py

@@ -275,7 +275,7 @@ def test_within_between_mutually_exclusive(self, ts):
 
     @pytest.mark.parametrize("ts", example_ts())
     def test_tables_interface(self, ts):
-        ibd_tab = ts.tables.ibd_segments(store_segments=True)
+        ibd_tab = ts.dump_tables().ibd_segments(store_segments=True)
         ibd_ts = ts.ibd_segments(store_segments=True)
         assert ibd_tab == ibd_ts