add Trait class, initializeTrait(), and related stuff

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -184,6 +184,8 @@
 <p class="p6">All of the <span class="s1">Species</span> objects defined in the simulation (in species declaration order).</p>
 <p class="p5">allSubpopulations =&gt; (object&lt;Subpopulation&gt;)</p>
 <p class="p6">All of the <span class="s1">Subpopulation</span> objects defined in the simulation.</p>
+<p class="p5">allTraits =&gt; (object&lt;Trait&gt;)</p>
+<p class="p6">All of the <span class="s1">Trait</span> objects defined in the simulation (in species declaration order, primarily, and in order of their index within a species, secondarily).</p>
 <p class="p5">cycleStage =&gt; (string$)</p>
 <p class="p6">The current cycle stage, as a <span class="s1">string</span>.<span class="Apple-converted-space">  </span>The values of this property essentially mirror the cycle stages of WF and nonWF models.<span class="Apple-converted-space">  </span>Common values include <span class="s1">"first"</span> (during execution of <span class="s1">first()</span> events), <span class="s1">"early"</span> (during execution of <span class="s1">early()</span> events), <span class="s1">"reproduction"</span> (during offspring generation), <span class="s1">"fitness"</span> (during fitness evaluation), <span class="s1">"survival"</span> (while applying selection and mortality in nonWF models), and <span class="s1">"late"</span> (during execution of <span class="s1">late()</span> events).</p>
 <p class="p6">Other possible values include <span class="s1">"begin"</span> (during internal setup before each cycle), <span class="s1">"tally"</span> (while tallying mutation reference counts and removing fixed mutations), <span class="s1">"swap"</span> (while swapping the offspring generation into the parental generation in WF models), <span class="s1">"end"</span> (during internal bookkeeping after each cycle), and <span class="s1">"console"</span> (during the in-between-ticks state in which commands in SLiMgui’s Eidos console are executed).<span class="Apple-converted-space">  </span>It would probably be a good idea not to use this latter set of values; they are probably not user-visible during ordinary model execution anyway.</p>
@@ -940,6 +942,8 @@
 <p class="p4">A vector of <span class="s1">Substitution</span> objects, representing all mutations that have been fixed in this species.</p>
 <p class="p3">tag &lt;–&gt; (integer$)</p>
 <p class="p4">A user-defined <span class="s1">integer</span> value.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is initially undefined<span class="s7">, and it is an error to try to read it</span>; if you wish it to have a defined value, you must arrange that yourself by explicitly setting its value prior to using it elsewhere in your code.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is not used by SLiM; it is free for you to use.<span class="Apple-converted-space">  </span>See also the <span class="s1">getValue()</span> and <span class="s1">setValue()</span> methods<span class="s5"> (provided by the </span><span class="s6">Dictionary</span><span class="s5"> class; see the Eidos manual)</span>, for another way of attaching state to the simulation.</p>
+<p class="p5">traits =&gt; (object&lt;Trait&gt;)</p>
+<p class="p6">The <span class="s1">Trait</span> objects defined in the species.<span class="Apple-converted-space">  </span>These are guaranteed to be in sorted order by their index (i.e., by the order in which they were defined).</p>
 <p class="p2"><i>5.16.2<span class="Apple-converted-space">  </span></i><span class="s1"><i>Species</i></span><i> methods</i></p>
 <p class="p5">– (object&lt;Dictionary&gt;$)addPatternForClone(iso&lt;Chromosome&gt;$ chromosome, No&lt;Dictionary&gt;$ pattern, object&lt;Individual&gt;$ parent, [Ns$ sex = NULL])</p>
 <p class="p6">Adds an inheritance dictionary for the specified chromosome to the pattern dictionary <span class="s1">pattern</span>, representing producing a clone of <span class="s1">parent</span>, with sex optionally specified by <span class="s1">sex</span>.<span class="Apple-converted-space">  </span>The parameter <span class="s1">chromosome</span> can provide a chromosome <span class="s1">id</span> (an <span class="s1">integer</span>), a chromosome <span class="s1">symbol</span> (a <span class="s1">string</span>), or a <span class="s1">Chromosome</span> object.<span class="Apple-converted-space">  </span>The resulting pattern dictionary is intended for use with the <span class="s1">Subpopulation</span> method <span class="s1">addMultiRecombinant()</span>; see that method for background on the use of pattern dictionaries.</p>
