extend sumOfMutationsOfType() for multitrait

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -300,7 +300,7 @@
 <p class="p6">In multi-chromosome models, the frequency of each mutation is assessed within the subset of target haplosomes that are associated with the same chromosome.<span class="Apple-converted-space">  </span>In other words, if a mutation is associated with chromosome 1, and the target haplosomes are associated with both chromosomes 1 and 2, the frequency of the mutation will be calculated only within the haplosomes for chromosome 1 (as you would expect).<span class="Apple-converted-space">  </span>However, you might often wish to obtain frequencies only for mutations associated with one particular chromosome.<span class="Apple-converted-space">  </span>In that case, you would probably want to pass a vector of the mutations associated with that specific chromosome, as obtained from the <span class="s1">subsetMutations()</span> method of <span class="s1">Species</span>, rather than passing <span class="s1">NULL</span>.<span class="Apple-converted-space">  </span>(Passing <span class="s1">NULL</span> in that scenario would give you frequencies of <span class="s1">0</span> for all of the mutations associated with other chromosomes in the model.)</p>
 <p class="p6">See the <span class="s1">+mutationCountsInHaplosomes()</span> method to obtain <span class="s1">integer</span> counts instead of <span class="s1">float</span> frequencies.<span class="Apple-converted-space">  </span>See also the <span class="s1">Species</span> methods <span class="s1">mutationCounts()</span> and <span class="s1">mutationFrequencies()</span>, which might be more efficient for getting counts/frequencies for whole subpopulations or for the whole species.</p>
 <p class="p3">–<span class="s9"> </span>(object&lt;Mutation&gt;)mutationsOfType(io&lt;MutationType&gt;$ mutType)</p>
