minor doc fixes

warn and remove existing metadata in annotatino; closes #327

Author: petrelharp

CHANGELOG.rst

@@ -14,7 +14,7 @@ https://tskit.dev/pyslim/docs/latest/previous_versions.html
 - SLiM tree sequence file version number has changed to 0.9.
 
 - This is a change in SLiM, really, but top-level SLiM metadata now requires
-    a `"this_chromosome"` entry.
+  a `"this_chromosome"` entry.
 
 - Similarly, node metadata no longer has `genome_type` or `is_null`; instead
   they have `is_vacant`, and the chromosome type is in top-level metadata,
@@ -25,7 +25,13 @@ https://tskit.dev/pyslim/docs/latest/previous_versions.html
     wishing to set up a multi-chromosome simulation should use instead
     `pyslim.slim_node_metadata_schema` (which has the appropriate value in
     `["properties"]["is_vacant"]["length"]`)
-    (:user:`petrelharp`, :pr:`367`)
+    (:user:`petrelharp`, :pr:`367`).
+
+- Previously, `pyslim.annotate` would leave existing node and individual
+    metadata, even if this metadata came from a different schema. This
+    could silently create garbage metadata. Now, `annotate` removes
+    any existing metadata, and warns if this occurs
+    (:user:`petrelharp`, :pr:`390`).
 
 **Notable changes**:
 
@@ -38,7 +44,7 @@ https://tskit.dev/pyslim/docs/latest/previous_versions.html
 
 - `pyslim.set_slim_state` will adjust times and "alive" flags so
     that when the tree sequence is loaded into SLiM it will have
-    a specified set of individuals alive.
+    a specified set of individuals alive at a particular time.
     (:user:`petrelharp`, :pr:`384`)
 
 - Functions `pyslim.node_is_vacant` and `pyslim.has_vacant_samples`
@@ -61,27 +67,27 @@ https://tskit.dev/pyslim/docs/latest/previous_versions.html
 
 **Bugfixes**:
 
-- The individual flags `INDIVIDUAL_ALIVE`, `INDIVIDUAL_REMEMBERED`,
-    and `INDIVIDUAL_RETAINED` were signed integers, but the flags in the
-    individual table they apply to are unsigned, so using the
-    bitwise negation operator `~` could result in an error. Now,
-    they are np.uint32 values. (:user:`petrelharp`, :pr:`378`)
-
 - Recapitation on tree sequences with null genomes would attempt to simulate
     the history of those null genomes; this would in all but exceptional cases
     fail with an error ("not all roots are at the time expected"). Now, null
     genomes are "vacant" (see above) and `recapitate` removes their
     sample flags before recapitating (and optionally puts them back)
-    as described above (:user:`petrelharp`, :pr:`367`)
-    
+    as described in `pyslim.remove_vacant` (:user:`petrelharp`, :pr:`367`).
+
 - Previously, recapitation would require the roots of all trees to be
     at the same time (roughly) as the 'tick' stored in the top-level metadata;
     however, this would not be the case if the first population was added
-    later than the first tick. (:user:`petrelharp`, :pr:`382`)
+    later than the first tick. The requirement has therefore been removed.
+    (:user:`petrelharp`, :pr:`382`)
 
 - The `generated_nucleotides` method now sets the `nucleotide_based` entry
-    in top-level metadata to True.
-    (:user:`petrelharp`, :pr:`385`)
+    in top-level metadata to True. (:user:`petrelharp`, :pr:`385`)
+
+- The individual flags `INDIVIDUAL_ALIVE`, `INDIVIDUAL_REMEMBERED`,
+    and `INDIVIDUAL_RETAINED` were signed integers, but the flags in the
+    individual table they apply to are unsigned, so using the
+    bitwise negation operator `~` could result in an error. Now,
+    they are np.uint32 values. (:user:`petrelharp`, :pr:`378`)
 
 
 ***************************

