From 85dc23f6111d555a0135c6161bcc4651d608e75b Mon Sep 17 00:00:00 2001 From: "Kevin R. Thornton" Date: Mon, 13 Nov 2023 14:04:24 -0800 Subject: [PATCH] fast finish and extended discussion --- fwdpy11/_types/model_params.py | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/fwdpy11/_types/model_params.py b/fwdpy11/_types/model_params.py index 5365fbcb2..9962df3f3 100644 --- a/fwdpy11/_types/model_params.py +++ b/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))