-<p class="p4">Returns an <span class="s1">object</span> vector of all the mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome.<span class="Apple-converted-space">  </span>If you just need a count of the matching <span class="s1">Mutation</span> objects, rather than a vector of the matches, use <span class="s1">-countOfMutationsOfType()</span>; if you need just the positions of matching <span class="s1">Mutation</span> objects, use <span class="s1">-positionsOfMutationsOfType()</span>; and if you are aiming for a sum of the selection coefficients of matching <span class="s1">Mutation</span> objects, use <span class="s1">-sumOfMutationsOfType()</span><span class="s2">.</span><span class="Apple-converted-space">  </span>This method is provided for speed; it is much faster than the corresponding Eidos code.<span class="s5"><span class="Apple-converted-space">  </span>See also </span><span class="s6">substitutionsOfType()</span><span class="s5">.</span></p>
+<p class="p4">Returns an <span class="s1">object</span> vector of all the mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome.<span class="Apple-converted-space">  </span>If you just need a count of the matching <span class="s1">Mutation</span> objects, rather than a vector of the matches, use <span class="s1">-countOfMutationsOfType()</span>; if you need just the positions of matching <span class="s1">Mutation</span> objects, use <span class="s1">-positionsOfMutationsOfType()</span>; and if you are aiming for a sum of the effects of matching <span class="s1">Mutation</span> objects, use <span class="s1">-sumOfMutationsOfType()</span><span class="s2">.</span><span class="Apple-converted-space">  </span>This method is provided for speed; it is much faster than the corresponding Eidos code.<span class="s5"><span class="Apple-converted-space">  </span>See also </span><span class="s6">substitutionsOfType()</span><span class="s5">.</span></p>
 <p class="p5"><span class="s3">– (is)nucleotides([Ni$ start = NULL], [Ni$ end = NULL], [string$ format = "string"])</span></p>
 <p class="p6"><span class="s3">Returns the nucleotide sequence for the haplosome.<span class="Apple-converted-space">  </span>This is the current ancestral sequence, as would be returned by the </span><span class="s4">Chromosome</span><span class="s3"> method </span><span class="s4">ancestralNucleotides()</span><span class="s3">, with the nucleotides for any nucleotide-based mutations in the haplosome overlaid.<span class="Apple-converted-space">  </span>The range of the returned sequence may be constrained by a start position given in </span><span class="s4">start</span><span class="s3"> and/or an end position given in </span><span class="s4">end</span><span class="s3">; nucleotides will be returned from </span><span class="s4">start</span><span class="s3"> to </span><span class="s4">end</span><span class="s3">, inclusive.<span class="Apple-converted-space">  </span>The default value of </span><span class="s4">NULL</span><span class="s3"> for </span><span class="s4">start</span><span class="s3"> and </span><span class="s4">end</span><span class="s3"> represent the first and last base positions of the chromosome, respectively.</span></p>
 <p class="p6"><span class="s3">The format of the returned sequence is controlled by the </span><span class="s4">format</span><span class="s3"> parameter.<span class="Apple-converted-space">  </span>A format of </span><span class="s4">"string"</span><span class="s3"> will return the sequence as a singleton </span><span class="s4">string</span><span class="s3"> (e.g., </span><span class="s4">"TATA"</span><span class="s3">).<span class="Apple-converted-space">  </span>A format of </span><span class="s4">"char"</span><span class="s3"> will return a </span><span class="s4">string</span><span class="s3"> vector with one element per nucleotide (e.g., </span><span class="s4">"T"</span><span class="s3">, </span><span class="s4">"A"</span><span class="s3">, </span><span class="s4">"T"</span><span class="s3">, </span><span class="s4">"A"</span><span class="s3">).<span class="Apple-converted-space">  </span>A format of </span><span class="s4">"integer"</span><span class="s3"> will return an </span><span class="s4">integer</span><span class="s3"> vector with values A=</span><span class="s4">0</span><span class="s3">, C=</span><span class="s4">1</span><span class="s3">, G=</span><span class="s4">2</span><span class="s3">, T=</span><span class="s4">3</span><span class="s3"> (e.g., </span><span class="s4">3</span><span class="s3">, </span><span class="s4">0</span><span class="s3">, </span><span class="s4">3</span><span class="s3">, </span><span class="s4">0</span><span class="s3">).<span class="Apple-converted-space">  </span>A format of </span><span class="s4">"codon"</span><span class="s3"> will return an </span><span class="s4">integer</span><span class="s3"> vector with values from </span><span class="s4">0</span><span class="s3"> to </span><span class="s4">63</span><span class="s3">, based upon successive nucleotide triplets in the sequence (which, for this format, must have a length that is a multiple of three); see the </span><span class="s4">ancestralNucleotides()</span><span class="s3"> documentation for details.<span class="Apple-converted-space">  </span>If the sequence returned is likely to be long, the </span><span class="s4">"string"</span><span class="s3"> format will be the most memory-efficient, and may also be the fastest (but may be harder to work with).</span></p>
