commit
message
[ALL] documenting functions loaded from jStat
author
Ben Vogt <[email protected]>
date
2017-04-29 22:29:24
stats
4 file(s) changed,
100 insertions(+),
11 deletions(-)
files
README.md
src/RawFormulas/Math.ts
src/RawFormulas/Statistical.ts
tests/StatisticalTest.ts
1diff --git a/README.md b/README.md
2index 8f2e811..77ea268 100644
3--- a/README.md
4+++ b/README.md
5@@ -1,5 +1,5 @@
6 # Spreadsheet
7-TypeScript implementation of a spreadsheet.
8+TypeScript/javascript implementation of a spreadsheet.
9
10 ## TODO
11 Things I should do.
12@@ -10,14 +10,6 @@ And the same for MAX, MAXA, COUNT, COUNTA, etc. Look these over.
13 ### Criteria evaluations should escape reg-ex characters
14 http://stackoverflow.com/questions/3446170/escape-string-for-use-in-javascript-regex
15
16-### Document the functions pulled in from jStat.
17-
18-### Double check all relevant formulas from MSExcel and GS have been implemented.
19-
20-### Refactor the way tests are organized.
21-Group by error type and have some useful functions that will call with 0, N, N+1 args to test the args
22-checker. Also, test for *all possible* errors that could be thrown, and *all possible types* that could be passed in.
23-Another thing to think about would be throwing custom errors if an object is passed in.
24
25 ### jStat functions should know their caller
26 Either through `arguments`, or directly passed in like `mean("FORMULA", [10, 20, 30])`
27diff --git a/src/RawFormulas/Math.ts b/src/RawFormulas/Math.ts
28index 3123058..335bcc3 100644
29--- a/src/RawFormulas/Math.ts
30+++ b/src/RawFormulas/Math.ts
31@@ -823,7 +823,17 @@ var ERF = function (...values) : number {
32 return values.length === 1 ? erf(lower) : erf(upper) - erf(lower);
33 };
34
35-// erf function from jStat [http://www.jstat.org/]
36+
37+/**
38+ * Returns the error function evaluated at x. See also:
39+ *
40+ * * http://jstat.github.io/special-functions.html#erf
41+ *
42+ * * https://github.com/jstat/jstat/search?utf8=%E2%9C%93&q=erf&type=
43+ *
44+ * @param x to evaluate
45+ * @returns {number} error
46+ */
47 function erf(x) {
48 var cof = [-1.3026537197817094, 6.4196979235649026e-1, 1.9476473204185836e-2,
49 -9.561514786808631e-3, -9.46595344482036e-4, 3.66839497852761e-4,
50diff --git a/src/RawFormulas/Statistical.ts b/src/RawFormulas/Statistical.ts
51index e1aeb88..70d7f15 100644
52--- a/src/RawFormulas/Statistical.ts
53+++ b/src/RawFormulas/Statistical.ts
54@@ -192,15 +192,30 @@ var AVERAGEA = function (...values) {
55 * @constructor
56 */
57 var CORREL = function (...values) : number {
58+ /**
59+ * Return the standard deviation of a vector. By defaut, the population standard deviation is returned. Passing true
60+ * for the flag parameter returns the sample standard deviation. See http://jstat.github.io/vector.html#stdev for
61+ * more information.
62+ */
63 function stdev(arr, flag) {
64 return Math.sqrt(variance(arr, flag));
65 }
66+
67+ /**
68+ * Return the variance of a vector. By default, the population variance is calculated. Passing true as the flag
69+ * indicates computes the sample variance instead. See http://jstat.github.io/vector.html#variance for more
70+ * information.
71+ */
72 function variance(arr, flag) {
73 if ((arr.length - (flag ? 1 : 0)) === 0) {
74 throw new DivZeroError("Evaluation of function CORREL caused a divide by zero error.");
75 }
76 return sumsqerr(arr) / (arr.length - (flag ? 1 : 0));
77 }
78+
79+ /**
80+ * Return the sum of a vector. See http://jstat.github.io/vector.html#sum for more information.
81+ */
82 function sum(arr) {
83 var sum = 0;
84 var i = arr.length;
85@@ -209,12 +224,20 @@ var CORREL = function (...values) : number {
86 }
87 return sum;
88 }
89+ /**
90+ * Return the mean of a vector. See http://jstat.github.io/vector.html#mean for more information.
91+ */
92 function mean(arr) {
93 if (arr.length === 0) {
94 throw new DivZeroError("Evaluation of function CORREL caused a divide by zero error.");
95 }
96 return sum(arr) / arr.length;
97 }
98+
99+ /**
100+ * Return the sum of squared errors of prediction of a vector. See http://jstat.github.io/vector.html#sumsqerr for
101+ * more information.
102+ */
103 function sumsqerr(arr) {
104 var m = mean(arr);
105 var sum = 0;
106@@ -226,6 +249,10 @@ var CORREL = function (...values) : number {
107 }
108 return sum;
109 }
110+
111+ /**
112+ * Return the covariance of two vectors. See http://jstat.github.io/vector.html#covariance for more information.
113+ */
114 function covariance(arr1, arr2) {
115 var u = mean(arr1);
116 var v = mean(arr2);
117@@ -308,6 +335,10 @@ var EXPONDIST = function (...values) : number {
118 * TODO: This function should be stricter in its return type.
119 */
120 var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
121+ /**
122+ * Returns the Log-Gamma function evaluated at x. See http://jstat.github.io/special-functions.html#gammaln for more
123+ * information.
124+ */
125 function gammaln(x) {
126 var j = 0;
127 var cof = [
128@@ -322,6 +353,11 @@ var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
129 ser += cof[j] / ++y;
130 return Math.log(2.5066282746310005 * ser / xx) - tmp;
131 }
132+
133+ /**
134+ * Returns the Gamma function evaluated at x. This is sometimes called the 'complete' gamma function. See
135+ * http://jstat.github.io/special-functions.html#gammafn for more information.
136+ */
137 function gammafn(x) {
138 var p = [-1.716185138865495, 24.76565080557592, -379.80425647094563,
139 629.3311553128184, 866.9662027904133, -31451.272968848367,
140@@ -369,6 +405,11 @@ var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
141 }
142 return res;
143 }
144+
145+ /**
146+ * Returns the continued fraction for the incomplete Beta function with parameters a and b modified by Lentz's method
147+ * evaluated at x. For more information see http://jstat.github.io/special-functions.html#betacf.
148+ */
149 function betacf(x, a, b) {
150 var fpmin = 1e-30;
151 var m = 1;
152@@ -414,6 +455,11 @@ var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
153
154 return h;
155 }
156+
157+ /**
158+ * Returns the incomplete Beta function evaluated at (x,a,b). See http://jstat.github.io/special-functions.html#ibeta
159+ * for more information.
160+ */
161 function ibeta(x, a, b) {
162 // Factors in front of the continued fraction.
163 var bt = (x === 0 || x === 1) ? 0 :
164@@ -428,9 +474,21 @@ var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
165 // else use continued fraction after making the symmetry transformation.
166 return 1 - bt * betacf(1 - x, b, a) / b;
167 }
168+
169+ /**
170+ * Returns the value of x in the cdf of the Gamma distribution with the parameters shape (k) and scale (theta). Notice
171+ * that if using the alpha beta convention, scale = 1/beta. For more information see
172+ * http://jstat.github.io/distributions.html#jStat.gamma.cdf
173+ */
174 function cdf(x, df1, df2) {
175 return ibeta((df1 * x) / (df1 * x + df2), df1 / 2, df2 / 2);
176 }
177+
178+ /**
179+ * Returns the value of x in the pdf of the Gamma distribution with the parameters shape (k) and scale (theta). Notice
180+ * that if using the alpha beta convention, scale = 1/beta. For more information see
181+ * http://jstat.github.io/distributions.html#jStat.gamma.pdf
182+ */
183 function pdf(x, df1, df2) {
184 if (x < 0) {
185 return undefined;
186@@ -468,9 +526,13 @@ var FDIST$LEFTTAILED = function (...values) : number|undefined|boolean {
187 * @param values[2] deg_freedom2 - Required. The denominator degrees of freedom.
188 * @returns {number} inverse of the (right-tailed) F probability distribution
189 * @constructor
190- * TODO: This function needs to be tested more thuroughly.
191+ * TODO: This function needs to be tested more thoroughly.
192 */
193 var FINV = function (...values) : number {
194+ /**
195+ * Returns the continued fraction for the incomplete Beta function with parameters a and b modified by Lentz's method
196+ * evaluated at x. For more information see http://jstat.github.io/special-functions.html#betacf
197+ */
198 function betacf(x, a, b) {
199 var fpmin = 1e-30;
200 var m = 1;
201@@ -516,6 +578,11 @@ var FINV = function (...values) : number {
202
203 return h;
204 }
205+
206+ /**
207+ * Returns the incomplete Beta function evaluated at (x,a,b). See http://jstat.github.io/special-functions.html#ibeta
208+ * for more information.
209+ */
210 function ibeta(x, a, b) : number {
211 // Factors in front of the continued fraction.
212 var bt = (x === 0 || x === 1) ? 0 :
213@@ -532,6 +599,11 @@ var FINV = function (...values) : number {
214 // else use continued fraction after making the symmetry transformation.
215 return 1 - bt * betacf(1 - x, b, a) / b;
216 }
217+
218+ /**
219+ * Returns the Log-Gamma function evaluated at x. For more information see
220+ * http://jstat.github.io/special-functions.html#gammaln
221+ */
222 function gammaln(x) {
223 var j = 0;
224 var cof = [
225@@ -546,6 +618,11 @@ var FINV = function (...values) : number {
226 ser += cof[j] / ++y;
227 return Math.log(2.5066282746310005 * ser / xx) - tmp;
228 }
229+
230+ /**
231+ * Returns the inverse of the incomplete Beta function evaluated at (p,a,b). For more information see
232+ * http://jstat.github.io/special-functions.html#ibetainv
233+ */
234 function ibetainv(p, a, b) {
235 var EPS = 1e-8;
236 var a1 = a - 1;
237@@ -595,6 +672,10 @@ var FINV = function (...values) : number {
238 }
239 return x;
240 }
241+
242+ /**
243+ * http://jstat.github.io/distributions.html
244+ */
245 function inv(x, df1, df2) {
246 return df2 / (df1 * (1 / ibetainv(x, df1 / 2, df2 / 2) - 1));
247 }
248diff --git a/tests/StatisticalTest.ts b/tests/StatisticalTest.ts
249index 15ec9a8..6da9cd4 100644
250--- a/tests/StatisticalTest.ts
251+++ b/tests/StatisticalTest.ts
252@@ -228,6 +228,7 @@ catchAndAssertEquals(function() {
253
254 // Test FINV
255 assertEquals(FINV(0.42, 2, 3), 1.174597274485816);
256+// TODO: Test this more.
257
258
259 // Test FISHER