@syncfusion/ej2-calculate 35.1.37

package/src/formulas/statistical-ecma.js

@@ -0,0 +1,392 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { FormulasErrorsStrings, CommonErrors } from '../common/index';
+import { isNullOrUndefined } from '@syncfusion/ej2-base';
+import { StatisticalSampleBase } from './statistical-sample-base';
+import { betaDist, betaInv, tCDF, tInv, fCDF } from './formula-math-helpers';
+/**
+ * ECMA-376 statistical distribution and hypothesis-test functions (beta, t, F, frequency).
+ *
+ * Registered functions: BETADIST, BETAINV, TDIST, TINV, TTEST, FTEST, FREQUENCY.
+ *
+ * @hidden
+ */
+var StatisticalEcmaFormulas = /** @class */ (function (_super) {
+    __extends(StatisticalEcmaFormulas, _super);
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    function StatisticalEcmaFormulas(owner) {
+        var _this = _super.call(this, owner) || this;
+        /** Formula definitions registered with {@link BasicFormulas}. */
+        _this.formulas = [
+            { formulaName: 'BETADIST', category: 'Statistical', description: 'Returns the beta cumulative distribution function.' },
+            { formulaName: 'BETAINV', category: 'Statistical', description: 'Returns the inverse of the beta cumulative distribution function.' },
+            { formulaName: 'TDIST', category: 'Statistical', description: 'Returns the Student t-distribution.' },
+            { formulaName: 'TINV', category: 'Statistical', description: 'Returns the inverse of the Student t-distribution.' },
+            { formulaName: 'TTEST', category: 'Statistical', description: 'Returns the probability associated with a Student t-test.' },
+            { formulaName: 'FTEST', category: 'Statistical', description: 'Returns the result of an F-test.' },
+            { formulaName: 'FREQUENCY', category: 'Statistical', description: 'Returns the frequency distribution of a range of values.' }
+        ];
+        return _this;
+    }
+    /**
+     * Returns the beta cumulative distribution function.
+     *
+     * Excel: `BETADIST(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=BETADIST(1)');
+     * ```
+     */
+    StatisticalEcmaFormulas.prototype.ComputeBETADIST = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 3 || args.length > 5) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var x = this.resolveNumberArg(args[0]);
+        var alpha = this.resolveNumberArg(args[1]);
+        var betaParam = this.resolveNumberArg(args[2]);
+        if (typeof x === 'string') {
+            return x;
+        }
+        if (typeof alpha === 'string') {
+            return alpha;
+        }
+        if (typeof betaParam === 'string') {
+            return betaParam;
+        }
+        var a = 0;
+        var b = 1;
+        if (args.length >= 4 && args[3] !== '') {
+            var av = this.resolveNumberArg(args[3]);
+            if (typeof av === 'string') {
+                return av;
+            }
+            a = av;
+        }
+        if (args.length >= 5 && args[4] !== '') {
+            var bv = this.resolveNumberArg(args[4]);
+            if (typeof bv === 'string') {
+                return bv;
+            }
+            b = bv;
+        }
+        if (x < a || x > b || alpha <= 0 || betaParam <= 0 || a >= b) {
+            return errCollection[CommonErrors.Num];
+        }
+        var scaled = (x - a) / (b - a);
+        var result = betaDist(scaled, alpha, betaParam);
+        if (isNaN(result)) {
+            return errCollection[CommonErrors.Num];
+        }
+        return result.toString();
+    };
+    /**
+     * Returns the inverse of the beta cumulative distribution function.
+     *
+     * Excel: `BETAINV(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeBETAINV = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 3 || args.length > 5) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var p = this.resolveNumberArg(args[0]);
+        var alpha = this.resolveNumberArg(args[1]);
+        var betaParam = this.resolveNumberArg(args[2]);
+        if (typeof p === 'string') {
+            return p;
+        }
+        if (typeof alpha === 'string') {
+            return alpha;
+        }
+        if (typeof betaParam === 'string') {
+            return betaParam;
+        }
+        var a = 0;
+        var b = 1;
+        if (args.length >= 4 && args[3] !== '') {
+            var av = this.resolveNumberArg(args[3]);
+            if (typeof av === 'string') {
+                return av;
+            }
+            a = av;
+        }
+        if (args.length >= 5 && args[4] !== '') {
+            var bv = this.resolveNumberArg(args[4]);
+            if (typeof bv === 'string') {
+                return bv;
+            }
+            b = bv;
+        }
+        var scaled = betaInv(p, alpha, betaParam);
+        if (isNaN(scaled)) {
+            return errCollection[CommonErrors.Num];
+        }
+        return (a + scaled * (b - a)).toString();
+    };
+    /**
+     * Returns the Student t-distribution.
+     *
+     * Excel: `TDIST(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeTDIST = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var x = this.resolveNumberArg(args[0]);
+        var df = this.resolveNumberArg(args[1]);
+        if (typeof x === 'string') {
+            return x;
+        }
+        if (typeof df === 'string') {
+            return df;
+        }
+        var tails = 1;
+        if (args.length === 3 && args[2] !== '') {
+            var t = this.resolveNumberArg(args[2]);
+            if (typeof t === 'string') {
+                return t;
+            }
+            tails = Math.floor(t);
+        }
+        var cdf = tCDF(Math.abs(x), df);
+        var p = tails === 1 ? 1 - cdf : 2 * (1 - cdf);
+        return p.toString();
+    };
+    /**
+     * Returns the inverse of the Student t-distribution.
+     *
+     * Excel: `TINV(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeTINV = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var p = this.resolveNumberArg(args[0]);
+        var df = this.resolveNumberArg(args[1]);
+        if (typeof p === 'string') {
+            return p;
+        }
+        if (typeof df === 'string') {
+            return df;
+        }
+        var tails = 2;
+        if (args.length === 3 && args[2] !== '') {
+            var t = this.resolveNumberArg(args[2]);
+            if (typeof t === 'string') {
+                return t;
+            }
+            tails = Math.floor(t);
+        }
+        var prob = tails === 1 ? 1 - p : 1 - p / 2;
+        var result = tInv(prob, df);
+        if (isNaN(result)) {
+            return errCollection[CommonErrors.Num];
+        }
+        return result.toString();
+    };
+    /**
+     * Returns the probability associated with a Student t-test.
+     *
+     * Excel: `TTEST(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeTTEST = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 3 || args.length > 4) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var a = this.collectSample([args[0]], false);
+        var b = this.collectSample([args[1]], false);
+        if (typeof a === 'string') {
+            return a;
+        }
+        if (typeof b === 'string') {
+            return b;
+        }
+        if (a.length < 2 || b.length < 2) {
+            return errCollection[CommonErrors.DivZero];
+        }
+        var meanA = this.mean(a);
+        var meanB = this.mean(b);
+        var varA = 0;
+        var varB = 0;
+        for (var i = 0; i < a.length; i++) {
+            varA += Math.pow(a[i] - meanA, 2);
+        }
+        for (var i = 0; i < b.length; i++) {
+            varB += Math.pow(b[i] - meanB, 2);
+        }
+        varA /= (a.length - 1);
+        varB /= (b.length - 1);
+        var se = Math.sqrt(varA / a.length + varB / b.length);
+        if (se === 0) {
+            return errCollection[CommonErrors.DivZero];
+        }
+        var t = Math.abs(meanA - meanB) / se;
+        var df = a.length + b.length - 2;
+        var tails = 2;
+        if (args.length === 4 && args[3] !== '') {
+            var tt = this.resolveNumberArg(args[3]);
+            if (typeof tt === 'string') {
+                return tt;
+            }
+            tails = Math.floor(tt);
+        }
+        var cdf = tCDF(t, df);
+        var p = tails === 1 ? 1 - cdf : 2 * (1 - cdf);
+        return p.toString();
+    };
+    /**
+     * Returns the result of an F-test.
+     *
+     * Excel: `FTEST(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeFTEST = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length !== 2) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var a = this.collectSample([args[0]], false);
+        var b = this.collectSample([args[1]], false);
+        if (typeof a === 'string') {
+            return a;
+        }
+        if (typeof b === 'string') {
+            return b;
+        }
+        if (a.length < 2 || b.length < 2) {
+            return errCollection[CommonErrors.DivZero];
+        }
+        var varA = this.sampleVar(a);
+        var varB = this.sampleVar(b);
+        if (varB === 0) {
+            return errCollection[CommonErrors.DivZero];
+        }
+        var f = varA / varB;
+        var d1 = a.length - 1;
+        var d2 = b.length - 1;
+        return (2 * Math.min(fCDF(f, d1, d2), fCDF(1 / f, d2, d1))).toString();
+    };
+    StatisticalEcmaFormulas.prototype.sampleVar = function (nums) {
+        var m = this.mean(nums);
+        var sum = 0;
+        for (var i = 0; i < nums.length; i++) {
+            sum += Math.pow(nums[i] - m, 2);
+        }
+        return sum / (nums.length - 1);
+    };
+    /**
+     * Returns a frequency distribution as a vertical array (first bin when spill unavailable).
+     *
+     * Excel: `FREQUENCY(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    StatisticalEcmaFormulas.prototype.ComputeFREQUENCY = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length !== 2) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var data = this.collectSample([args[0]], false);
+        var bins = this.collectSample([args[1]], false);
+        if (typeof data === 'string') {
+            return data;
+        }
+        if (typeof bins === 'string') {
+            return bins;
+        }
+        if (bins.length === 0) {
+            return errCollection[CommonErrors.Num];
+        }
+        var sortedBins = bins.slice().sort(function (x, y) { return x - y; });
+        var counts = new Array(sortedBins.length + 1).fill(0);
+        for (var i = 0; i < data.length; i++) {
+            var v = data[i];
+            var placed = false;
+            for (var b = 0; b < sortedBins.length; b++) {
+                if (v <= sortedBins[b]) {
+                    counts[b]++;
+                    placed = true;
+                    break;
+                }
+            }
+            if (!placed) {
+                counts[counts.length - 1]++;
+            }
+        }
+        var sep = this.parent.getParseArgumentSeparator();
+        return counts.join(sep);
+    };
+    return StatisticalEcmaFormulas;
+}(StatisticalSampleBase));
+export { StatisticalEcmaFormulas };

package/src/formulas/statistical-extended.d.ts

@@ -0,0 +1,136 @@
+import { IBasicFormula } from '../common/index';
+import { FormulaOwner } from './formula-owner';
+import { StatisticalSampleBase } from './statistical-sample-base';
+/**
+ * Large-sample and array statistical helpers beyond basic descriptive functions.
+ *
+ * Registers 11 functions including STDEVA, STDEVPA, VARA, VARPA, TRIMMEAN, and others.
+ *
+ * @hidden
+ */
+export declare class StatisticalExtendedFormulas extends StatisticalSampleBase {
+    /** Formula definitions registered with {@link BasicFormulas}. */
+    formulas: IBasicFormula[];
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    constructor(owner: FormulaOwner);
+    private stdevVarA;
+    /**
+     * Estimates standard deviation based on a sample, including text and logicals.
+     *
+     * Excel: `STDEVA(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=STDEVA(1)');
+     * ```
+     */
+    ComputeSTDEVA(...args: string[]): string | number;
+    /**
+     * Calculates standard deviation based on the entire population, including text and logicals.
+     *
+     * Excel: `STDEVPA(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeSTDEVPA(...args: string[]): string | number;
+    /**
+     * Estimates variance based on a sample, including text and logicals.
+     *
+     * Excel: `VARA(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeVARA(...args: string[]): string | number;
+    /**
+     * Calculates variance based on the entire population, including text and logicals.
+     *
+     * Excel: `VARPA(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeVARPA(...args: string[]): string | number;
+    /**
+     * Returns the mean of the interior of a data set.
+     *
+     * Excel: `TRIMMEAN(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeTRIMMEAN(...args: string[]): string | number;
+    /**
+     * Returns the Fisher transformation.
+     *
+     * Excel: `FISHER(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeFISHER(...args: string[]): string | number;
+    /**
+     * Returns the inverse of the Fisher transformation.
+     *
+     * Excel: `FISHERINV(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeFISHERINV(...args: string[]): string | number;
+    /**
+     * Returns the natural logarithm of the gamma function.
+     *
+     * Excel: `GAMMALN(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeGAMMALN(...args: string[]): string | number;
+    private sumSquaresPair;
+    /**
+     * Returns the sum of the difference of squares of corresponding values in two arrays.
+     *
+     * Excel: `SUMX2MY2(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeSUMX2MY2(...args: string[]): string | number;
+    /**
+     * Returns the sum of the sum of squares of corresponding values in two arrays.
+     *
+     * Excel: `SUMX2PY2(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeSUMX2PY2(...args: string[]): string | number;
+    /**
+     * Returns the sum of squares of differences of corresponding values in two arrays.
+     *
+     * Excel: `SUMXMY2(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeSUMXMY2(...args: string[]): string | number;
+}