Statistics

docs/underscore.collections.statistics.md

@@ -0,0 +1,169 @@
+### statistics
+
+> Statisctics Functions. <a href="docs/underscore.collections.statistics.js.html" class="btn btn-primary btn-xs">View Annotated Source</a>
+
+#### mean
+
+Signature: `_.mean(... array:Array ...)`
+
+The `_.mean` function finds out the average value from the array of numbers.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Mean" target="_blank" class="btn btn-primary btn-xs">Mean</a>
+
+```javascript
+
+_.mean([]);
+//=> 0
+
+_.mean([0, 1, 2, 3, 4]);
+//=> 2
+
+_.mean(null)
+//=> 0
+
+```
+
+#### median
+
+Signature: `_.median(... array:Array ...)`
+
+The `_.median` function finds out the middle value from the array of numbers.
+
+Calulation of median is done using the following method.
+
+If the array is odd length then median is the middle element.
+
+If the array is even numbers then average of middle two numbers is the median value.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Median" target="_blank" class="btn btn-primary btn-xs">Median</a>
+
+```javascript
+
+_.median([]);
+//=> undefined
+
+_.median([1, 2, 3]);
+//=> 2
+
+_.median([1, 2, 3, 4])
+// => 2.5
+
+```
+
+#### sum
+
+Signature: `_.sum(... array:Array ...)`
+
+The `_.sum` function calculates the sum of the given array.
+
+```javascript
+
+_.sum([]);
+//=> 0
+
+_.sum([0, 1, 2, 3, 4]);
+//=> 10
+```
+
+#### variance
+
+Signature: `_.variance(... array:Array ...)`
+
+The `_.variance` function return the variance of the numeric elements of the collection.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Variance" target="_blank" class="btn btn-primary btn-xs">Variance</a>
+
+```javascript
+
+_.variance([]);
+//=> 0
+
+_.variance([0, 1, 2, 3, 4]);
+//=> 1.25
+```
+
+#### standardDeviation
+
+Signature: `_.standardDeviation(... array:Array ...)`
+
+The `_.standardDeviation` function return the standard deviation of the numeric elements of the collection.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Standard_deviation" target="_blank" class="btn btn-primary btn-xs">Standard Deviation</a>
+
+```javascript
+
+_.standardDeviation([]);
+//=> 0
+
+_.standardDeviation([1, 2, 3, 4]);
+//=> 1.118
+```
+
+#### standardError
+
+Signature: `_.standardError(... array:Array ...)`
+
+The `_.standardError` function return the standard error of the numeric elements of the collection.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Standard_error" target="_blank" class="btn btn-primary btn-xs">Standard Error</a>
+
+```javascript
+
+_.standardError([]);
+//=> 0
+
+_.standardError([1, 2, 3, 4]);
+//=> 0.64
+```
+
+#### mode
+
+Signature: `_.mode(... array:Array ...)`
+
+The `_.mode` function return the element (or element-based computation) that appears most frequently in the collection.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Mode_(statistics)" target="_blank" class="btn btn-primary btn-xs">Mode</a>
+
+```javascript
+
+_.mode([]);
+//=> undefined
+
+_.mode([1, 1, 3, 4]);
+//=> 1
+```
+
+#### statRange
+
+Signature: `_.statRange(... array:Array ...)`
+
+The `_.statRange` function return the difference of the max and min value of the elements in the array.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Range_(statistics)" target="_blank" class="btn btn-primary btn-xs">Range</a>
+
+```javascript
+
+_.statRange([]);
+//=> -Infinity
+
+_.statRange([1, 1, 3, 4]);
+//=> 3
+```
+
+#### percentile
+
+Signature: `_.percentile(... array:Array ...,percentileVal:number)`
+
+The `_.percentile` function return the percentile value of the numeric elements from the collection like 50th,75th,99th etc.
+
+Link for reference <a href="https://en.wikipedia.org/wiki/Percentile" target="_blank" class="btn btn-primary btn-xs">Percentile</a>
+
+
+```javascript
+
+_.percentile([], 10);
+//=> 0
+
+_.percentile([1, 1, 3, 4], 50);
+//=> 2
+```

modules/index.collections.statistics.js

@@ -0,0 +1,10 @@
+//Statistical Function
+export { default as sum } from './sum.js';
+export { default as mean } from './mean.js';
+export { default as median } from './median.js';
+export { default as standardDeviation } from './standardDeviation.js';
+export { default as variance } from './variance.js';
+export { default as mode } from './mode.js';
+export { default as standardError } from './standardError.js';
+export { default as statRange } from './statRange.js';
+export { default as percentile } from './percentile.js';

modules/mean.js

@@ -0,0 +1,11 @@
+import size from 'underscore/modules/size.js';
+import sum from './sum.js';
+
+// Compute the average of the numbers obtained from the collection
+export default function mean(collection, iteratee, context) {
+  var length = size(collection);
+
+  if (length < 1) return 0;
+
+  return sum(collection, iteratee, context) / length;
+}

modules/median.js

