std.js (3576B)
1 import { factory } from '../../utils/factory.js'; 2 var name = 'std'; 3 var dependencies = ['typed', 'sqrt', 'variance']; 4 export var createStd = /* #__PURE__ */factory(name, dependencies, _ref => { 5 var { 6 typed, 7 sqrt, 8 variance 9 } = _ref; 10 11 /** 12 * Compute the standard deviation of a matrix or a list with values. 13 * The standard deviations is defined as the square root of the variance: 14 * `std(A) = sqrt(variance(A))`. 15 * In case of a (multi dimensional) array or matrix, the standard deviation 16 * over all elements will be calculated by default, unless an axis is specified 17 * in which case the standard deviation will be computed along that axis. 18 * 19 * Additionally, it is possible to compute the standard deviation along the rows 20 * or columns of a matrix by specifying the dimension as the second argument. 21 * 22 * Optionally, the type of normalization can be specified as the final 23 * parameter. The parameter `normalization` can be one of the following values: 24 * 25 * - 'unbiased' (default) The sum of squared errors is divided by (n - 1) 26 * - 'uncorrected' The sum of squared errors is divided by n 27 * - 'biased' The sum of squared errors is divided by (n + 1) 28 * 29 * 30 * Syntax: 31 * 32 * math.std(a, b, c, ...) 33 * math.std(A) 34 * math.std(A, normalization) 35 * math.std(A, dimension) 36 * math.std(A, dimension, normalization) 37 * 38 * Examples: 39 * 40 * math.std(2, 4, 6) // returns 2 41 * math.std([2, 4, 6, 8]) // returns 2.581988897471611 42 * math.std([2, 4, 6, 8], 'uncorrected') // returns 2.23606797749979 43 * math.std([2, 4, 6, 8], 'biased') // returns 2 44 * 45 * math.std([[1, 2, 3], [4, 5, 6]]) // returns 1.8708286933869707 46 * math.std([[1, 2, 3], [4, 6, 8]], 0) // returns [2.1213203435596424, 2.8284271247461903, 3.5355339059327378] 47 * math.std([[1, 2, 3], [4, 6, 8]], 1) // returns [1, 2] 48 * math.std([[1, 2, 3], [4, 6, 8]], 1, 'biased') // returns [0.7071067811865476, 1.4142135623730951] 49 * 50 * See also: 51 * 52 * mean, median, max, min, prod, sum, variance 53 * 54 * @param {Array | Matrix} array 55 * A single matrix or or multiple scalar values 56 * @param {string} [normalization='unbiased'] 57 * Determines how to normalize the variance. 58 * Choose 'unbiased' (default), 'uncorrected', or 'biased'. 59 * @param dimension {number | BigNumber} 60 * Determines the axis to compute the standard deviation for a matrix 61 * @return {*} The standard deviation 62 */ 63 return typed(name, { 64 // std([a, b, c, d, ...]) 65 'Array | Matrix': _std, 66 // std([a, b, c, d, ...], normalization) 67 'Array | Matrix, string': _std, 68 // std([a, b, c, c, ...], dim) 69 'Array | Matrix, number | BigNumber': _std, 70 // std([a, b, c, c, ...], dim, normalization) 71 'Array | Matrix, number | BigNumber, string': _std, 72 // std(a, b, c, d, ...) 73 '...': function _(args) { 74 return _std(args); 75 } 76 }); 77 78 function _std(array, normalization) { 79 if (array.length === 0) { 80 throw new SyntaxError('Function std requires one or more parameters (0 provided)'); 81 } 82 83 try { 84 return sqrt(variance.apply(null, arguments)); 85 } catch (err) { 86 if (err instanceof TypeError && err.message.indexOf(' variance') !== -1) { 87 throw new TypeError(err.message.replace(' variance', ' std')); 88 } else { 89 throw err; 90 } 91 } 92 } 93 });