add tagLX to sampleIndividuals() / subsetIndividuals()

QtSLiM/help/SLiMHelpClasses.html

@@ -1031,8 +1031,8 @@
 <p class="p3">– (void)removeSubpopulation(void)</p>
 <p class="p6"><span class="s3">Removes this subpopulation from the model.<span class="Apple-converted-space">  </span>The subpopulation is immediately removed from the list of active subpopulations, and the symbol representing the subpopulation is undefined.<span class="Apple-converted-space">  </span>The subpopulation object itself remains unchanged until children are next generated (at which point it is deallocated), but it is no longer part of the simulation and should not be used.</span></p>
 <p class="p6"><span class="s3">Note that this method is only for use in nonWF models, in which there is a distinction between a subpopulation being empty and a subpopulation being removed from the simulation; an empty subpopulation may be re-colonized by migrants, whereas as a removed subpopulation no longer exists at all.<span class="Apple-converted-space">  </span>WF models do not make this distinction; when a subpopulation is empty it is automatically removed.<span class="Apple-converted-space">  </span>WF models should therefore call </span><span class="s4">setSubpopulationSize(0)</span><span class="s3"> instead of this method; </span><span class="s4">setSubpopulationSize()</span><span class="s3"> is the standard way for WF models to change the subpopulation size, including to a size of </span><span class="s4">0</span><span class="s3">.</span></p>
