Deprecate name_map for table_name_map

Author: benjeffery

docs/python-api.md

@@ -644,7 +644,7 @@ Other properties
       TableCollection.file_uuid
       TableCollection.indexes
       TableCollection.nbytes
-      TableCollection.name_map
+      TableCollection.table_name_map
       TableCollection.metadata
       TableCollection.metadata_bytes
       TableCollection.metadata_schema

python/CHANGELOG.rst

@@ -2,6 +2,12 @@
 [0.4.0] - 2022-0X-XX
 ----------------------
 
+**Changes**
+
+- ``TableCollection.name_map`` has been deprecated in favour of ``table_name_map``.
+  (:user:`benjeffery`, :issue:`1981`, :pr:`2086`)
+
+
 **Fixes**
 
 - ``TreeSequence.dump_text`` now prints decoded metadata if there is a schema.

python/lwt_interface/dict_encoding_testlib.py

@@ -71,7 +71,7 @@ def full_ts():
     for ind in ts.individuals():
         tables.individuals.add_row(flags=0, location=[ind.id, ind.id], parents=[-1, -1])
 
-    for name, table in tables.name_map.items():
+    for name, table in tables.table_name_map.items():
         if name != "provenances":
             table.metadata_schema = tskit.MetadataSchema({"codec": "json"})
             metadatas = [f"n_{name}_{u}" for u in range(len(table))]

python/tests/test_file_format.py

@@ -1158,7 +1158,7 @@ def load():
 
 
 def assert_tables_empty(tables):
-    for table in tables.name_map.values():
+    for table in tables.table_name_map.values():
         assert len(table) == 0
 
 

python/tests/test_highlevel.py

@@ -2189,7 +2189,7 @@ def test_html_repr(self):
             assert len(html) > 4300
             assert f"<tr><td>Trees</td><td>{ts.num_trees}</td></tr>" in html
             assert f"<tr><td>Time Units</td><td>{ts.time_units}</td></tr>" in html
-            for table in ts.tables.name_map:
+            for table in ts.tables.table_name_map:
                 assert f"<td>{table.capitalize()}</td>" in html
 
     def test_str(self):
@@ -2198,7 +2198,7 @@ def test_str(self):
             assert len(s) > 999
             assert re.search(rf"║Trees *│ *{ts.num_trees}║", s)
             assert re.search(rf"║Time Units *│ *{ts.time_units}║", s)
-            for table in ts.tables.name_map:
+            for table in ts.tables.table_name_map:
                 assert re.search(rf"║{table.capitalize()} *│", s)
 
     @pytest.mark.skip("FIXME nbytes")

python/tests/test_lowlevel.py

