add zygosityOfMutations() method to Individual

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -474,7 +474,7 @@
 <p class="p6">The <span class="s1">mutType</span> parameter may be <span class="s1">NULL</span>, or may specify a mutation type by its <span class="s1">integer</span> id or with the <span class="s1">MutationType</span> object itself.<span class="Apple-converted-space">  </span>If <span class="s1">mutType</span> is <span class="s1">NULL</span> (the default), mutations of every mutation type are returned; no filtering by mutation type is done.<span class="Apple-converted-space">  </span>Otherwise, only mutations of the specified mutation type will be returned.</p>
 <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="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.<span class="Apple-converted-space">  </span>See also the method <span class="s1">zygosityOfMutations()</span>, which provides an alternative approach for assessing the zygosity of mutations in an individual.</p>
 <p class="p5">– (float)offsetForTrait([Niso&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 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> 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">– (float)phenotypeForTrait([Niso&lt;Trait&gt; trait = NULL])</p>
@@ -534,6 +534,13 @@
 <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>
+<p class="p5">+ (integer)zygosityOfMutations([No&lt;Mutation&gt; mutations = NULL], [integer$ hemizygousValue = 1], [integer$ haploidValue = 1])</p>
+<p class="p6">Returns an <span class="s1">integer</span> matrix with the target individuals’ zygosity for all of the <span class="s1">Mutation</span> objects passed in <span class="s1">mutations</span>.<span class="Apple-converted-space">  </span>If the optional <span class="s1">mutations</span> argument is <span class="s1">NULL</span> (the default), zygosity values will be returned for all of the active <span class="s1">Mutation</span> objects in the species – the same <span class="s1">Mutation</span> objects, and in the same order, as would be returned by the <span class="s1">mutations</span> property of <span class="s1">sim</span>, in other words.<span class="Apple-converted-space">  </span>The returned matrix has one column for each individual and one row for each mutation.</p>
+<p class="p6">For a mutation on a diploid chromosome, the zygosity will be either <span class="s1">0</span> (absent), <span class="s1">1</span> (heterozygous), or <span class="s1">2</span> (homozygous).<span class="Apple-converted-space">  </span>This is the straightforward “base case” that is usually meant by the term “zygosity”.</p>
+<p class="p6">If one of the two haplosomes of an intrinsically diploid chromosome is a null haplosome (as would be the case for an X chromosome in a male individual, for example), mutations present in the non-null haplosome are called “hemizygous”, and the zygosity returned for them is configurable using the <span class="s1">hemizygousValue</span> parameter.<span class="Apple-converted-space">  </span>By default, the zygosity returned for hemizygous mutations is <span class="s1">1</span>.</p>
+<p class="p6">Finally, although the term “zygosity” is not usually used in the context of haploidy, this method nevertheless supports intrinsically haploid chromosomes; the zygosity returned for mutations present on an intrinsically haploid chromosome is configurable using the <span class="s1">haploidValue</span> parameter.<span class="Apple-converted-space">  </span>By default, the zygosity returned for haploid mutations is <span class="s1">1</span>.</p>
+<p class="p6">For a large number of mutations – and especially for a <span class="s1">mutations</span> value of <span class="s1">NULL</span>, representing all mutations in the species – this method should be much more efficient than using methods such as <span class="s1">containsMutations()</span> to assess zygosity.<span class="Apple-converted-space">  </span>Nevertheless, calculating fitness effects in script based upon zygosity will generally be slower than SLiM’s internal fitness calculations.<span class="Apple-converted-space">  </span>Note that for just one or a few mutations – especially if <span class="s1">mutations</span> contains just a small fraction of all of the mutations in the species – this method will probably be much slower than alternative approaches; this method is optimized for the bulk case.</p>
+<p class="p6">See also the method <span class="s1">mutationsFromHaplosomes()</span>, which provides an alternative approach for assessing the zygosity of mutations in an individual.</p>
 <p class="p1"><b>5.8<span class="Apple-converted-space">  </span>Class InteractionType</b></p>
 <p class="p2"><i>5.8.1<span class="Apple-converted-space">  </span></i><span class="s1"><i>InteractionType</i></span><i> properties</i></p>
 <p class="p3">id =&gt; (integer$)</p>

SLiMgui/SLiMHelpClasses.rtf

@@ -3873,7 +3873,9 @@ The returned vector will contain tranches of mutations, one tranche per chromoso
 \f4\fs20 .  (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.)\
 This method replaces the deprecated method 
 \f3\fs18 uniqueMutationsOfType()
-\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.\
+\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.  See also the method 
+\f3\fs18 zygosityOfMutations()
+\f4\fs20 , which provides an alternative approach for assessing the zygosity of mutations in an individual.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
 \f3\fs18 \cf2 \'96\'a0(float)offsetForTrait([Niso<Trait>\'a0trait\'a0=\'a0NULL])\
@@ -4555,6 +4557,59 @@ Historically, this method was often useful in models that used a particular muta
 \f4\fs20 .  This method is provided for speed; it is much faster than the corresponding Eidos code.  Indeed, it is faster than just 
 \f3\fs18 individual.haplosomes.mutationsOfType(mutType)
 \f4\fs20 , and gives uniquing and sorting on top of that, so it is advantageous unless duplicate entries for homozygous mutations are actually needed.\
+\pard\pardeftab397\li720\fi-446\ri720\sb180\sa60\partightenfactor0
+
+\f3\fs18 \cf2 +\'a0(integer)zygosityOfMutations([No<Mutation>\'a0mutations\'a0=\'a0NULL], [integer$\'a0hemizygousValue\'a0=\'a01], [integer$\'a0haploidValue\'a0=\'a01])\
+\pard\pardeftab397\li547\ri720\sb60\sa60\partightenfactor0
+
+\f4\fs20 \cf2 Returns an 
+\f3\fs18 integer
+\f4\fs20  matrix with the target individuals\'92 zygosity for all of the 
+\f3\fs18 Mutation
+\f4\fs20  objects passed in 
+\f3\fs18 mutations
+\f4\fs20 .  If the optional 
+\f3\fs18 mutations
+\f4\fs20  argument is 
+\f3\fs18 NULL
+\f4\fs20  (the default), zygosity values will be returned for all of the active 
+\f3\fs18 Mutation
+\f4\fs20  objects in the species \'96 the same 
+\f3\fs18 Mutation
+\f4\fs20  objects, and in the same order, as would be returned by the 
+\f3\fs18 mutations
+\f4\fs20  property of 
+\f3\fs18 sim
+\f4\fs20 , in other words.  The returned matrix has one column for each individual and one row for each mutation.\
+For a mutation on a diploid chromosome, the zygosity will be either 
+\f3\fs18 0
+\f4\fs20  (absent), 
+\f3\fs18 1
+\f4\fs20  (heterozygous), or 
+\f3\fs18 2
+\f4\fs20  (homozygous).  This is the straightforward \'93base case\'94 that is usually meant by the term \'93zygosity\'94.\
+If one of the two haplosomes of an intrinsically diploid chromosome is a null haplosome (as would be the case for an X chromosome in a male individual, for example), mutations present in the non-null haplosome are called \'93hemizygous\'94, and the zygosity returned for them is configurable using the 
+\f3\fs18 hemizygousValue
+\f4\fs20  parameter.  By default, the zygosity returned for hemizygous mutations is 
+\f3\fs18 1
+\f4\fs20 .\
+Finally, although the term \'93zygosity\'94 is not usually used in the context of haploidy, this method nevertheless supports intrinsically haploid chromosomes; the zygosity returned for mutations present on an intrinsically haploid chromosome is configurable using the 
+\f3\fs18 haploidValue
+\f4\fs20  parameter.  By default, the zygosity returned for haploid mutations is 
+\f3\fs18 1
+\f4\fs20 .\
+For a large number of mutations \'96 and especially for a 
+\f3\fs18 mutations
+\f4\fs20  value of 
+\f3\fs18 NULL
+\f4\fs20 , representing all mutations in the species \'96 this method should be much more efficient than using methods such as 
+\f3\fs18 containsMutations()
+\f4\fs20  to assess zygosity.  Nevertheless, calculating fitness effects in script based upon zygosity will generally be slower than SLiM\'92s internal fitness calculations.  Note that for just one or a few mutations \'96 especially if 
+\f3\fs18 mutations
+\f4\fs20  contains just a small fraction of all of the mutations in the species \'96 this method will probably be much slower than alternative approaches; this method is optimized for the bulk case.\
+See also the method 
+\f3\fs18 mutationsFromHaplosomes()
+\f4\fs20 , which provides an alternative approach for assessing the zygosity of mutations in an individual.\
 \pard\pardeftab720\ri720\sb360\sa60\partightenfactor0
 
 \f0\b\fs22 \cf0 5.8  Class InteractionType\

VERSIONS

@@ -132,6 +132,7 @@ multitrait branch:
 	add a cachedFitness property to class Individual to provide another way of accessing fitness values for individuals, besides the cachedFitness() method of Subpopulation
 	extend the Eidos deleteFile() and fileExists() functions to support passing in a vector of file paths
 	extend the Eidos + operator to support adding logical+logical, integer+logical, and logical+integer (all for NxN, 1xN, Nx1), as in R
+	add zygosityOfMutations([No<Mutation> mutations = NULL], [integer$ hemizygousValue = 1], [integer$ haploidValue = 1]) for assessing zygosity (see also mutationsFromHaplosomes())
 
 
 version 5.1 (Eidos version 4.1):

core/chromosome.h

@@ -276,6 +276,8 @@ class Chromosome : public EidosDictionaryRetained
 	// private scratch space for the use of Population::RemoveAllFixedMutations()
 	std::vector<MutationIndex> fixed_mutation_accumulator_;
 
+	int8_t scratch_;									// temporary scratch space for use by algorithms; regard as volatile outside your own code block
+	
 	// a user-defined tag value
 	slim_usertag_t tag_value_ = SLIM_TAG_UNSET_VALUE;
 

core/haplosome.h

@@ -429,9 +429,9 @@ class Haplosome : public EidosObject
 	virtual void SetProperty(EidosGlobalStringID p_property_id, const EidosValue &p_value) override;
 
 	virtual EidosValue_SP ExecuteInstanceMethod(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter) override;
-	static EidosValue_SP ExecuteMethod_Accelerated_containsMarkerMutation(EidosObject **p_values, size_t p_values_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
-	static EidosValue_SP ExecuteMethod_Accelerated_containsMutations(EidosObject **p_values, size_t p_values_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
-	static EidosValue_SP ExecuteMethod_Accelerated_countOfMutationsOfType(EidosObject **p_values, size_t p_values_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
+	static EidosValue_SP ExecuteMethod_Accelerated_containsMarkerMutation(EidosObject **p_elements, size_t p_elements_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
+	static EidosValue_SP ExecuteMethod_Accelerated_containsMutations(EidosObject **p_elements, size_t p_elements_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
+	static EidosValue_SP ExecuteMethod_Accelerated_countOfMutationsOfType(EidosObject **p_elements, size_t p_elements_size, EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_mutationsOfType(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_nucleotides(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);
 	EidosValue_SP ExecuteMethod_positionsOfMutationsOfType(EidosGlobalStringID p_method_id, const std::vector<EidosValue_SP> &p_arguments, EidosInterpreter &p_interpreter);