@@ -339,8 +339,9 @@
 <p class="p6">Remove the mutations in <span class="s1">mutations</span> from the target haplosomes, if they are present (if they are not present, they will be ignored).<span class="Apple-converted-space">  </span>If <span class="s1">NULL</span> is passed for <span class="s1">mutations</span> (which is the default), then all mutations will be removed from the target haplosomes; in this case, <span class="s1">substitute</span> must be <span class="s1">F</span> (a specific vector of mutations to be substituted is required).<span class="Apple-converted-space">  </span>Note that the <span class="s1">Mutation</span> objects removed remain valid, and will still be in the simulation’s mutation registry (i.e., will be returned by the <span class="s1">Species</span> property <span class="s1">mutations</span>), until the next tick.<span class="Apple-converted-space">  </span>All target haplosomes and all mutations in <span class="s1">mutations</span> must be associated with the same <span class="s1">Chromosome</span> object; attempting to remove a mutation from a haplosome associated with a different chromosome will raise an error.</p>
 <p class="p6"><span class="s3">Removing mutations will normally affect the fitness values calculated at the end of the current tick; if you want current fitness values to be affected, you can call the </span><span class="s4">Species</span><span class="s3"> method </span><span class="s4">recalculateFitness()</span><span class="s3"> – but see the documentation of that method for caveats.</span></p>
 <p class="p6"><span class="s3">The optional parameter </span><span class="s4">substitute</span><span class="s3"> was added in SLiM 2.2, with a default of </span><span class="s4">F</span><span class="s3"> for backward compatibility.<span class="Apple-converted-space">  </span>If </span><span class="s4">substitute</span><span class="s3"> is </span><span class="s4">T</span><span class="s3">, </span><span class="s4">Substitution</span><span class="s3"> objects will be created for all of the removed mutations so that they are recorded in the simulation as having fixed, just as if they had reached fixation and been removed by SLiM’s own internal machinery.<span class="Apple-converted-space">  </span>This will occur regardless of whether the mutations have in fact fixed, regardless of the </span><span class="s4">convertToSubstitution</span><span class="s3"> property of the relevant mutation types, and regardless of whether all copies of the mutations have even been removed from the simulation (making it possible to create </span><span class="s4">Substitution</span><span class="s3"> objects for mutations that are still segregating).<span class="Apple-converted-space">  </span>It is up to the caller to perform whatever checks are necessary to preserve the integrity of the simulation’s records.<span class="Apple-converted-space">  </span>Typically </span><span class="s4">substitute</span><span class="s3"> will only be set to </span><span class="s4">T</span><span class="s3"> in the context of calls like </span><span class="s4">sim.subpopulations.haplosomes.removeMutations(muts, T)</span><span class="s3">, such that the substituted mutations are guaranteed to be entirely removed from circulation.<span class="Apple-converted-space">  </span>As mentioned above, </span><span class="s4">substitute</span><span class="s3"> may not be </span><span class="s4">T</span><span class="s3"> if </span><span class="s4">mutations</span><span class="s3"> is </span><span class="s4">NULL</span><span class="s3">.</span></p>
-<p class="p3">–<span class="s9"> </span>(float$)sumOfMutationsOfType(io&lt;MutationType&gt;$ mutType)</p>
-<p class="p4">Returns the sum of the selection coefficients of all mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome.<span class="Apple-converted-space">  </span>This is often useful in models that use a particular mutation type to represent QTLs with additive effects; in that context, <span class="s1">sumOfMutationsOfType()</span> will provide the sum of the additive effects of the QTLs for the given mutation type.<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>Note that this method also exists on <span class="s1">Individual</span>, for cases in which the sum across both haplosomes of an individual is desired.</p>
+<p class="p3">–<span class="s9"> </span>(float$)sumOfMutationsOfType(io&lt;MutationType&gt;$ mutType<span class="s5">, [Niso&lt;Trait&gt;$ trait = NULL]</span>)</p>
+<p class="p6">Returns the sum of the effects of all mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosome, 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 or <span class="s1">string</span> names of traits in the species, or directly as <span class="s1">Trait</span> objects; <span class="s1">NULL</span> can be used to represent the one defined trait in a single-trait species.</p>
+<p class="p6">Historically, this method was often useful in models that used a particular mutation type to represent QTLs with additive effects; in that context, <span class="s1">sumOfMutationsOfType()</span> provides the sum of the additive effects of the QTLs for the given mutation type.<span class="Apple-converted-space">  </span>With the support for quantitative traits that is now built into SLiM this method has largely been superseded, and is now provided mostly for backward compatibility.<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>Note that this method also exists on <span class="s1">Individual</span>, for cases in which the sum across both haplosomes of an individual is desired.</p>
 <p class="p1"><b>5.5<span class="Apple-converted-space">  </span>Class GenomicElement</b></p>
 <p class="p2"><i>5.5.1<span class="Apple-converted-space">  </span></i><span class="s1"><i>GenomicElement</i></span><i> properties</i></p>
 <p class="p3">endPosition =&gt; (integer$)</p>