docs/tutorial.md

@@ -258,7 +258,8 @@ align: right
 name: pedigree_simplify
 ---
 The result of simplifying the tree sequence
-in figure {numref}`figure {number} <pedigree_recapitate>`.
+in figure {numref}`figure {number} <pedigree_recapitate>`
+to only two of the three samples.
 ```
 
 Probably, your simulations have produced many more fictitious genomes

pyslim/methods.py

@@ -1009,6 +1009,16 @@ def _annotate_nodes_individuals(tables, age):
     If you have other situations, like non-alive "remembered" individuals, you
     will need to edit the tables by hand, afterwards.
     '''
+    if len(tables.nodes.metadata) > 0:
+        warnings.warn(
+                "The provided tree sequence already has some nodes with "
+                "metadata; this metadata will be overwritten."
+        )
+    if len(tables.individuals.metadata) > 0:
+        warnings.warn(
+                "The provided tree sequence already has some individuals with "
+                "metadata; this metadata will be overwritten."
+        )
     ind_population = np.full(tables.individuals.num_rows, -1, dtype="int")
     ind_slim_id = np.full(tables.individuals.num_rows, 0, dtype='int')
     nid = 0
@@ -1025,12 +1035,8 @@ def _annotate_nodes_individuals(tables, age):
             md["slim_id"] = nid
             nid += 1
         else:
-            md = n.metadata
+            md = None
         node_metadata.append(md)
-        print("....")
-        print(md)
-        print(tables.nodes.metadata_schema.validate_and_encode_row(md))
-
     nms = tables.nodes.metadata_schema
     tables.nodes.packset_metadata([
         nms.validate_and_encode_row(x)
@@ -1053,7 +1059,7 @@ def _annotate_nodes_individuals(tables, age):
             # so no big deal
             ind_flags[j] |= INDIVIDUAL_ALIVE
         else:
-            md = ind.metadata
+            md = None
         ind_metadata.append(md)
     tables.individuals.set_columns(
         flags=ind_flags,

tests/test_annotation.py

@@ -263,6 +263,42 @@ def test_warns_overwriting_mutations(self, helper_functions):
         with pytest.warns(Warning, match="already has.*metadata"):
             slim_ts = pyslim.annotate(ts, model_type="WF", tick=1) 
 
+    def test_warns_and_overwrites_node_metadata(self, helper_functions):
+        ts = msprime.sim_ancestry(
+                4,
+                population_size=10,
+                sequence_length=10,
+                recombination_rate=0.01,
+                random_seed=100,
+        )
+        tables = ts.dump_tables()
+        tables.nodes.clear()
+        for n in ts.nodes():
+            tables.nodes.append(n.replace(metadata=b'abc'))
+        ts = tables.tree_sequence()
+        with pytest.warns(Warning, match="already has.*metadata"):
+            slim_ts = pyslim.annotate(ts, model_type="WF", tick=1) 
+            for n in slim_ts.nodes():
+                assert n.is_sample() or n.metadata is None
+
+    def test_warns_and_overwrites_individual_metadata(self, helper_functions):
+        ts = msprime.sim_ancestry(
+                4,
+                population_size=10,
+                sequence_length=10,
+                recombination_rate=0.01,
+                random_seed=100,
+        )
+        tables = ts.dump_tables()
+        tables.individuals.clear()
+        for n in ts.individuals():
+            tables.individuals.append(n.replace(metadata=b'abc'))
+        ts = tables.tree_sequence()
+        with pytest.warns(Warning, match="already has.*metadata"):
+            slim_ts = pyslim.annotate(ts, model_type="WF", tick=1) 
+            for ind in slim_ts.individuals():
+                assert slim_ts.node(ind.nodes[0]).is_sample() or ind.metadata is None
+
     def test_just_simulate(self, helper_functions, tmp_path):
         ts = msprime.sim_ancestry(
                 4,