@@ -1056,6 +1060,10 @@
 <p class="p6">This method is shorthand for getting the <span class="s1">mutations</span> property of the subpopulation, and then using operator <span class="s1">[]</span> to select only mutations with the desired properties; besides being much simpler than the equivalent Eidos code, it is also much faster.<span class="Apple-converted-space">  </span>Note that if you only need to select on mutation type, the <span class="s1">mutationsOfType()</span> method will be even faster.</p>
 <p class="p5">– (object&lt;Substitution&gt;)substitutionsOfType(io&lt;MutationType&gt;$ mutType)</p>
 <p class="p6">Returns an <span class="s1">object</span> vector of all the substitutions that are of the type specified by <span class="s1">mutType</span>, out of all of the substitutions that are currently present in the species.<span class="Apple-converted-space">  </span>This method is provided for speed; it is much faster than the corresponding Eidos code.<span class="Apple-converted-space">  </span>See also <span class="s1">mutationsOfType()</span>.</p>
+<p class="p5">– (object&lt;Trait&gt;)traitsWithIndices(integer indices)</p>
+<p class="p6">Returns a vector of <span class="s1">Trait</span> objects corresponding to the trait indices supplied in <span class="s1">indices</span>, in the same order.<span class="Apple-converted-space">  </span>If any index in <span class="s1">indices</span> does not correspond to a trait in the target species, an error will be raised.<span class="Apple-converted-space">  </span>See also <span class="s1">traitsWithNames()</span>.</p>
+<p class="p5">– (object&lt;Trait&gt;)traitsWithNames(string names)</p>
+<p class="p6">Returns a vector of <span class="s1">Trait</span> objects corresponding to the trait names supplied in <span class="s1">names</span>, in the same order.<span class="Apple-converted-space">  </span>If any name in <span class="s1">names</span> does not correspond to a trait in the target species, an error will be raised.<span class="Apple-converted-space">  </span>See also <span class="s1">traitsWithIndices()</span>.</p>
 <p class="p5"><span class="s3">– (logical$)treeSeqCoalesced(void)</span></p>
 <p class="p6"><span class="s3">Returns the coalescence state for the recorded tree sequence at the last simplification.<span class="Apple-converted-space">  </span>The returned value is a logical singleton flag, </span><span class="s4">T</span><span class="s3"> to indicate that full coalescence was observed at the last tree-sequence simplification (meaning that there is a single ancestral individual that roots all ancestry trees at all sites along the chromosome – although not necessarily the <i>same</i> ancestor at all sites), or </span><span class="s4">F</span><span class="s3"> if full coalescence was not observed.<span class="Apple-converted-space">  </span>For simple models, reaching coalescence may indicate that the model has reached an equilibrium state, but this may not be true in models that modify the dynamics of the model during execution by changing migration rates, introducing new mutations programmatically, dictating non-random mating, etc., so be careful not to attach more meaning to coalescence than it is due; some models may require burn-in beyond coalescence to reach equilibrium, or may not have an equilibrium state at all.<span class="Apple-converted-space">  </span>Also note that some actions by a model, such as adding a new subpopulation, may cause the coalescence state to revert from </span><span class="s4">T</span><span class="s3"> back to </span><span class="s4">F</span><span class="s3"> (at the next simplification), so a return value of </span><span class="s4">T</span><span class="s3"> may not necessarily mean that the model is coalesced at the present moment – only that it <i>was</i> coalesced at the last simplification.</span></p>
 <p class="p6"><span class="s3">This method may only be called if tree sequence recording has been turned on with </span><span class="s4">initializeTreeSeq()</span><span class="s3">; in addition, </span><span class="s4">checkCoalescence=T</span><span class="s3"> must have been supplied to </span><span class="s4">initializeTreeSeq()</span><span class="s3">, so that the necessary work is done during each tree-sequence simplification.<span class="Apple-converted-space">  </span>Since this method does not perform coalescence checking itself, but instead simply returns the coalescence state observed at the last simplification, it may be desirable to call </span><span class="s4">treeSeqSimplify()</span><span class="s3"> immediately before </span><span class="s4">treeSeqCoalesced()</span><span class="s3"> to obtain up-to-date information.<span class="Apple-converted-space">  </span>However, the speed penalty of doing this in every tick would be large, and most models do not need this level of precision; usually it is sufficient to know that the model has coalesced, without knowing whether that happened in the current tick or in a recent preceding tick.</span></p>
@@ -1307,5 +1315,27 @@
 <p class="p4">A user-defined <span class="s1">integer</span> value.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is carried over automatically from the original <span class="s1">Mutation</span> object.<span class="Apple-converted-space">  </span>Apart from that, the value of <span class="s1">tag</span> is not used by SLiM; it is free for you to use.</p>
 <p class="p2"><i>5.18.2<span class="Apple-converted-space">  </span></i><span class="s1"><i>Substitution</i></span><i> methods</i></p>
 <p class="p15"><br></p>
