add support for individual offsets in Individual

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -467,6 +467,8 @@
 <p class="p6">The <span class="s1">chromosomes</span> parameter may be <span class="s1">NULL</span>, or may provide a vector of chromosomes specified by their <span class="s1">integer</span> id, <span class="s1">string</span> symbol, or with the <span class="s1">Chromosome</span> object itself.<span class="Apple-converted-space">  </span>If <span class="s1">chromosomes</span> is <span class="s1">NULL</span> (the default), mutations associated with every chromosome are returned; no filtering by chromosome is done.<span class="Apple-converted-space">  </span>Otherwise, only mutations associated with the specified chromosomes will be returned.</p>
 <p class="p6">The returned vector will contain tranches of mutations, one tranche per chromosome, in the order that the chromosomes were specified (if <span class="s1">chromosomes</span> is non-<span class="s1">NULL</span>) or the order the chromosomes were defined in the model (if <span class="s1">chromosomes</span> is <span class="s1">NULL</span>).<span class="Apple-converted-space">  </span>Within a given tranche, the mutations for that chromosome will be returned in sorted order by <span class="s1">position</span>.<span class="Apple-converted-space">  </span>(If more than one mutation associated with a given chromosome exists at the same position, the order in which those mutations are returned is undefined.)</p>
 <p class="p6">This method replaces the deprecated method <span class="s1">uniqueMutationsOfType()</span>, while providing additional useful options.<span class="Apple-converted-space">  </span>It is particularly useful for efficient, vectorized assessment of the homozygous versus heterozygous state of the mutations contained by an individual, which is otherwise difficult to assess efficiently.</p>
+<p class="p5">– (float)offsetForTrait([Nio&lt;Trait&gt; trait = NULL])</p>
+<p class="p6">Returns 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.<span class="Apple-converted-space">  </span>Offsets for a given target individual will be returned consecutively in the order in which the traits are specified by <span class="s1">trait</span>.</p>
 <p class="p5">+ (void)outputIndividuals([Ns$ filePath = NULL], [logical$ append = F], [Niso&lt;Chromosome&gt;$ chromosome = NULL], [logical$ spatialPositions = T], [logical$ ages = T], [logical$ ancestralNucleotides = F], [logical$ pedigreeIDs = F], [logical$ objectTags = F])</p>
 <p class="p6">Output the state of the target vector of individuals in SLiM's own format.<span class="Apple-converted-space">  </span>If the optional parameter <span class="s1">filePath</span> is <span class="s1">NULL</span> (the default), output will be sent to Eidos’s output stream.<span class="Apple-converted-space">  </span>Otherwise, output will be sent to the filesystem path specified by <span class="s1">filePath</span>, overwriting that file if <span class="s1">append</span> if <span class="s1">F</span>, or appending to the end of it if <span class="s1">append</span> is <span class="s1">T</span>.<span class="Apple-converted-space">  </span>This method is quite similar to the <span class="s1">Species</span> method <span class="s1">outputFull()</span>, but (1) it can produce output for any vector of individuals, not always for the entire population; (2) it does not support output in a binary format; (3) it can produce output regarding the genetics for all chromosomes or for just one focal chromosome; and (4) there is no corresponding read method, as r<span class="s1">eadFromPopulationFile()</span> can read the data saved by <span class="s1">outputFull()</span>.</p>
 <p class="p6">The <span class="s1">chromosome</span> parameter specifies a focal chromosome for which the genetics of the target individuals will be output.<span class="Apple-converted-space">  </span>If <span class="s1">chromosome</span> is <span class="s1">NULL</span>, all chromosomes will be output; otherwise, <span class="s1">chromosome</span> may specify the focal chromosome with an <span class="s1">integer</span> chromosome id, a <span class="s1">string</span> chromosome symbol, or a <span class="s1">Chromosome</span> object.</p>
@@ -494,6 +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="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="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

@@ -3797,6 +3797,22 @@ This method replaces the deprecated method
 \f4\fs20 , while providing additional useful options.  It is particularly useful for efficient, vectorized assessment of the homozygous versus heterozygous state of the mutations contained by an individual, which is otherwise difficult to assess efficiently.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
+\f3\fs18 \cf2 \'96\'a0(float)offsetForTrait([Nio<Trait>\'a0trait\'a0=\'a0NULL])\
+\pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
+
+\f4\fs20 \cf2 Returns the individual offset(s) for the trait(s) specified by 
+\f3\fs18 trait
+\f4\fs20 .  The traits can be specified as 
+\f3\fs18 integer
+\f4\fs20  indices of traits in the species, or directly as 
+\f3\fs18 Trait
+\f4\fs20  objects; 
+\f3\fs18 NULL
+\f4\fs20  represents all of the traits in the species, in the order in which they were defined.  Offsets for a given target individual will be returned consecutively in the order in which the traits are specified by 
+\f3\fs18 trait
+\f4\fs20 .\
+\pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
 \f3\fs18 \cf2 +\'a0(void)outputIndividuals([Ns$\'a0filePath\'a0=\'a0NULL], [logical$\'a0append\'a0=\'a0F], [Niso<Chromosome>$\'a0chromosome\'a0=\'a0NULL], [logical$\'a0spatialPositions\'a0=\'a0T], [logical$\'a0ages\'a0=\'a0T], [logical$\'a0ancestralNucleotides\'a0=\'a0F], [logical$\'a0pedigreeIDs\'a0=\'a0F], [logical$\'a0objectTags\'a0=\'a0F])\
 \pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
 
@@ -4155,6 +4171,39 @@ 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])\
+\pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
+
+\f4\fs20 \cf2 Sets the individual offset(s) for the trait(s) specified by 
+\f3\fs18 trait
+\f4\fs20 .  The traits can be specified as 
+\f3\fs18 integer
+\f4\fs20  indices of traits in the species, or directly as 
+\f3\fs18 Trait
+\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 
+\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, 
+\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
+\f4\fs20  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.  In the fourth pattern, 
+\f3\fs18 offset
+\f4\fs20  is of length equal to the number of specified traits times the number of target individuals; this uses 
+\f3\fs18 offset
+\f4\fs20  to provide a different offset value for each trait in each individual, using consecutive values from 
+\f3\fs18 offset
+\f4\fs20  to set the offset for each of the specified traits in one individual before moving to the next individual.\
+\pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
 \f3\fs18 \cf2 \expnd0\expndtw0\kerning0
 +\'a0(void)setSpatialPosition(float\'a0position)\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0

VERSIONS

@@ -52,6 +52,9 @@ multitrait branch:
 		added C++ IsPureNeutralDFE() method to represent whether all of the effects of a given mutation type are all neutral
 	add Individual properties for each trait in the individual's species, allowing direct access
 		this was done by adding GetProperty_NO_SIGNATURE() / SetProperty_NO_SIGNATURE() methods called by EidosValue_Object::GetPropertyOfElements() and EidosValue_Object::SetPropertyOfElements() to support properties with no signature
+	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])
 
 
 version 5.1 (Eidos version 4.1):