Merge pull request #397 from MesserLab/samplePt_fix

fix sampleNearbyPoint() and sampleImprovedNearbyPoint()

QtSLiM/help/SLiMHelpClasses.html

@@ -745,7 +745,7 @@
 <p class="p5">– (float)sampleNearbyPoint(float point, float$ maxDistance, string$ functionType, ...)</p>
 <p class="p6">For a spatial point supplied in <span class="s1">point</span>, returns a nearby point sampled from a kernel weighted by the spatial map’s values.<span class="Apple-converted-space">  </span>Only points within the maximum distance of the kernel, <span class="s1">maxDistance</span>, will be chosen, and the probability that a given point is chosen will be proportional to the density of the kernel at that point multiplied by the value of the map at that point (interpolated, if interpolation is enabled for the map).<span class="Apple-converted-space">  </span>Negative values of the map will be treated as zero.<span class="Apple-converted-space">  </span>The point returned will be within spatial bounds, respecting periodic boundaries if in effect (so there is no need to call <span class="s1">pointPeriodic()</span> on the result).</p>
 <p class="p6">The kernel is specified with a kernel shape, <span class="s1">functionType</span>, followed by zero or more ellipsis arguments; see <span class="s1">smooth()</span> for further information.<span class="Apple-converted-space">  </span>For this method, at present only kernel types <span class="s1">"f"</span>, <span class="s1">"l"</span>, <span class="s1">"e"</span>, <span class="s1">"n"</span>, and <span class="s1">"t"</span> are supported, and type <span class="s1">"t"</span> is not presently supported for 3D kernels.</p>
-<p class="p6">This method can be used to find points in the vicinity of individuals that are favorable – possessing more resources, or better environmental conditions, etc.<span class="Apple-converted-space">  </span>It can also be used to guide the dispersal or foraging behavior of individuals.<span class="Apple-converted-space">  </span>See <span class="s1">sampleImprovedNearbyPoint()</span> for a variant that may be useful for directed movement across a landscape.</p>
+<p class="p6">This method can be used to find points in the vicinity of individuals that are favorable – possessing more resources, or better environmental conditions, etc.<span class="Apple-converted-space">  </span>It can also be used to guide the dispersal or foraging behavior of individuals.<span class="Apple-converted-space">  </span>See <span class="s1">sampleImprovedNearbyPoint()</span> for a variant that may be useful for directed movement across a landscape.<span class="Apple-converted-space">  </span>Note that the algorithm for <span class="s1">sampleNearbyPoint()</span> works by rejection sampling, and so will be very inefficient if the maximum value of the map (anywhere, across the entire map) is much larger than the typical value of the map where individuals are.<span class="Apple-converted-space">  </span>The algorithm for <span class="s1">sampleImprovedNearbyPoint()</span> is different, and does not exhibit this performance issue.</p>
 <p class="p5">– (object&lt;SpatialMap&gt;$)smooth(float$ maxDistance, string$ functionType, ...)</p>
 <p class="p6">Smooths (or blurs, one could say) the values of the spatial map by convolution with a kernel.<span class="Apple-converted-space">  </span>The kernel is specified with a maximum distance <span class="s1">maxDistance</span> (beyond which the kernel cuts off to a value of zero), a kernel type <span class="s1">functionType</span> that should be <span class="s1">"f"</span>, <span class="s1">"l"</span>, <span class="s1">"e"</span>, <span class="s1">"n"</span>, <span class="s1">"c"</span>, or <span class="s1">"t"</span>, and additional parameters in the ellipsis <span class="s1">...</span> that depend upon the kernel type and further specify its shape.<span class="Apple-converted-space">  </span>The target spatial map is returned, to allow easy chaining of operations.</p>
 <p class="p6">The kernel specification is similar to that for the <span class="s1">setInteractionType()</span> method of <span class="s1">InteractionType</span>, but omits the maximum value of the kernel.<span class="Apple-converted-space">  </span>Specifically, <span class="s1">functionType</span> may be <span class="s1">"f"</span>, in which case no ellipsis arguments should be supplied; <span class="s1">"l"</span>, similarly with no ellipsis arguments; <span class="s1">"e"</span>, in which case the ellipsis should supply a <span class="s1">numeric$</span> lambda (rate) parameter for a negative exponential function; <span class="s1">"n"</span>, in which case the ellipsis should supply a <span class="s1">numeric$</span> sigma (standard deviation) parameter for a Gaussian function; <span class="s1">"c"</span>, in which case the ellipsis should supply a <span class="s1">numeric$</span> scale parameter for a Cauchy distribution function; or <span class="s1">"t"</span>, in which case the ellipsis should supply a <span class="s1">numeric$</span> degrees of freedom and a <span class="s1">numeric$</span> scale parameter for a <i>t</i>-distribution function.<span class="Apple-converted-space">  </span>See the <span class="s1">InteractionType</span> class documentation for discussions of these kernel types.</p>

SLiMgui/SLiMHelpClasses.rtf

@@ -6252,7 +6252,11 @@ The kernel is specified with a kernel shape,
 \f4\fs20  is not presently supported for 3D kernels.\
 This method can be used to find points in the vicinity of individuals that are favorable \'96 possessing more resources, or better environmental conditions, etc.  It can also be used to guide the dispersal or foraging behavior of individuals.  See 
 \f3\fs18 sampleImprovedNearbyPoint()
-\f4\fs20  for a variant that may be useful for directed movement across a landscape.\
+\f4\fs20  for a variant that may be useful for directed movement across a landscape.  Note that the algorithm for 
+\f3\fs18 sampleNearbyPoint()
+\f4\fs20  works by rejection sampling, and so will be very inefficient if the maximum value of the map (anywhere, across the entire map) is much larger than the typical value of the map where individuals are.  The algorithm for 
+\f3\fs18 sampleImprovedNearbyPoint()
+\f4\fs20  is different, and does not exhibit this performance issue.\
 \pard\pardeftab397\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
 \f3\fs18 \cf2 \'96\'a0(object<SpatialMap>$)smooth(float$\'a0maxDistance, string$\'a0functionType, ...)\