@@ -0,0 +1,19 @@
+import map from 'underscore/modules/map.js'
+import isEmpty from 'underscore/modules/isEmpty';
+
+// https://en.wikipedia.org/wiki/Median
+// Calulation of median is done using the following method.
+// If the array has odd numbers then median is the middle element.
+// If the array has even numbers then average of middle two numbers is the median value.
+export default function median(collection, iteratee, context) {
+  if (isEmpty(collection)) return undefined;
+
+  if (typeof iteratee == 'number' && collection != null && typeof collection[0] != 'object') {
+    iteratee = null;
+  }
+  var tmpArr = map(collection, iteratee, context).sort();
+
+  return tmpArr.length % 2 ?
+             tmpArr[Math.floor(tmpArr.length / 2)] : 
+                 (tmpArr[tmpArr.length / 2 - 1] + tmpArr[tmpArr.length / 2]) / 2
+}

modules/mode.js

@@ -0,0 +1,16 @@
+import isEmpty from 'underscore/modules/isEmpty';
+import groupBy from 'underscore/modules/groupBy.js';
+import max from 'underscore/modules/max.js';
+import first from 'underscore/modules/first.js';
+
+// Return the element (or element-based computation) that appears most frequently in the collection.
+// https://en.wikipedia.org/wiki/Mode_(statistics)
+export default function mode(collection, iteratee, context) {
+  if (isEmpty(collection)) return;
+
+  if (typeof iteratee == 'number' && collection != null && typeof collection[0] != 'object') {
+    iteratee = null;
+  }
+  var groups = groupBy(collection, iteratee, context);
+  return first(max(groups, 'length'));
+}

modules/percentile.js

@@ -0,0 +1,21 @@
+import isEmpty from 'underscore/modules/isEmpty';
+import sortBy from 'underscore/modules/sortBy.js';
+
+// Return the percentile value of the numeric elements from the collection
+//Ex : 50th,75th,99th etc.
+//https://en.wikipedia.org/wiki/Percentile
+export default function percentile(collection, percentile) {
+  if (isEmpty(collection)) return 0;
+  if (typeof percentile !== 'number') throw new TypeError('Percentile must be a number between 0 - 100');
+  if (percentile <= 0) return collection[0];
+  if (percentile >= 100) return collection[collection.length - 1];
+
+  collection = sortBy(collection);
+  var index = (percentile/100) * (collection.length - 1),
+    lowerIndex = Math.floor(index),
+    upperIndex = lowerIndex + 1,
+    weight = index % 1;
+
+  if (upperIndex >= collection.length) return collection[lowerIndex];
+  return collection[lowerIndex] * (1 - weight) + collection[upperIndex] * weight;
+}

modules/standardDeviation.js

@@ -0,0 +1,7 @@
+import variance from './variance.js';
+
+// Return the standardDeviation based on element-based computation.
+// https://en.wikipedia.org/wiki/Standard_deviation
+export default function standardDeviation(collection, iteratee, context) {
+  return Math.sqrt(variance(collection, iteratee, context));
+}

modules/standardError.js

@@ -0,0 +1,8 @@
+import variance from './variance.js';
+import size from 'underscore/modules/size.js';
+
+// Return the standard error of the mean based on element-based computation.
+// https://en.wikipedia.org/wiki/Standard_error
+export default function standardError(collection, iteratee, context) {
+  return Math.sqrt(variance(collection, iteratee, context) / (size(collection) - 1));
+}

modules/statRange.js

@@ -0,0 +1,6 @@
+import max from 'underscore/modules/max.js';
+import min from 'underscore/modules/min.js';
+
+export default function statRange(collection, iteratee, context){
+    return max(collection, iteratee, context) - min(collection, iteratee, context);
+}

modules/sum.js

@@ -0,0 +1,22 @@
+import isArrayLike from 'underscore/modules/_isArrayLike.js';
+import values from 'underscore/modules/values.js';
+import 'underscore/modules/iteratee.js';
+import _ from 'underscore/modules/underscore.js';
+import find from 'underscore/modules/find.js';
+
+// Return the sum of elements (or element-based computation).
+export default function sum(collection, iteratee, context) {
+  var result = 0;
+  if (iteratee == null || typeof iteratee == 'number'  && collection != null && typeof collection[0] != 'object') {
+    collection = isArrayLike(collection) ? collection : values(collection);
+    for (var i = 0, length = collection.length; i < length; i++) {
+      result += collection[i];
+    }
+  } else {
+    iteratee = _.iteratee(iteratee, context);
+    find(collection, function(v, index, list) {
+      result += iteratee(v, index, list);;
+    });
+  }
+  return result;
+}

modules/variance.js

@@ -0,0 +1,24 @@
+import 'underscore/modules/iteratee.js';
+import _ from 'underscore/modules/underscore.js';
+import mean from './mean.js';
+
+// Return the variance of the numeric elements of the collection,
+// optionally after transforming them through `iteratee`.
+// https://en.wikipedia.org/wiki/Variance
+export default function variance(collection, iteratee, context) {
+  if (typeof iteratee == 'number' && collection != null && typeof collection[0] != 'object') { 
+    iteratee = null;
+  }
+  iteratee = _.iteratee(iteratee, context);
+
+  var computed = [];
+  var avg = mean(collection, function(value, key, collection) {
+    var result = iteratee(value, key, collection);
+    computed.push(result);
+    return result;
+  });
+  return mean(computed, function(value) {
+    var difference = value - avg;
+    return difference * difference;
+  });
+}