@@ -523,8 +524,9 @@
 <p class="p7"><span class="Apple-tab-span">	</span><span class="s1">AB</span> <span class="s1">BA</span> <span class="s14">→</span> <span class="s1">2</span> (full siblings)</p>
 <p class="p7"><span class="Apple-tab-span">	</span><span class="s1">AA</span> <span class="s1">AA</span> <span class="s14">→</span> <span class="s1">2</span> (full siblings)</p>
 <p class="p6">This method does not estimate consanguinity.<span class="Apple-converted-space">  </span>For example, if one individual is itself a parent of the other individual, that is irrelevant for this method.<span class="Apple-converted-space">  </span>Similarly, in simulations of sex chromosomes, the sexes of the parents are irrelevant, even if no genetic material would have been inherited from a given parent.<span class="Apple-converted-space">  </span>See <span class="s1">relatedness()</span> for an assessment of pedigree-based relatedness that does estimate the consanguinity of individuals.<span class="Apple-converted-space">  </span>The <span class="s1">sharedParentCount()</span> method is preferable if your exact question is simply whether individuals are full siblings, half siblings, or non-siblings; in other cases, <span class="s1">relatedness()</span> is probably more useful.</p>
-<p class="p3">–<span class="s9"> </span>(float$)sumOfMutationsOfType(io&lt;MutationType&gt;$ mutType)</p>
-<p class="p4">Returns the sum of the selection coefficients of all mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosomes of the individual.<span class="Apple-converted-space">  </span>This is often useful in models that use a particular mutation type to represent QTLs with additive effects; in that context, <span class="s1">sumOfMutationsOfType()</span> will provide the sum of the additive effects of the QTLs for the given mutation type.<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>Note that this method also exists on <span class="s1">Haplosome</span>, for cases in which the sum for just one haplosome is desired.</p>
+<p class="p3">–<span class="s9"> </span>(float$)sumOfMutationsOfType(io&lt;MutationType&gt;$ mutType<span class="s5">, [Niso&lt;Trait&gt;$ trait = NULL]</span>)</p>
+<p class="p6">Returns the sum of the effects of all mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the haplosomes of the individual, 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 or <span class="s1">string</span> names of traits in the species, or directly as <span class="s1">Trait</span> objects; <span class="s1">NULL</span> can be used to represent the one defined trait in a single-trait species.</p>
+<p class="p6">Historically, this method was often useful in models that used a particular mutation type to represent QTLs with additive effects; in that context, <span class="s1">sumOfMutationsOfType()</span> provides the sum of the additive effects of the QTLs for the given mutation type.<span class="Apple-converted-space">  </span>With the support for quantitative traits that is now built into SLiM this method has largely been superseded, and is now provided mostly for backward compatibility.<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>Note that this method also exists on <span class="s1">Haplosome</span>, for cases in which the sum for just one haplosome is desired.</p>
 <p class="p3">–<span class="s9"> </span>(object&lt;Mutation&gt;)uniqueMutationsOfType(io&lt;MutationType&gt;$ mutType)</p>
 <p class="p6"><b>This method has been deprecated, and may be removed in a future release of SLiM.</b><span class="Apple-converted-space">  </span>Its functionality was replaced by <span class="s1">mutationsFromHaplosomes()</span> in SLiM 5.0.</p>
 <p class="p6">Returns an <span class="s1">object</span> vector of all the mutations that are of the type specified by <span class="s1">mutType</span>, out of all of the mutations in the individual.<span class="Apple-converted-space">  </span>Mutations present in both homologous haplosomes will occur only once in the result of this method, and the mutations for a given chromosomes will be given in sorted order by <span class="s1">position</span>, so in single-chromosome simulations this method is similar to <span class="s1">sortBy(unique(individual.haplosomes.mutationsOfType(mutType)), "position")</span>.<span class="Apple-converted-space">  </span>(Even with a single chromosome it is not identical to that call, since if multiple mutations exist at the exact same position, they may be sorted differently by this method than they would be by <span class="s1">sortBy()</span>.)<span class="Apple-converted-space">  </span>If you just need a count of the matching <span class="s1">Mutation</span> objects, rather than a vector of the matches, use <span class="s1">-countOfMutationsOfType()</span>.<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>Indeed, it is faster than just <span class="s1">individual.haplosomes.mutationsOfType(mutType)</span>, and gives uniquing and sorting on top of that, so it is advantageous unless duplicate entries for homozygous mutations are actually needed.</p>