@@ -906,7 +906,7 @@ class TestTableMethodsErrors:
     """
 
     def yield_tables(self, ts):
-        for table in ts.tables.name_map.values():
+        for table in ts.tables.table_name_map.values():
             yield table.ll_table
 
     @pytest.mark.parametrize(

python/tests/test_tables.py

@@ -3372,7 +3372,7 @@ def test_asdict(self, ts_fixture):
     def test_asdict_force_offset_64(self, ts_fixture, force_offset_64):
         tables = ts_fixture.dump_tables()
         d = tables.asdict(force_offset_64=force_offset_64)
-        for table in tables.name_map:
+        for table in tables.table_name_map:
             for name, column in d[table].items():
                 if name.endswith("_offset"):
                     if force_offset_64:
@@ -3383,7 +3383,7 @@ def test_asdict_force_offset_64(self, ts_fixture, force_offset_64):
     def test_asdict_force_offset_64_default(self, ts_fixture):
         tables = ts_fixture.dump_tables()
         d = tables.asdict()
-        for table in tables.name_map:
+        for table in tables.table_name_map:
             for name, column in d[table].items():
                 if name.endswith("_offset"):
                     assert column.dtype == np.uint32
@@ -3423,7 +3423,7 @@ def test_roundtrip_dict(self, ts_fixture):
         t2 = tskit.TableCollection.fromdict(t1.asdict())
         t1.assert_equals(t2)
 
-    def test_name_map(self, ts_fixture):
+    def test_table_name_map(self, ts_fixture):
         tables = ts_fixture.tables
         td1 = {
             "individuals": tables.individuals,
@@ -3435,13 +3435,18 @@ def test_name_map(self, ts_fixture):
             "migrations": tables.migrations,
             "provenances": tables.provenances,
         }
-        td2 = tables.name_map
+        td2 = tables.table_name_map
         assert isinstance(td2, dict)
         assert set(td1.keys()) == set(td2.keys())
         for name in td2.keys():
             assert td1[name] == td2[name]
         assert td1 == td2
 
+        # Deprecated in 0.4.1
+        with pytest.warns(FutureWarning):
+            td1 = tables.name_map
+        td1 == td2
+
     def test_equals_empty(self):
         assert tskit.TableCollection() == tskit.TableCollection()
 
@@ -3943,7 +3948,7 @@ def test_time_units(self, t1, t2):
         ):
             t1.assert_equals(t2)
 
-    @pytest.mark.parametrize("table_name", tskit.TableCollection(1).name_map)
+    @pytest.mark.parametrize("table_name", tskit.TableCollection(1).table_name_map)
     def test_tables(self, t1, t2, table_name):
         table = getattr(t2, table_name)
         table.truncate(0)
@@ -3954,7 +3959,7 @@ def test_tables(self, t1, t2, table_name):
         ):
             t1.assert_equals(t2)
 
-    @pytest.mark.parametrize("table_name", tskit.TableCollection(1).name_map)
+    @pytest.mark.parametrize("table_name", tskit.TableCollection(1).table_name_map)
     def test_ignore_metadata(self, t1, t2, table_name):
         table = getattr(t2, table_name)
         if hasattr(table, "metadata_schema"):

python/tests/tsutil.py

@@ -1941,7 +1941,7 @@ def all_fields_ts():
     tables.migrations.add_row(left=0, right=1, node=21, source=1, dest=3, time=1001)
 
     # Add metadata
-    for name, table in tables.name_map.items():
+    for name, table in tables.table_name_map.items():
         if name != "provenances":
             table.metadata_schema = tskit.MetadataSchema.permissive_json()
             metadatas = [f'{{"foo":"n_{name}_{u}"}}' for u in range(len(table))]

python/tskit/tables.py

@@ -2958,11 +2958,8 @@ def asdict(self, force_offset_64=False):
         """
         return self._ll_tables.asdict(force_offset_64)
 
-    # TODO rename this to "table_name_map" to resolve the issue with whether
-    # we should regard ReferenceSequence as being in it or not.
-    # https://github.com/tskit-dev/tskit/issues/1981
     @property
-    def name_map(self) -> Dict:
+    def table_name_map(self) -> Dict:
         """
         Returns a dictionary mapping table names to the corresponding
         table instances. For example, the returned dictionary will contain the
@@ -2979,6 +2976,15 @@ def name_map(self) -> Dict:
             "sites": self.sites,
         }
 
+    @property
+    def name_map(self) -> Dict:
+        # Deprecated in 0.4.1
+        warnings.warn(
+            "name_map is deprecated; use table_name_map instead",
+            FutureWarning,
+        )
+        return self.table_name_map
+
     @property
     def nbytes(self) -> int:
         """
@@ -2993,7 +2999,7 @@ def nbytes(self) -> int:
                 len(self.time_units.encode()),
                 self.indexes.nbytes,
                 self.reference_sequence.nbytes,
-                sum(table.nbytes for table in self.name_map.values()),
+                sum(table.nbytes for table in self.table_name_map.values()),
             )
         )
 
@@ -3155,7 +3161,7 @@ def assert_equals(
                 f" differs: self={self.sequence_length} other={other.sequence_length}"
             )
 
-        for table_name, table in self.name_map.items():
+        for table_name, table in self.table_name_map.items():
             if table_name != "provenances":
                 table.assert_equals(
                     getattr(other, table_name), ignore_metadata=ignore_metadata

python/tskit/trees.py

@@ -3767,9 +3767,9 @@ def tables_dict(self):
         """
         Returns a dictionary mapping names to tables in the
         underlying :class:`.TableCollection`. Equivalent to calling
-        ``ts.tables.name_map``.
+        ``ts.tables.table_name_map``.
         """
-        return self.tables.name_map
+        return self.tables.table_name_map
 
     @property
     def tables(self):
@@ -3884,7 +3884,7 @@ def __str__(self):
         ]
         header = ["Table", "Rows", "Size", "Has Metadata"]
         table_rows = []
-        for name, table in self.tables.name_map.items():
+        for name, table in self.tables.table_name_map.items():
             table_rows.append(
                 [
                     str(s)