add some multitrait unit tests; fix a couple of bugs

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -496,9 +496,9 @@
 <p class="p6">Note that this relatedness is simply pedigree-based relatedness, and does not necessarily correspond to genetic relatedness, because of the effects of factors like assortment and recombination.<span class="Apple-converted-space">  </span>If a metric of actual genetic relatedness is desired, tree-sequence recording can be used after simulation is complete, to compute the exact genetic relatedness between individuals based upon the complete ancestry tree (a topic which is beyond the scope of this manual).<span class="Apple-converted-space">  </span>Actual genetic relatedness cannot presently be calculated during a simulation run; the information is implicitly contained in the recorded tree-sequence tables, but calculating it is too computationally expensive to be reasonable.</p>
 <p class="p6">This method assumes that the grandparents (or the parents, if grandparental information is not available) are themselves unrelated and that they are not inbred; this assumption is necessary because we have no information about their parentage, since SLiM’s pedigree tracking information only goes back two generations.<span class="Apple-converted-space">  </span>Be aware that in a model where inbreeding or selfing occurs at all (including “incidental selfing”, where a hermaphroditic individual happens to choose itself as a mate), some level of “background relatedness” will be present and this assumption will be violated.<span class="Apple-converted-space">  </span>In such circumstances, <span class="s1">relatedness()</span> will therefore tend to underestimate the degree of relatedness between individuals, and the greater the degree of inbreeding, the greater the underestimation will be.<span class="Apple-converted-space">  </span>If inbreeding is allowed in a model – and particularly if it is common – the results of <span class="s1">relatedness()</span> should therefore not be taken as an estimate of <i>absolute</i> relatedness, but can still be useful as an estimate of <i>relative</i> relatedness (indicating that, say, A appears from the information available to be more closely related to B than it is to C).</p>
 <p class="p6">See also <span class="s1">sharedParentCount()</span> for a different metric of relatedness.</p>
-<p class="p5">– (void)setOffsetForTrait([Nio&lt;Trait&gt; trait = NULL], [Nif offset = NULL])</p>
+<p class="p5">+ (void)setOffsetForTrait([Nio&lt;Trait&gt; trait = NULL], [Nif offset = NULL])</p>
 <p class="p6">Sets the individual offset(s) for the trait(s) specified by <span class="s1">trait</span>.<span class="Apple-converted-space">  </span>The traits can be specified as <span class="s1">integer</span> indices of traits in the species, or directly as <span class="s1">Trait</span> objects; <span class="s1">NULL</span> represents all of the traits in the species, in the order in which they were defined.</p>
