add parameter outside to filter()

Author: bhaller

EidosScribe/EidosHelpFunctions.rtf

@@ -915,7 +915,7 @@
 \f3\fs20  with a matrix or array argument, because the desired behavior in that case has not yet been implemented.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
-\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (float)filter(numeric\'a0x, float\'a0filter)\
+\f1\fs18 \cf2 \kerning1\expnd0\expndtw0 (float)filter(numeric\'a0x, float\'a0filter, [lif$\'a0outside\'a0=\'a0F])\
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
 \f3\fs20 \cf2 Returns the result of convolving 
@@ -932,24 +932,59 @@
 \f1\fs18 filter
 \f3\fs20  value with each 
 \f1\fs18 x
-\f3\fs20  value within the filter\'92s range.  If the filter, centered over a given value of 
+\f3\fs20  value within the filter\'92s range.  The length of 
+\f1\fs18 filter
+\f3\fs20  is required to be odd, so that the filter has a central value (and can thus be centered over each value of 
+\f1\fs18 x
+\f3\fs20 ).\
+If the filter, centered over a given value of 
 \f1\fs18 x
 \f3\fs20 , extends beyond the end of 
 \f1\fs18 x
-\f3\fs20  the corresponding result element will be 
+\f3\fs20  then the calculation of the corresponding element of the result is governed by the 
+\f1\fs18 outside
+\f3\fs20  parameter.  When 
+\f1\fs18 outside
+\f3\fs20  is 
+\f1\fs18 F
+\f3\fs20  (the default), the corresponding element in the result will be 
 \f1\fs18 NAN
-\f3\fs20  since its value is undefined.  The length of 
-\f1\fs18 filter
-\f3\fs20  is required to be odd, so that the filter has a central value (and can thus be centered over each value of 
+\f3\fs20 ; this matches the behavior of the R 
+\f1\fs18 filter()
+\f3\fs20  function (except that R uses 
+\f1\fs18 NA
+\f3\fs20 ).  If 
+\f1\fs18 outside
+\f3\fs20  is 
+\f1\fs18 T
+\f3\fs20 , values outside 
 \f1\fs18 x
-\f3\fs20 ).\
-This function is useful for computing running means and similar transformations of an input vector,.  For a simple running mean of width 
+\f3\fs20  will be excluded from the calculation (the filter value covering that position will be considered to be 
+\f1\fs18 0
+\f3\fs20 ), and the other values in the filter will be adjusted so that the sum of the absolute values of the filter weights used is unchanged, to compensate for the excluded values by giving the positions inside 
+\f1\fs18 x
+\f3\fs20  more weight. Finally, if 
+\f1\fs18 outside
+\f3\fs20  is 
+\f1\fs18 integer
+\f3\fs20  or 
+\f1\fs18 float
+\f3\fs20 , that value will be used as the value of 
+\f1\fs18 x
+\f3\fs20  for all positions outside 
+\f1\fs18 x
+\f3\fs20 ; one might pass an expected value or mean value in this way, to be used for all outside positions.\
+This function is useful for computing running means and similar transformations of an input vector.  For a simple running mean of width 
 \f1\fs18 w
 \f3\fs20 , pass r
 \f1\fs18 ep(1/w, w)
 \f3\fs20  for 
 \f1\fs18 filter
-\f3\fs20 .\
+\f3\fs20 .  That case is automatically detected and handled efficiently; otherwise, the runtime of this function is proportional to the length of 
+\f1\fs18 x
+\f3\fs20  times the length of 
+\f1\fs18 filter
+\f3\fs20 , and so will be slow for long filters.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
 \f1\fs18 \cf0 (+$)max(+\'a0x, ...)\

QtSLiM/help/EidosHelpFunctions.html

@@ -118,9 +118,10 @@
 <p class="p5"><span class="s5">Returns the <b>sample Pearson’s correlation coefficient</b> between </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5">, usually denoted <i>r</i>.<span class="Apple-converted-space">  </span>The sizes of </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5"> must be identical.<span class="Apple-converted-space">  </span>If </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5"> have a size of </span><span class="s6">0</span><span class="s5"> or </span><span class="s6">1</span><span class="s5">, the return value will be </span><span class="s6">NULL</span><span class="s5">.<span class="Apple-converted-space">  </span>At present it is illegal to call </span><span class="s6">cor()</span><span class="s5"> with a matrix or array argument, because the desired behavior in that case has not yet been implemented.</span></p>
 <p class="p4"><span class="s5">(float$)cov(numeric x, numeric y)</span></p>
 <p class="p5"><span class="s5">Returns the <b>corrected sample covariance</b> between </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5">.<span class="Apple-converted-space">  </span>The sizes of </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5"> must be identical.<span class="Apple-converted-space">  </span>If </span><span class="s6">x</span><span class="s5"> and </span><span class="s6">y</span><span class="s5"> have a size of </span><span class="s6">0</span><span class="s5"> or </span><span class="s6">1</span><span class="s5">, the return value will be </span><span class="s6">NULL</span><span class="s5">.<span class="Apple-converted-space">  </span>At present it is illegal to call </span><span class="s6">cov()</span><span class="s5"> with a matrix or array argument, because the desired behavior in that case has not yet been implemented.</span></p>
-<p class="p4">(float)filter(numeric x, float filter)</p>
-<p class="p5">Returns the result of convolving <span class="s2">x</span> with <span class="s2">filter</span>.<span class="Apple-converted-space">  </span>The returned vector will be the same length as <span class="s2">x</span>.<span class="Apple-converted-space">  </span>The convolution is performed by centering <span class="s2">filter</span> on each position of <span class="s2">x</span> to produce a corresponding result element that is the sum over the products of each <span class="s2">filter</span> value with each <span class="s2">x</span> value within the filter’s range.<span class="Apple-converted-space">  </span>If the filter, centered over a given value of <span class="s2">x</span>, extends beyond the end of <span class="s2">x</span> the corresponding result element will be <span class="s2">NAN</span> since its value is undefined.<span class="Apple-converted-space">  </span>The length of <span class="s2">filter</span> is required to be odd, so that the filter has a central value (and can thus be centered over each value of <span class="s2">x</span>).</p>
-<p class="p5">This function is useful for computing running means and similar transformations of an input vector,.<span class="Apple-converted-space">  </span>For a simple running mean of width <span class="s2">w</span>, pass r<span class="s2">ep(1/w, w)</span> for <span class="s2">filter</span>.</p>
+<p class="p4">(float)filter(numeric x, float filter, [lif$ outside = F])</p>
+<p class="p5">Returns the result of convolving <span class="s2">x</span> with <span class="s2">filter</span>.<span class="Apple-converted-space">  </span>The returned vector will be the same length as <span class="s2">x</span>.<span class="Apple-converted-space">  </span>The convolution is performed by centering <span class="s2">filter</span> on each position of <span class="s2">x</span> to produce a corresponding result element that is the sum over the products of each <span class="s2">filter</span> value with each <span class="s2">x</span> value within the filter’s range.<span class="Apple-converted-space">  </span>The length of <span class="s2">filter</span> is required to be odd, so that the filter has a central value (and can thus be centered over each value of <span class="s2">x</span>).</p>
+<p class="p5">If the filter, centered over a given value of <span class="s2">x</span>, extends beyond the end of <span class="s2">x</span> then the calculation of the corresponding element of the result is governed by the <span class="s2">outside</span> parameter.<span class="Apple-converted-space">  </span>When <span class="s2">outside</span> is <span class="s2">F</span> (the default), the corresponding element in the result will be <span class="s2">NAN</span>; this matches the behavior of the R <span class="s2">filter()</span> function (except that R uses <span class="s2">NA</span>).<span class="Apple-converted-space">  </span>If <span class="s2">outside</span> is <span class="s2">T</span>, values outside <span class="s2">x</span> will be excluded from the calculation (the filter value covering that position will be considered to be <span class="s2">0</span>), and the other values in the filter will be adjusted so that the sum of the absolute values of the filter weights used is unchanged, to compensate for the excluded values by giving the positions inside <span class="s2">x</span> more weight. Finally, if <span class="s2">outside</span> is <span class="s2">integer</span> or <span class="s2">float</span>, that value will be used as the value of <span class="s2">x</span> for all positions outside <span class="s2">x</span>; one might pass an expected value or mean value in this way, to be used for all outside positions.</p>
+<p class="p5">This function is useful for computing running means and similar transformations of an input vector.<span class="Apple-converted-space">  </span>For a simple running mean of width <span class="s2">w</span>, pass r<span class="s2">ep(1/w, w)</span> for <span class="s2">filter</span>.<span class="Apple-converted-space">  </span>That case is automatically detected and handled efficiently; otherwise, the runtime of this function is proportional to the length of <span class="s2">x</span> times the length of <span class="s2">filter</span>, and so will be slow for long filters.</p>
 <p class="p2">(+$)max(+ x, ...)</p>
 <p class="p3">Returns the <b>maximum</b> of <span class="s2">x</span> and the other arguments supplied: the single greatest value contained by all of them.<span class="Apple-converted-space">  </span>All of the arguments must be the same type as <span class="s2">x</span>, and the return type will match that of <span class="s2">x</span><span class="s3">.</span><span class="Apple-converted-space">  </span>If all of the arguments have a size of <span class="s2">0</span>, the return value will be <span class="s2">NULL</span>; note that this means that <span class="s2">max(x, max(y))</span> may produce an error, if <span class="s2">max(y)</span> is <span class="s2">NULL</span>, in cases where <span class="s2">max(x, y)</span> does not.</p>
 <p class="p2">(float$)mean(lif<span class="s1"> </span>x)</p>

VERSIONS

@@ -26,7 +26,7 @@ development head (in the master branch):
 	fix #534, support uniparentally-transmitted chromosomes in hermaphrodite populations
 	add new Plot legendTitleEntry() method for making a title line in a plot legend
 	click-drag in the SLiMgui script view's line number area now drag-selects whole lines
-	fix #550, add filter() function to Eidos, which is essentially a subset of R's filter(): (float)filter(numeric x, float filter)
+	fix #550, add filter() function to Eidos, which is essentially a subset of R's filter(): (float)filter(numeric x, float filter, [lif$ outside = F])
 	partial fix for #530, add function (numeric$)tr(numeric x) to obtain the trace of a square matrix
 	partial fix for #530, add function (numeric)outerProduct(numeric x, numeric y) to obtain the outer product of vectors x and y
 	partial fix for #530, add function (numeric$)det(numeric x) to obtain the determinant of a square matrix

eidos/eidos_functions.cpp

@@ -147,7 +147,7 @@ const std::vector<EidosFunctionSignature_CSP> &EidosInterpreter::BuiltInFunction
 
 		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("cor",				Eidos_ExecuteFunction_cor,			kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddNumeric("x")->AddNumeric("y"));
 		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("cov",				Eidos_ExecuteFunction_cov,			kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddNumeric("x")->AddNumeric("y"));
-		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("filter",			Eidos_ExecuteFunction_filter,		kEidosValueMaskFloat))->AddNumeric("x")->AddFloat("filter"));
+		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("filter",			Eidos_ExecuteFunction_filter,		kEidosValueMaskFloat))->AddNumeric("x")->AddFloat("filter")->AddLogicalEquiv_OS("outside", gStaticEidosValue_LogicalF));
 		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("max",				Eidos_ExecuteFunction_max,			kEidosValueMaskAnyBase | kEidosValueMaskSingleton))->AddAnyBase("x")->AddEllipsis());
 		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("mean",				Eidos_ExecuteFunction_mean,			kEidosValueMaskFloat | kEidosValueMaskSingleton))->AddLogicalEquiv("x"));
 		signatures->emplace_back((EidosFunctionSignature *)(new EidosFunctionSignature("min",				Eidos_ExecuteFunction_min,			kEidosValueMaskAnyBase | kEidosValueMaskSingleton))->AddAnyBase("x")->AddEllipsis());