simple-squiggle

A restricted subset of Squiggle
Log | Files | Refs | README

std.js (3760B)

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