-<p class="p6">The parameter <span class="s1">offset</span> must follow one of four patterns.<span class="Apple-converted-space">  </span>In the first pattern, offset is <span class="s1">NULL</span>; this sets the offset for each of the specified traits to its default value (<span class="s1">0.0</span> for additive traits, <span class="s1">1.0</span> for multiplicative traits) in each target individual.<span class="Apple-converted-space">  </span>In the second pattern, <span class="s1">offset</span> is a singleton value; this sets the given offset for each of the specified traits in each target individual.<span class="Apple-converted-space">  </span>In the third pattern, <span class="s1">offset</span> is of length equal to the number of specified traits; this sets the offset for each of the specified traits to the corresponding offset value in each target individual.<span class="Apple-converted-space">  </span>In the fourth pattern, <span class="s1">offset</span> is of length equal to the number of specified traits times the number of target individuals; this uses <span class="s1">offset</span> to provide a different offset value for each trait in each individual, using consecutive values from <span class="s1">offset</span> to set the offset for each of the specified traits in one individual before moving to the next individual.</p>
+<p class="p6">The parameter <span class="s1">offset</span> must follow one of four patterns.<span class="Apple-converted-space">  </span>In the first pattern, offset is <span class="s1">NULL</span>; this draws the offset for each of the specified traits from each trait’s individual-offset distribution (defined by each trait’s <span class="s1">individualOffsetMean</span> and <span class="s1">individualOffsetSD</span> properties) in each target individual.<span class="Apple-converted-space">  </span>(Note that individual offsets are automatically drawn from these distributions when an individual is created; this re-draws new offset values.)<span class="Apple-converted-space">  </span>In the second pattern, <span class="s1">offset</span> is a singleton value; this sets the given offset for each of the specified traits in each target individual.<span class="Apple-converted-space">  </span>In the third pattern, <span class="s1">offset</span> is of length equal to the number of specified traits; this sets the offset for each of the specified traits to the corresponding offset value in each target individual.<span class="Apple-converted-space">  </span>In the fourth pattern, <span class="s1">offset</span> is of length equal to the number of specified traits times the number of target individuals; this uses <span class="s1">offset</span> to provide a different offset value for each trait in each individual, using consecutive values from <span class="s1">offset</span> to set the offset for each of the specified traits in one individual before moving to the next individual.</p>
 <p class="p5"><span class="s3">+ (void)setSpatialPosition(float position)</span></p>
 <p class="p6"><span class="s3">Sets the spatial position of the individual (as accessed through the </span><span class="s4">spatialPosition</span><span class="s3"> property).<span class="Apple-converted-space">  </span>The length of </span><span class="s4">position</span><span class="s3"> (the number of coordinates in the spatial position of an individual) depends upon the spatial dimensionality declared with </span><span class="s4">initializeSLiMOptions()</span><span class="s3">.<span class="Apple-converted-space">  </span>If the spatial dimensionality is zero (as it is by default), it is an error to call this method.<span class="Apple-converted-space">  </span>The elements of </span><span class="s4">position</span><span class="s3"> are set into the values of the </span><span class="s4">x</span><span class="s3">, </span><span class="s4">y</span><span class="s3">, and </span><span class="s4">z</span><span class="s3"> properties (if those properties are encompassed by the spatial dimensionality of the simulation).<span class="Apple-converted-space">  </span>In other words, if the declared dimensionality is </span><span class="s4">"xy"</span><span class="s3">, calling </span><span class="s4">individual.setSpatialPosition(c(1.0, 0.5))</span><span class="s3"> property is equivalent to </span><span class="s4">individual.x = 1.0; individual.y = 0.5</span><span class="s3">; </span><span class="s4">individual.z</span><span class="s3"> is not set (even if a third value is supplied in </span><span class="s4">position</span><span class="s3">) since it is not encompassed by the simulation’s dimensionality in this example.</span></p>
 <p class="p6"><span class="s3">Note that this is an Eidos class method, somewhat unusually, which allows it to work in a special way when called on a vector of individuals.<span class="Apple-converted-space">  </span>When the target vector of individuals is non-singleton, this method can do one of two things.<span class="Apple-converted-space">  </span>If </span><span class="s4">position</span><span class="s3"> contains just a single point (i.e., is equal in length to the spatial dimensionality of the model), the spatial position of all of the target individuals will be set to the given point.<span class="Apple-converted-space">  </span>Alternatively, if </span><span class="s4">position</span><span class="s3"> contains one point per target individual (i.e., is equal in length to the number of individuals multiplied by the spatial dimensionality of the model), the spatial position of each target individual will be set to the corresponding point from </span><span class="s4">position</span><span class="s3"> (where the point data is concatenated, not interleaved, just as it would be returned by accessing the </span><span class="s4">spatialPosition</span><span class="s3"> property on the vector of target individuals).<span class="Apple-converted-space">  </span>Calling this method with a </span><span class="s4">position</span><span class="s3"> vector of any other length is an error.</span></p>

SLiMgui/SLiMHelpClasses.rtf

@@ -4171,7 +4171,7 @@ See also
 \f4\fs20  for a different metric of relatedness.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f3\fs18 \cf2 \'96\'a0(void)setOffsetForTrait([Nio<Trait>\'a0trait\'a0=\'a0NULL], [Nif offset = NULL])\
+\f3\fs18 \cf2 +\'a0(void)setOffsetForTrait([Nio<Trait>\'a0trait\'a0=\'a0NULL], [Nif\'a0offset\'a0=\'a0NULL])\
 \pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
 
 \f4\fs20 \cf2 Sets the individual offset(s) for the trait(s) specified by 
@@ -4183,15 +4183,16 @@ See also
 \f4\fs20  objects; 
 \f3\fs18 NULL
 \f4\fs20  represents all of the traits in the species, in the order in which they were defined.\
-The parameter 
+\pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
+\cf2 The parameter 
 \f3\fs18 offset
 \f4\fs20  must follow one of four patterns.  In the first pattern, offset is 
 \f3\fs18 NULL
