Update return value of conditional models. (#1163)

* mutation_index is now Optional[int]
* added fixation_index, which is Optional[int]
* Added tests of prune_selected = True
* Update vignettes
* Add auto-attribute docs for a population's
  fixation and fixation time properties

Closes #1160

doc/misc/changelog.md

@@ -12,6 +12,14 @@ Breaking changes
   PR {pr}`1161`.
   Issue {issue}`934`.
 
+Fixes
+
+* {class}`fwdpy11.conditional_models.ConditionalModelOutput` now contains
+  fields allowing one to distinguish if the tracked mutation is still present
+  in {attr}`fwdpy11.DiploidPopulation.mutations` and/or {attr}`fwdpy11.DiploidPopulation.fixations`
+  PR {pr}`1163`.
+  Issue {issue}`1160`.
+
 New features
 
 * {func}`fwdpy11.DiploidPopulation.create_from_tskit` is now able to restore

doc/pages/types.md

@@ -31,6 +31,8 @@ kernelspec:
 
    .. autoattribute:: fwdpy11.DiploidPopulation.generation
    .. autoattribute:: fwdpy11.DiploidPopulation.mutations
+   .. autoattribute:: fwdpy11.DiploidPopulation.fixations
+   .. autoattribute:: fwdpy11.DiploidPopulation.fixation_times
    .. autoattribute:: fwdpy11.DiploidPopulation.haploid_genomes
    .. autoattribute:: fwdpy11.DiploidPopulation.genetic_values
    .. autoattribute:: fwdpy11.DiploidPopulation.ancient_sample_genetic_values

doc/short_vignettes/trackmutationfates.md

@@ -99,10 +99,12 @@ output = fwdpy11.conditional_models.track_added_mutation(
 When tracking deleterious variants, it is unlikely that they will be around at the end of the simulation:
 
 ```{code-cell} python
-try:
+if output.mutation_index is not None:
     print(output.pop.mutations[output.mutation_index])
-except IndexError as _:
-    print(f"mutation {output.mutation_index} is no longer in the population!") 
+elif output.fixation_index is not None:
+    print(output.pop.fixations[output.fixation_index])
+else:
+    print("Our mutation is no longer in the population!") 
 ```
 
 ### Recording all generations of the mutation's sojourn
@@ -131,10 +133,12 @@ Now, our mutation is present in nodes in our tree sequence.
 Let's try to print it again:
 
 ```{code-cell} python
-try:
+if output.mutation_index is not None:
     print(output.pop.mutations[output.mutation_index])
-except IndexError as _:
-    output.mutation_index(f"mutation {output.mutation_index} is no longer in the population!") 
+elif output.fixation_index is not None:
+    print(output.pop.fixations[output.fixation_index])
+else:
+    print("Our mutation is no longer in the population!") 
 ```
 
 Let's track this variant's frequency at each time point:

fwdpy11/conditional_models/__init__.py

@@ -219,8 +219,10 @@ class ConditionalModelOutput:
     """The population with the added mutation"""
     params: fwdpy11.ModelParams
     """The evolved model parameters"""
-    mutation_index: int
+    mutation_index: typing.Optional[int]
     """The index of the new mutation in pop.mutations"""
+    fixation_index: typing.Optional[int]
+    """The index of the new mutation in pop.fixations"""
     num_descendant_nodes: int
     """The number of alive nodes initially containing the new mutation"""
 

fwdpy11/conditional_models/_track_added_mutation.py

@@ -376,6 +376,8 @@ def _track_added_mutation(
         _sampling_policy,
     )
 
+    tracked_mutation_key = pcopy.mutations[idx].key
+
     internal_options = _InternalSweepEvolveOptions()
 
     finished = False
@@ -422,9 +424,20 @@ def _track_added_mutation(
 
     assert pop_to_return is not None
 
+    if idx < len(pop_to_return.mutations):
+        mutation_index = idx
+    else:
+        mutation_index = None
+    if mutation_index is not None:
+        assert pop_to_return.mutations[mutation_index].key == tracked_mutation_key
+    fixation_index = None
+    for i, f in enumerate(pop_to_return.fixations):
+        if f.key == tracked_mutation_key:
+            fixation_index = i
     return ConditionalModelOutput(
         pop=pop_to_return,
         params=local_params,
-        mutation_index=idx,
+        mutation_index=mutation_index,
+        fixation_index=fixation_index,
         num_descendant_nodes=ndescendants,
     )