-<p class="p5"><span class="s5">– </span><span class="s3">(object&lt;Individual&gt;)sampleIndividuals(integer$ size, [logical$ replace = F], [No&lt;Individual&gt;$ exclude = NULL], [Ns$ sex = NULL], [Ni$ tag = NULL], [Ni$ minAge = NULL], [Ni$ maxAge = NULL], [Nl$ migrant = NULL])</span></p>
-<p class="p6"><span class="s3">Returns a vector of individuals, of size less than or equal to parameter </span><span class="s4">size</span><span class="s3">, sampled from the individuals in the target subpopulation.<span class="Apple-converted-space">  </span>Sampling is done without replacement if </span><span class="s4">replace</span><span class="s3"> is </span><span class="s4">F</span><span class="s3"> (the default), or with replacement if </span><span class="s4">replace</span><span class="s3"> is </span><span class="s4">T</span><span class="s3">.<span class="Apple-converted-space">  </span>The remaining parameters specify constraints upon the pool of individuals that will be considered candidates for the sampling.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">exclude</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a specific individual that should not be considered a candidate (typically the focal individual in some operation).<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">sex</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a sex (</span><span class="s4">"M"</span><span class="s3"> or </span><span class="s4">"F"</span><span class="s3">) for the individuals to be drawn, in sexual models.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">tag</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a tag value for the individuals to be drawn.<span class="Apple-converted-space">  </span>Parameters </span><span class="s4">minAge</span><span class="s3"> and </span><span class="s4">maxAge</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a minimum or maximum age for the individuals to be drawn, in nonWF models.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">migrant</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a required value for the </span><span class="s4">migrant</span><span class="s3"> property of the individuals to be drawn (so </span><span class="s4">T</span><span class="s3"> will require that individuals be migrants, </span><span class="s4">F</span><span class="s3"> will require that they not be).<span class="Apple-converted-space">  </span>If the candidate pool is smaller than the requested sample size, all eligible candidates will be returned (in randomized order); the result will be a zero-length vector if no eligible candidates exist (unlike </span><span class="s4">sample()</span><span class="s3">).</span></p>
+<p class="p5"><span class="s5">– </span><span class="s3">(object&lt;Individual&gt;)sampleIndividuals(integer$ size, [logical$ replace = F], [No&lt;Individual&gt;$ exclude = NULL], [Ns$ sex = NULL], [Ni$ tag = NULL], [Ni$ minAge = NULL], [Ni$ maxAge = NULL], [Nl$ migrant = NULL]</span>, [Nl$ tagL0 = NULL], [Nl$ tagL1 = NULL], [Nl$ tagL2 = NULL], [Nl$ tagL3 = NULL], [Nl$ tagL4 = NULL]<span class="s3">)</span></p>
+<p class="p6">Returns a vector of individuals, of size less than or equal to parameter <span class="s1">size</span>, sampled from the individuals in the target subpopulation.<span class="Apple-converted-space">  </span>Sampling is done without replacement if <span class="s1">replace</span> is <span class="s1">F</span> (the default), or with replacement if <span class="s1">replace</span> is <span class="s1">T</span>.<span class="Apple-converted-space">  </span>The remaining parameters specify constraints upon the pool of individuals that will be considered candidates for the sampling.<span class="Apple-converted-space">  </span>Parameter <span class="s1">exclude</span>, if non-<span class="s1">NULL</span>, may specify a specific individual that should not be considered a candidate (typically the focal individual in some operation).<span class="Apple-converted-space">  </span>Parameter <span class="s1">sex</span>, if non-<span class="s1">NULL</span>, may specify a sex (<span class="s1">"M"</span> or <span class="s1">"F"</span>) for the individuals to be drawn, in sexual models.<span class="Apple-converted-space">  </span>Parameter <span class="s1">tag</span>, if non-<span class="s1">NULL</span>, may specify a <span class="s1">tag</span> property value for the individuals to be drawn.<span class="Apple-converted-space">  </span>Parameters <span class="s1">minAge</span> and <span class="s1">maxAge</span>, if non-<span class="s1">NULL</span>, may specify a minimum or maximum age for the individuals to be drawn, in nonWF models.<span class="Apple-converted-space">  </span>Parameter <span class="s1">migrant</span>, if non-<span class="s1">NULL</span>, may specify a required value for the <span class="s1">migrant</span> property of the individuals to be drawn (so <span class="s1">T</span> will require that individuals be migrants, <span class="s1">F</span> will require that they not be).<span class="Apple-converted-space">  </span>Finally, parameters <span class="s1">tagL0</span>, <span class="s1">tagL1</span>, <span class="s1">tagL2</span>, <span class="s1">tagL3</span>, and <span class="s1">tagL4</span>, if non-<span class="s1">NULL</span>, may specify a required value (<span class="s1">T</span> or <span class="s1">F</span>) for the corresponding properties (<span class="s1">tagL0</span>, <span class="s1">tagL1</span>, <span class="s1">tagL2</span>, <span class="s1">tagL3</span>, and <span class="s1">tagL4</span>) of the individuals to be drawn.<span class="Apple-converted-space">  </span>Note that if any <span class="s1">tag</span>/<span class="s1">tagL</span> parameter is specified as non-<span class="s1">NULL</span>, that <span class="s1">tag</span>/<span class="s1">tagL</span> property must have a defined value for every individual in the subpopulation, otherwise an error may result (although this requirement will not necessarily be checked comprehensively by this method in every invocation).<span class="Apple-converted-space">  </span>If the candidate pool is smaller than the requested sample size, all eligible candidates will be returned (in randomized order); the result will be a zero-length vector if no eligible candidates exist (unlike <span class="s1">sample()</span>).</p>
 <p class="p6"><span class="s3">This method is similar to getting the </span><span class="s4">individuals</span><span class="s3"> property of the subpopulation, using operator </span><span class="s4">[]</span><span class="s3"> to select only individuals with the desired properties, and then using </span><span class="s4">sample()</span><span class="s3"> to sample from that candidate pool.<span class="Apple-converted-space">  </span>However, besides being much simpler than the equivalent Eidos code, it is also much faster, and it does not fail if less than the full sample size is available.<span class="Apple-converted-space">  </span>See </span><span class="s4">subsetIndividuals()</span><span class="s3"> for a similar method that returns a full subset, rather than a sample.</span></p>
 <p class="p3">– (void)setCloningRate(numeric rate)</p>
 <p class="p4">Set the cloning rate of this subpopulation.<span class="Apple-converted-space">  </span>The rate is changed to <span class="s1">rate</span>, which should be between 0.0 and 1.0, inclusive (see the SLiM manual for further details).<span class="Apple-converted-space">  </span>Clonal reproduction can be enabled in both non-sexual (i.e. hermaphroditic) and sexual simulations.<span class="Apple-converted-space">  </span>In non-sexual simulations, <span class="s1">rate</span> must be a singleton value representing the overall clonal reproduction rate for the subpopulation.<span class="Apple-converted-space">  </span>In sexual simulations, <span class="s1">rate</span> may be either a singleton (specifying the clonal reproduction rate for both sexes) or a vector containing two numeric values (the female and male cloning rates specified separately, at indices <span class="s1">0</span> and <span class="s1">1</span> respectively).<span class="Apple-converted-space">  </span>During mating and offspring generation, the probability that any given offspring individual will be generated by cloning – by asexual reproduction without gametes or meiosis – will be equal to the cloning rate (for its sex, in sexual simulations) set in the parental (not the offspring!) subpopulation.</p>