-\f4\fs20 ; this sets the offset for each of the specified traits to its default value (
-\f3\fs18 0.0
-\f4\fs20  for additive traits, 
-\f3\fs18 1.0
-\f4\fs20  for multiplicative traits) in each target individual.  In the second pattern, 
+\f4\fs20 ; this draws the offset for each of the specified traits from each trait\'92s individual-offset distribution (defined by each trait\'92s 
+\f3\fs18 individualOffsetMean
+\f4\fs20  and 
+\f3\fs18 individualOffsetSD
+\f4\fs20  properties) in each target individual.  (Note that individual offsets are automatically drawn from these distributions when an individual is created; this re-draws new offset values.)  In the second pattern, 
 \f3\fs18 offset
 \f4\fs20  is a singleton value; this sets the given offset for each of the specified traits in each target individual.  In the third pattern, 
 \f3\fs18 offset

VERSIONS

@@ -55,6 +55,7 @@ multitrait branch:
 	add support in Individual for the individual's offset for each trait
 		add -(float)offsetForTrait([Nio<Trait> trait = NULL])
 		add +(void)setOffsetForTrait([Nio<Trait> trait = NULL], [Nif offset = NULL])
+		draw an individual's trait offsets from the trait individual-offset distributions, at the individual's moment of generation
 
 
 version 5.1 (Eidos version 4.1):

core/individual.cpp

@@ -53,6 +53,7 @@ bool Individual::s_any_individual_fitness_scaling_set_ = false;
 
 // individual first, haplosomes later; this is the new multichrom paradigm
 // BCH 10/12/2024: Note that this will rarely be called after simulation startup; see NewSubpopIndividual()
+// BCH 10/12/2025: Note also that NewSubpopIndividual() will rarely be called in WF models; see the Munge...() methods
 Individual::Individual(Subpopulation *p_subpopulation, slim_popsize_t p_individual_index, IndividualSex p_sex, slim_age_t p_age, double p_fitness, float p_mean_parent_age) :
 #ifdef SLIMGUI
 	color_set_(false),
@@ -83,44 +84,69 @@ Individual::Individual(Subpopulation *p_subpopulation, slim_popsize_t p_individu
 	}
 
 	// Set up per-trait information such as phenotype caches and individual offsets
+	_DrawTraitOffsets();
+	
+	// Initialize tag values to the "unset" value
+	tag_value_ = SLIM_TAG_UNSET_VALUE;
+	tagF_value_ = SLIM_TAGF_UNSET_VALUE;
+	tagL0_set_ = false;
+	tagL1_set_ = false;
+	tagL2_set_ = false;
+	tagL3_set_ = false;
+	tagL4_set_ = false;
+	
+	// Initialize x/y/z to 0.0, only when leak-checking (they show up as used before initialized in Valgrind)
+#if SLIM_LEAK_CHECKING
+	spatial_x_ = 0.0;
+	spatial_y_ = 0.0;
+	spatial_z_ = 0.0;
+#endif
+}
+
+void Individual::_DrawTraitOffsets(void)
+{
+	// Set up per-trait individual-level information such as individual offsets.  This is called by
+	// Individual::Individual(), but also in various other places where individuals are re-used.
+	
+	// FIXME MULTITRAIT: this will probably be a pain point; maybe we can skip it if offsets have never been changed by the user?
+	// I imagine a design where there is a bool flag that says "the offsets for this individual have been initialized".  This
+	// would allow a lazy caching scheme; if an offset is queried or set, all the offsets in that individual are then set up
+	// and the flag is set to indicate that it has been set up.  Every tick, offsets will probably be needed for every individual
+	// in order to calculate phenotypes, so we can't avoid that work altogether.  But we can avoid doing it one individual at a
+	// time, with a lot of setup overhead here to get the traits, get the RNG, etc.; we could do it in bulk for all individuals
+	// in a species, at the point when we're calculating everybody's phenotypes, which would allow us to do it very quickly.
+	// The only difficulty I see with such a lazy caching scheme is: if the trait's individual-offset distribution is *changed*
+	// by the script, then at that moment, the individual offsets of every alive individual need to be initialized using the old
+	// distribution before it changes, otherwise they will (incorrectly) draw from the new distribution.  So that's a little
+	// tricky, but doable.  I'm going to put off doing this until later, though, so as to not get bogged down.  BCH 10/12/2025
+	
+	// FIXME MULTITRAIT: note also that if all trait individual offsets have SD == 0, and thus initialize to a constant, we
+	// could use a buffer of default trait values that we memcpy() in to each individual's offset buffer.  That would be
+	// a strategy that could easily be used when we bulk-initialize the offsets of all uninitialized individuals, for example.
+	
+	// FIXME MULTITRAIT: also, _DrawIndividualOffset() looks up the RNG; when doing this work in bulk, we can look up the RNG
+	// once and then pass it in to DrawIndividualOffset() instead of having it look it up.  Much optimization to do in bulk.
+	
 	Species &species = subpopulation_->species_;
 	const std::vector<Trait *> &traits = species.Traits();
 	int trait_count = (int)traits.size();
 
 	if (trait_count == 1)
 	{
-		// FIXME MULTITRAIT: DefaultOffset() has a branch; maybe better for each trait to have a cached slim_effect_t for it?  or maybe not?
 		offsets_for_traits_ = &offset_for_trait_0_;
-		offset_for_trait_0_ = traits[0]->DefaultOffset();
+		offset_for_trait_0_ = traits[0]->DrawIndividualOffset();
 	}
 	else if (trait_count == 0)
 	{
 		offsets_for_traits_ = nullptr;
 	}
 	else
 	{
-		// FIXME MULTITRAIT: we could keep a buffer of default trait values in the Species, and just memcpy() here
 		offsets_for_traits_ = static_cast<slim_effect_t *>(malloc(trait_count * sizeof(slim_effect_t)));
 
 		for (int trait_index = 0; trait_index < trait_count; ++trait_index)
-			offsets_for_traits_[trait_index] = traits[trait_index]->DefaultOffset();
+			offsets_for_traits_[trait_index] = traits[trait_index]->DrawIndividualOffset();
 	}
-	
-	// Initialize tag values to the "unset" value
-	tag_value_ = SLIM_TAG_UNSET_VALUE;
-	tagF_value_ = SLIM_TAGF_UNSET_VALUE;
-	tagL0_set_ = false;
-	tagL1_set_ = false;
-	tagL2_set_ = false;
-	tagL3_set_ = false;
-	tagL4_set_ = false;
-	
-	// Initialize x/y/z to 0.0, only when leak-checking (they show up as used before initialized in Valgrind)
-#if SLIM_LEAK_CHECKING
-	spatial_x_ = 0.0;
-	spatial_y_ = 0.0;
-	spatial_z_ = 0.0;
-#endif
 }
 
 Individual::~Individual(void)