+<p class="p1"><b>5.19<span class="Apple-converted-space">  </span>Class Trait</b></p>
+<p class="p2"><i>5.19.1<span class="Apple-converted-space">  </span></i><span class="s1"><i>Trait</i></span><i> properties</i></p>
+<p class="p5">baselineOffset &lt;–&gt; (float$)</p>
+<p class="p6">The baseline offset for the trait.<span class="Apple-converted-space">  </span>This value is combined – multiplicatively for multiplicative traits, additively for additive traits – with all other effects that influence the trait.<span class="Apple-converted-space">  </span>This provides the baseline trait value, from which individuals will deviate due to mutations and other effects on the trait that they possess.</p>
+<p class="p5">directFitnessEffect &lt;–&gt; (logical$)</p>
+<p class="p6">A <span class="s1">logical</span> flag indicating whether the trait has a direct fitness effect or not.<span class="Apple-converted-space">  </span>If <span class="s1">T</span>, the trait value for an individual is used as a fitness effect for that individual, implying that the trait should be considered a fitness component.<span class="Apple-converted-space">  </span>If <span class="s1">F</span>, the trait value is not used directly as a fitness effect; in script, one might compute a fitness effect from the trait value (using a “fitness function”), or the trait might have other effects that are not obviously related to fitness at all.</p>
+<p class="p5">index =&gt; (integer$)</p>
+<p class="p6">The index of the trait in the vector of traits kept by the species.<span class="Apple-converted-space">  </span>The first trait defined in a species is at index <span class="s1">0</span>, and subsequent traits count upwards from there.<span class="Apple-converted-space">  </span>The index of a trait is often used to refer to the trait, so it is important.<span class="Apple-converted-space">  </span>A global constant is defined for every trait, using each trait’s name, that provides the index of each trait, so this property will probably rarely be needed.</p>
+<p class="p5">individualOffsetMean &lt;–&gt; (float$)</p>
+<p class="p6">The mean for the normal distribution from which individual offsets are drawn.<span class="Apple-converted-space">  </span>Individual offsets are combined – multiplicatively for multiplicative traits, additively for additive traits – with all other effects that influence the trait.<span class="Apple-converted-space">  </span>This typically provides random variance in trait values among genetically identical individuals that is often termed “environmental variance” or “developmental noise”.<span class="Apple-converted-space">  </span>See also the <span class="s1">individualOffsetSD</span> property.</p>
+<p class="p5">individualOffsetSD &lt;–&gt; (float$)</p>
+<p class="p6">The standard deviation for the normal distribution from which individual offsets are drawn.<span class="Apple-converted-space">  </span>Individual offsets are combined – multiplicatively for multiplicative traits, additively for additive traits – with all other effects that influence the trait.<span class="Apple-converted-space">  </span>This typically provides random variance in trait values among genetically identical individuals that is often termed “environmental variance” or “developmental noise”.<span class="Apple-converted-space">  </span>See also the <span class="s1">individualOffsetMean</span> property.</p>
+<p class="p5">name =&gt; (string$)</p>
+<p class="p6">The name of the trait, as given to <span class="s1">initializeTrait()</span>.<span class="Apple-converted-space">  </span>The default trait that is provided if no trait is explicitly defined has a name that is the name of the species plus a <span class="s1">T</span>; so for a single-species model, the default trait will generally be named <span class="s1">simT</span>.<span class="Apple-converted-space">  </span>The name of a trait can sometimes be used to refer to the trait, and is visible in SLiMgui.</p>
+<p class="p5">species =&gt; (object&lt;Species&gt;$)</p>
+<p class="p6">The species to which the target object belongs.</p>
+<p class="p5">tag &lt;–&gt; (integer$)</p>
+<p class="p6">A user-defined <span class="s1">integer</span> value.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is initially undefined, and it is an error to try to read it; if you wish it to have a defined value, you must arrange that yourself by explicitly setting its value prior to using it elsewhere in your code.<span class="Apple-converted-space">  </span>The value of <span class="s1">tag</span> is not used by SLiM; it is free for you to use.</p>
+<p class="p5">type =&gt; (string$)</p>
+<p class="p6">The type of the trait, as a <span class="s1">string</span>.<span class="Apple-converted-space">  </span>In the present design, this will be either <span class="s1">"multiplicative"</span> or <span class="s1">"additive"</span>.</p>
+<p class="p2"><i>5.19.2<span class="Apple-converted-space">  </span></i><span class="s1"><i>Trait</i></span><i> methods</i></p>
+<p class="p15"><br></p>
 </body>
 </html>