fast finish and extended discussion

fwdpy11/_types/model_params.py

@@ -156,6 +156,27 @@ class ModelParams(object):
         recombination rates for details.
 
 
+    If ``prune_selected`` is ``True``, fixations will be remove
+    during the simulation. This removal is a sensible thing to do
+    if individual relative fitnesses are constant up to a multiplicative
+    constant.
+
+    In a multiplicative model, removing a fixation would be equivalent to dividing all values
+    by the same value, which does not affect their *relative*
+    values.
+
+    However, removing a fixation in an additive model *does* change
+    the relative values.
+    Likewise, mappings from genetic value to fitness such as Gaussian
+    stabilizing selection, or adding random noise to genetic values,
+    also changes relative values.
+
+    This class will raise a warning if ``prune_selected`` is ``True``
+    and there is a possibility that removing fixations will change
+    relative fitness.
+    Such warnings should not be ignored as they suggest that a simulation
+    may not be giving biologically sensible results.
+
     .. versionadded:: 0.1.1
 
     .. versionchanged:: 0.2.0
@@ -314,20 +335,23 @@ def validate_simlen(self, attribute, value):
 
     def _is_multiplicative(self, gvalue):
         multiplicative = True
+
         if not isinstance(gvalue, fwdpy11.Multiplicative):
             multiplicative = False
-        if gvalue.gvalue_to_fitness is not None:
-            if not isinstance(gvalue.gvalue_to_fitness, fwdpy11.GeneticValueIsFitness):
+        if multiplicative is True:
+            if gvalue.gvalue_to_fitness is not None:
+                if not isinstance(gvalue.gvalue_to_fitness, fwdpy11.GeneticValueIsFitness):
+                    multiplicative = False
+            if gvalue.noise is not None and not isinstance(gvalue.noise, fwdpy11.NoNoise):
                 multiplicative = False
-        if gvalue.noise is not None and not isinstance(gvalue.noise, fwdpy11.NoNoise):
-            multiplicative = False
 
         if not multiplicative and self.prune_selected is True:
             msg = f"""
             the genetic value {gvalue} may not be proportional to fitness
             up to a multiplicative constant. Because prune_selected=True,
             the removal of fixations during simulation may lead to unexpected
-            or incorrect results.
+            or incorrect results. See the ModelParams documentation
+            for discussion.
             """
             warnings.warn(fwdpy11.PruneSelectedWarning(msg))