@@ -1055,8 +1055,8 @@
 <p class="p6">Looks up the spatial map specified by <span class="s1">map</span>, and uses its mapping machinery (as defined by the <span class="s1">gridSize</span>, <span class="s1">values</span>, and <span class="s1">interpolate</span> parameters to <span class="s1">defineSpatialMap()</span>) to translate the coordinates of <span class="s1">point</span> into a corresponding map value.<span class="Apple-converted-space">  </span>The parameter <span class="s1">map</span> may specify the map either as a <span class="s1">SpatialMap</span> object, or by its <span class="s1">string</span> name; in either case, the map must have been added to the subpopulation.<span class="Apple-converted-space">  </span>The length of <span class="s1">point</span> must be equal to the spatiality of the spatial map; in other words, for a spatial map with spatiality <span class="s1">"xz"</span>, <span class="s1">point</span> must be of length <span class="s1">2</span>, specifying the <i>x</i> and <i>z</i> coordinates of the point to be evaluated.<span class="Apple-converted-space">  </span>Interpolation will automatically be used if it was enabled for the spatial map.<span class="Apple-converted-space">  </span>Point coordinates are clamped into the range defined by the spatial boundaries, even if the spatial boundaries are periodic; use <span class="s1">pointPeriodic()</span> to wrap the point coordinates first if desired.<span class="Apple-converted-space">  </span>See the documentation for <span class="s1">defineSpatialMap()</span> for information regarding the details of value mapping.</p>
 <p class="p6">Beginning in SLiM 3.3, <span class="s1">point</span> may contain more than one point to be looked up.<span class="Apple-converted-space">  </span>In this case, the length of <span class="s1">point</span> must be an exact multiple of the spatiality of the spatial map; for a spatial map with spatiality <span class="s1">"xz"</span>, for example, the length of <span class="s1">point</span> must be an exact multiple of <span class="s1">2</span>, and successive pairs of elements from point (elements <span class="s1">0</span> and <span class="s1">1</span>, then elements <span class="s1">2</span> and <span class="s1">3</span>, etc.) will be taken as the <i>x</i> and <i>z</i> coordinates of the points to be evaluated.<span class="Apple-converted-space">  </span>This allows <span class="s1">spatialMapValue()</span> to be used in a vectorized fashion.</p>
 <p class="p6">The <span class="s1">mapValue()</span> method of <span class="s1">SpatialMap</span> provides the same functionality directly on the <span class="s1">SpatialMap</span> class; <span class="s1">spatialMapValue()</span> is provided on <span class="s1">Subpopulation</span> partly for backward compatibility, but also for convenience for the most common usage case of spatial maps.</p>