@@ -4051,11 +4077,11 @@ EidosValue_SP Individual_Class::ExecuteMethod_setOffsetForTrait(EidosGlobalStrin
 
 	if (offset_value->Type() == EidosValueType::kValueNULL)
 	{
-		// pattern 1: setting the default offset value for each trait in one or more individuals
+		// pattern 1: drawing a default offset value for each trait in one or more individuals
 		for (int64_t trait_index : trait_indices)
 		{
 			Trait *trait = species->Traits()[trait_index];
-			slim_effect_t offset = trait->DefaultOffset();
+			slim_effect_t offset = trait->DrawIndividualOffset();
 
 			for (int individual_index = 0; individual_index < individuals_count; ++individual_index)
 			{

core/individual.h

@@ -169,6 +169,8 @@ class Individual : public EidosDictionaryUnretained
 	Individual(Subpopulation *p_subpopulation, slim_popsize_t p_individual_index, IndividualSex p_sex, slim_age_t p_age, double p_fitness, float p_mean_parent_age);
 	virtual ~Individual(void) override;
 
+	void _DrawTraitOffsets(void);
+	
 	inline __attribute__((always_inline)) void ClearColor(void) {
 #ifdef SLIMGUI
 		// BCH 3/23/2025: color variables now only exist in SLiMgui, to save on memory footprint

core/slim_test.cpp

@@ -461,6 +461,7 @@ int RunSLiMTests(void)
 	_RunChromosomeTests();
 	_RunMutationTests();
 	_RunHaplosomeTests(temp_path);
+	_RunMultitraitTests();
 	_RunSubpopulationTests();
 	_RunIndividualTests();
 	_RunSubstitutionTests();

core/slim_test.h

@@ -49,6 +49,7 @@ extern void _RunGenomicElementTests(void);
 extern void _RunChromosomeTests(void);
 extern void _RunMutationTests(void);
 extern void _RunHaplosomeTests(const std::string &temp_path);
+extern void _RunMultitraitTests(void);
 extern void _RunSubpopulationTests(void);
 extern void _RunIndividualTests(void);
 extern void _RunErrorPositionTests(void);