policy change for cor()/cov()/sd()/var(): return NAN when x is too short

Author: bhaller

EidosScribe/EidosHelpFunctions.rtf

@@ -895,7 +895,9 @@
 \f1\fs18 0
 \f3\fs20  or 
 \f1\fs18 1
-\f3\fs20 , an error will be raised (a change in behavior from Eidos 4.0; it used to return 
+\f3\fs20 , 
+\f1\fs18 NAN
+\f3\fs20  will be returned (a change in behavior from Eidos 4.0; it used to return 
 \f1\fs18 NULL
 \f3\fs20 ).  The return value will be a singleton 
 \f1\fs18 float
@@ -968,7 +970,9 @@ It is also legal to call
 \f1\fs18 0
 \f3\fs20  or 
 \f1\fs18 1
-\f3\fs20 , an error will be raised (a change in behavior from Eidos 4.0; it used to return 
+\f3\fs20 , 
+\f1\fs18 NAN
+\f3\fs20  will be returned (a change in behavior from Eidos 4.0; it used to return 
 \f1\fs18 NULL
 \f3\fs20 ).  The return value will be a singleton 
 \f1\fs18 float
@@ -1441,7 +1445,9 @@ The result for all of these
 \f1\fs18 0
 \f3\fs20  or 
 \f1\fs18 1
-\f3\fs20 , an error will be raised (a change in behavior from Eidos 4.0; it used to return 
+\f3\fs20 , 
+\f1\fs18 NAN
+\f3\fs20  will be returned (a change in behavior from Eidos 4.0; it used to return 
 \f1\fs18 NULL
 \f3\fs20 ).  Matrix/array dimensions are ignored by 
 \f1\fs18 sd()
@@ -1515,7 +1521,9 @@ The result for all of these
 \f1\fs18 0
 \f3\fs20  or 
 \f1\fs18 1
-\f3\fs20 , an error will be raised (a change in behavior from Eidos 4.0; it used to return 
+\f3\fs20 , 
+\f1\fs18 NAN
+\f3\fs20  will be returned (a change in behavior from Eidos 4.0; it used to return 
 \f1\fs18 NULL
 \f3\fs20 ).  This is the square of the standard deviation calculated by 
 \f1\fs18 sd()

QtSLiM/help/EidosHelpFunctions.html

@@ -115,10 +115,10 @@
 <p class="p3">Returns the <b>truncation</b> of <span class="s2">x</span>: the integral value nearest to, but no larger in magnitude than, <span class="s2">x</span>.<span class="Apple-converted-space">  </span>Note that the return value is <span class="s2">float</span> even though integral values are guaranteed, because values could be outside of the range representable by <span class="s2">integer</span><span class="s3">.</span></p>
 <p class="p1"><b>3.2.<span class="Apple-converted-space">  </span>Statistics functions</b></p>
 <p class="p4"><span class="s5">(float)cor(numeric x, </span>[Nif y = NULL]<span class="s5">)</span></p>
-<p class="p5">Returns the <b>sample Pearson’s correlation coefficient</b> between vectors <span class="s2">x</span> and <span class="s2">y</span>, usually denoted <i>r</i>.<span class="Apple-converted-space">  </span>If <span class="s2">y</span> is <span class="s2">NULL</span>, it is considered to have the same value as <span class="s2">x</span>; for vector <span class="s2">x</span> this is not very useful (since the correlation of <span class="s2">x</span> with itself is <span class="s2">1.0</span> by definition), but it is more useful for calculating a correlation matrix using the columns of <span class="s2">x</span> (see below).<span class="Apple-converted-space">  </span>The sizes of <span class="s2">x</span> and <span class="s2">y</span> must be identical.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">y</span> have a size of <span class="s2">0</span> or <span class="s2">1</span>, an error will be raised (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>The return value will be a singleton <span class="s2">float</span>.</p>
+<p class="p5">Returns the <b>sample Pearson’s correlation coefficient</b> between vectors <span class="s2">x</span> and <span class="s2">y</span>, usually denoted <i>r</i>.<span class="Apple-converted-space">  </span>If <span class="s2">y</span> is <span class="s2">NULL</span>, it is considered to have the same value as <span class="s2">x</span>; for vector <span class="s2">x</span> this is not very useful (since the correlation of <span class="s2">x</span> with itself is <span class="s2">1.0</span> by definition), but it is more useful for calculating a correlation matrix using the columns of <span class="s2">x</span> (see below).<span class="Apple-converted-space">  </span>The sizes of <span class="s2">x</span> and <span class="s2">y</span> must be identical.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">y</span> have a size of <span class="s2">0</span> or <span class="s2">1</span>, <span class="s2">NAN</span> will be returned (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>The return value will be a singleton <span class="s2">float</span>.</p>
 <p class="p5">It is also legal to call <span class="s2">cor()</span> with matrix <span class="s2">x</span> and/or <span class="s2">y</span>.<span class="Apple-converted-space">  </span>In this case the return value will be a correlation matrix between x and y.<span class="Apple-converted-space">  </span>Each column of <span class="s2">x</span> will be represented by one row of the result (or if <span class="s2">x</span> is a vector, the result will simply have one row representing <span class="s2">x</span>), and each column of <span class="s2">y</span> will be represented by one column of the result (or if <span class="s2">y</span> is a vector, the result will simply have one column representing <span class="s2">y</span>).<span class="Apple-converted-space">  </span>Each element in the result matrix will therefore represent the correlation between a column of matrix <span class="s2">x</span> (or the entirety of vector <span class="s2">x</span>) and a column of matrix <span class="s2">y</span> (or the entirety of vector y).<span class="Apple-converted-space">  </span>Calling <span class="s2">cor(x, x)</span>, or equivalently <span class="s2">cor(x)</span>, thus produces a symmetric correlation matrix among the columns of <span class="s2">x</span>.</p>
 <p class="p4"><span class="s5">(float)cov(numeric x, </span>[Nif y = NULL]<span class="s5">)</span></p>
-<p class="p5">Returns the <b>corrected sample covariance</b> between vectors <span class="s2">x</span> and <span class="s2">y</span>.<span class="Apple-converted-space">  </span>If <span class="s2">y</span> is <span class="s2">NULL</span>, it is considered to have the same value as <span class="s2">x</span>; for vector <span class="s2">x</span> this is equivalent to calling <span class="s2">var(x)</span>, but it is more useful for calculating a variance-covariance matrix using the columns of <span class="s2">x</span> (see below).<span class="Apple-converted-space">  </span>The sizes of <span class="s2">x</span> and <span class="s2">y</span> must be identical.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">y</span> have a size of <span class="s2">0</span> or <span class="s2">1</span>, an error will be raised (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>The return value will be a singleton <span class="s2">float</span>.</p>
+<p class="p5">Returns the <b>corrected sample covariance</b> between vectors <span class="s2">x</span> and <span class="s2">y</span>.<span class="Apple-converted-space">  </span>If <span class="s2">y</span> is <span class="s2">NULL</span>, it is considered to have the same value as <span class="s2">x</span>; for vector <span class="s2">x</span> this is equivalent to calling <span class="s2">var(x)</span>, but it is more useful for calculating a variance-covariance matrix using the columns of <span class="s2">x</span> (see below).<span class="Apple-converted-space">  </span>The sizes of <span class="s2">x</span> and <span class="s2">y</span> must be identical.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">y</span> have a size of <span class="s2">0</span> or <span class="s2">1</span>, <span class="s2">NAN</span> will be returned (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>The return value will be a singleton <span class="s2">float</span>.</p>
 <p class="p5">It is also legal to call <span class="s2">cov()</span> with matrix <span class="s2">x</span> and/or <span class="s2">y</span>.<span class="Apple-converted-space">  </span>In this case the return value will be a covariance matrix between x and y.<span class="Apple-converted-space">  </span>Each column of <span class="s2">x</span> will be represented by one row of the result (or if <span class="s2">x</span> is a vector, the result will simply have one row representing <span class="s2">x</span>), and each column of <span class="s2">y</span> will be represented by one column of the result (or if <span class="s2">y</span> is a vector, the result will simply have one column representing <span class="s2">y</span>).<span class="Apple-converted-space">  </span>Each element in the result matrix will therefore represent the covariance between a column of matrix <span class="s2">x</span> (or the entirety of vector <span class="s2">x</span>) and a column of matrix <span class="s2">y</span> (or the entirety of vector y).<span class="Apple-converted-space">  </span>Calling <span class="s2">cov(x, x)</span>, or equivalently <span class="s2">cov(x)</span>, thus produces a symmetric variance-covariance matrix among the columns of <span class="s2">x</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>
@@ -143,12 +143,12 @@
 <p class="p5">Returns the <b>ranks</b> of the elements of <span class="s2">x</span>: a vector of length <span class="s2">L</span> (the length of <span class="s2">x</span>), composed of the relative ranks, from <span class="s2">1</span> to <span class="s2">L</span>, of each corresponding element of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>The <span class="s2">tiesMethod</span> parameter may be any of <span class="s2">"average"</span> (the default), <span class="s2">"first"</span>, <span class="s2">"last"</span>, <span class="s2">"max"</span>, or <span class="s2">"min"</span> (<span class="s2">"random"</span>, supported by R, is not supported by Eidos at this time but could be added if needed).<span class="Apple-converted-space">  </span>For <span class="s2">"average"</span>, the return value is of type <span class="s2">float</span>; for all others, it is of type <span class="s2">integer</span>.<span class="Apple-converted-space">  </span>(Note that the return type does <i>not</i> depend upon the type of <span class="s2">x</span>.)</p>
 <p class="p5">The result for all of these <span class="s2">tiesMethod</span> values is identical (except for type) if the elements of <span class="s2">x</span> are unique; the difference between these methods is in how ties are resolved.<span class="Apple-converted-space">  </span>Suppose that <i>n</i> elements of <span class="s2">x</span> are tied (because they are equal), corresponding to ranks <i>k</i> through <i>k</i>+<i>n−</i>1.<span class="Apple-converted-space">  </span>For <span class="s2">tiesMethod</span> <span class="s2">"average"</span>, all <i>n</i> tied elements receive the same rank, (<i>k</i> + (<i>n−</i>1)/2), which is the average of the ranks.<span class="Apple-converted-space">  </span>For <span class="s2">"first"</span>, the first tied element receives rank <i>k</i>, upward to the last tied element receiving rank <i>k</i>+<i>n−</i>1.<span class="Apple-converted-space">  </span>For <span class="s2">"last"</span>, the last tied element receives rank <i>k</i>, downward to the first tied element receiving rank <i>k</i>+<i>n−</i>1.<span class="Apple-converted-space">  </span>For <span class="s2">"max"</span>, all <i>n</i> tied element receive the maximum rank, <i>k</i>+<i>n−</i>1.<span class="Apple-converted-space">  </span>For <span class="s2">"min"</span>, all <i>n</i> tied element receive the minimum rank, <i>k</i>.</p>
 <p class="p2">(float$)sd(numeric<span class="s1"> </span>x)</p>
-<p class="p5">Returns the <b>corrected sample standard deviation</b> of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> has a size of <span class="s2">0</span> or <span class="s2">1</span>, an error will be raised (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>Matrix/array dimensions are ignored by <span class="s2">sd()</span>; it simply uses all of the elements of <span class="s2">x</span> for its calculation.</p>
+<p class="p5">Returns the <b>corrected sample standard deviation</b> of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> has a size of <span class="s2">0</span> or <span class="s2">1</span>, <span class="s2">NAN</span> will be returned (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>Matrix/array dimensions are ignored by <span class="s2">sd()</span>; it simply uses all of the elements of <span class="s2">x</span> for its calculation.</p>
 <p class="p2">(float$)ttest(float<span class="s1"> </span>x, [Nf y = NULL], [Nf$ mu = NULL])</p>
 <p class="p3">Returns the <i>p</i>-value resulting from running a <i>t</i>-test with the supplied data.<span class="Apple-converted-space">  </span>Two types of <i>t</i><span class="s3">-</span>tests can be performed.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">y</span> are supplied (i.e., <span class="s2">y</span> is non-<span class="s2">NULL</span>), a two-sample unpaired two-sided Welch’s <i>t</i>-test is conducted using the samples in <span class="s2">x</span> and <span class="s2">y</span>, each of which must contain at least two elements.<span class="Apple-converted-space">  </span>The null hypothesis for this test is that the two samples are drawn from populations with the same mean.<span class="Apple-converted-space">  </span>Other options, such as pooled-variance <i>t</i>-tests, paired <i>t</i>-tests, and one-sided <i>t</i>-tests, are not presently available.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> and <span class="s2">mu</span> are supplied (i.e., <span class="s2">mu</span> is non-<span class="s2">NULL</span>), a one-sample <i>t</i>-test is conducted in which the null hypothesis is that the sample is drawn from a population with mean <span class="s2">mu</span><span class="s3">.</span></p>
 <p class="p3">Note that the results from this function are substantially different from those produced by R.<span class="Apple-converted-space">  </span>The Eidos <span class="s2">ttest() </span>function uses uncorrected sample statistics, which means they will be biased for small sample sizes, whereas R probably uses corrected, unbiased sample statistics.<span class="Apple-converted-space">  </span>This is an Eidos bug, and might be fixed if anyone complains.<span class="Apple-converted-space">  </span>If large sample sizes are used, however, the bias is likely to be small, and uncorrected statistics are simpler and faster to compute.</p>
 <p class="p4"><span class="s5">(float$)var(numeric x)</span></p>
-<p class="p5">Returns the <b>corrected sample variance</b> of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> has a size of <span class="s2">0</span> or <span class="s2">1</span>, an error will be raised (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>This is the square of the standard deviation calculated by <span class="s2">sd()</span>.<span class="Apple-converted-space">  </span>It is illegal to call <span class="s2">var()</span> with a matrix or array argument; use <span class="s2">cov()</span> to calculate a variance-covariance matrix.</p>
+<p class="p5">Returns the <b>corrected sample variance</b> of <span class="s2">x</span>.<span class="Apple-converted-space">  </span>If <span class="s2">x</span> has a size of <span class="s2">0</span> or <span class="s2">1</span>, <span class="s2">NAN</span> will be returned (a change in behavior from Eidos 4.0; it used to return <span class="s2">NULL</span>).<span class="Apple-converted-space">  </span>This is the square of the standard deviation calculated by <span class="s2">sd()</span>.<span class="Apple-converted-space">  </span>It is illegal to call <span class="s2">var()</span> with a matrix or array argument; use <span class="s2">cov()</span> to calculate a variance-covariance matrix.</p>
 <p class="p1"><b>3.3.<span class="Apple-converted-space">  </span>Distribution drawing and density functions</b></p>
 <p class="p4"><span class="s5">(float)dmvnorm(float x, numeric mu, numeric sigma)</span></p>
 <p class="p5"><span class="s5">Returns a vector of <b>probability densities for a <i>k</i>-dimensional multivariate normal distribution</b> with a length <i>k</i> mean vector </span><span class="s9">mu</span><span class="s5"> and a <i>k</i> × <i>k</i> variance-covariance matrix </span><span class="s9">sigma</span><span class="s5">.<span class="Apple-converted-space">  </span>The </span><span class="s9">mu</span><span class="s5"> and </span><span class="s9">sigma</span><span class="s5"> parameters are used for all densities.<span class="Apple-converted-space">  </span>The quantile values, </span><span class="s9">x</span><span class="s5">, should be supplied as a matrix with one row per vector of quantile values and <i>k</i> columns (one column per dimension); for convenience, a single quantile may be supplied as a vector rather than a matrix with just one row.<span class="Apple-converted-space">  </span>The number of dimensions <i>k</i> must be at least two; for <i>k</i>=1, use </span><span class="s9">dnorm()</span><span class="s5">.</span></p>

VERSIONS

@@ -33,7 +33,7 @@ development head (in the master branch):
 	partial fix for #530, add function (float)inverse(numeric x) to obtain the inverse of a square non-singular matrix
 	partial fix for #530, add function (numeric)matrixPow(numeric x, integer$ power) to raise a matrix to an integer power
 	partial fix for #530, extend cor() and cov() to support correlation/covariance between the columns of a matrix (or matrices), as in R
-		policy change: cov(x, y), cor(x, y), var(x), and sd(x) with x and/or y of length 1 now errors (used to return NULL);
+		policy change: cov(x, y), cor(x, y), var(x), and sd(x) with x and/or y of length 1 now returns NAN (used to return NULL);
 			this is because you can't make a matrix containing NULLs, and Eidos doesn't have NA (which is what R uses in this case)