-<p class="p5"><span class="s5">– </span><span class="s3">(object&lt;Individual&gt;)subsetIndividuals([No&lt;Individual&gt;$ exclude = NULL], [Ns$ sex = NULL], [Ni$ tag = NULL], [Ni$ minAge = NULL], [Ni$ maxAge = NULL], [Nl$ migrant = NULL])</span></p>
-<p class="p6"><span class="s3">Returns a vector of individuals subset from the individuals in the target subpopulation.<span class="Apple-converted-space">  </span>The parameters specify constraints upon the subset of individuals that will be returned.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">exclude</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a specific individual that should not be included (typically the focal individual in some operation).<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">sex</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a sex (</span><span class="s4">"M"</span><span class="s3"> or </span><span class="s4">"F"</span><span class="s3">) for the individuals to be returned, in sexual models.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">tag</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a tag value for the individuals to be returned.<span class="Apple-converted-space">  </span>Parameters </span><span class="s4">minAge</span><span class="s3"> and </span><span class="s4">maxAge</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a minimum or maximum age for the individuals to be returned, in nonWF models.<span class="Apple-converted-space">  </span>Parameter </span><span class="s4">migrant</span><span class="s3">, if non-</span><span class="s4">NULL</span><span class="s3">, may specify a required value for the </span><span class="s4">migrant</span><span class="s3"> property of the individuals to be returned (so </span><span class="s4">T</span><span class="s3"> will require that individuals be migrants, </span><span class="s4">F</span><span class="s3"> will require that they not be).</span></p>
+<p class="p5"><span class="s5">– </span><span class="s3">(object&lt;Individual&gt;)subsetIndividuals([No&lt;Individual&gt;$ exclude = NULL], [Ns$ sex = NULL], [Ni$ tag = NULL], [Ni$ minAge = NULL], [Ni$ maxAge = NULL], [Nl$ migrant = NULL]</span>, [Nl$ tagL0 = NULL], [Nl$ tagL1 = NULL], [Nl$ tagL2 = NULL], [Nl$ tagL3 = NULL], [Nl$ tagL4 = NULL]<span class="s3">)</span></p>
+<p class="p6">Returns a vector of individuals subset from the individuals in the target subpopulation.<span class="Apple-converted-space">  </span>The parameters specify constraints upon the subset of individuals that will be returned.<span class="Apple-converted-space">  </span>Parameter <span class="s1">exclude</span>, if non-<span class="s1">NULL</span>, may specify a specific individual that should not be included (typically the focal individual in some operation).<span class="Apple-converted-space">  </span>Parameter <span class="s1">sex</span>, if non-<span class="s1">NULL</span>, may specify a sex (<span class="s1">"M"</span> or <span class="s1">"F"</span>) for the individuals to be returned, in sexual models.<span class="Apple-converted-space">  </span>Parameter <span class="s1">tag</span>, if non-<span class="s1">NULL</span>, may specify a <span class="s1">tag</span> property value for the individuals to be returned.<span class="Apple-converted-space">  </span>Parameters <span class="s1">minAge</span> and <span class="s1">maxAge</span>, if non-<span class="s1">NULL</span>, may specify a minimum or maximum age for the individuals to be returned, in nonWF models.<span class="Apple-converted-space">  </span>Parameter <span class="s1">migrant</span>, if non-<span class="s1">NULL</span>, may specify a required value for the <span class="s1">migrant</span> property of the individuals to be returned (so <span class="s1">T</span> will require that individuals be migrants, <span class="s1">F</span> will require that they not be).<span class="Apple-converted-space">  </span>Finally, parameters <span class="s1">tagL0</span>, <span class="s1">tagL1</span>, <span class="s1">tagL2</span>, <span class="s1">tagL3</span>, and <span class="s1">tagL4</span>, if non-<span class="s1">NULL</span>, may specify a required value (<span class="s1">T</span> or <span class="s1">F</span>) for the corresponding properties (<span class="s1">tagL0</span>, <span class="s1">tagL1</span>, <span class="s1">tagL2</span>, <span class="s1">tagL3</span>, and <span class="s1">tagL4</span>) of the individuals to be returned.<span class="Apple-converted-space">  </span>Note that if any <span class="s1">tag</span>/<span class="s1">tagL</span> parameter is specified as non-<span class="s1">NULL</span>, that <span class="s1">tag</span>/<span class="s1">tagL</span> property must have a defined value for every individual in the subpopulation, otherwise an error may result (although this requirement will not necessarily be checked comprehensively by this method in every invocation).</p>
 <p class="p6"><span class="s3">This method is shorthand for getting the </span><span class="s4">individuals</span><span class="s3"> property of the subpopulation, and then using operator </span><span class="s4">[]</span><span class="s3"> to select only individuals with the desired properties; besides being much simpler than the equivalent Eidos code, it is also much faster.<span class="Apple-converted-space">  </span>See </span><span class="s4">sampleIndividuals()</span><span class="s3"> for a similar method that returns a sample taken from a chosen subset of individuals.</span></p>
 <p class="p5"><span class="s3">– (void)takeMigrants(object&lt;Individual&gt; migrants)</span></p>
 <p class="p6"><span class="s3">Immediately moves the individuals in </span><span class="s4">migrants</span><span class="s3"> to the target subpopulation (removing them from their previous subpopulation).<span class="Apple-converted-space">  </span>Individuals in </span><span class="s4">migrants</span><span class="s3"> that are already in the target subpopulation are unaffected.<span class="Apple-converted-space">  </span>Note that the indices and order of individuals and genomes in both the target and source subpopulations will change unpredictably as a side effect of this method.</span></p>