main.js (4792B)
1 /** 2 * @license Apache-2.0 3 * 4 * Copyright (c) 2018 The Stdlib Authors. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 'use strict'; 20 21 // MODULES // 22 23 var isNumberArray = require( '@stdlib/assert/is-number-array' ).primitives; 24 var isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' ); 25 var setReadOnly = require( '@stdlib/utils/define-read-only-property' ); 26 var fCDF = require( './../../base/dists/f/cdf' ); 27 var fQuantile = require( './../../base/dists/f/quantile' ); 28 var variance = require( './../../base/variance' ); 29 var min = require( '@stdlib/math/base/special/min' ); 30 var PINF = require( '@stdlib/constants/float64/pinf' ); 31 var validate = require( './validate.js' ); 32 var print = require( './print.js' ); // eslint-disable-line stdlib/no-redeclare 33 34 35 // MAIN // 36 37 /** 38 * Computes a two-sample F-test for equal variances. 39 * 40 * @param {NumericArray} x - first data array 41 * @param {NumericArray} y - second data array 42 * @param {Options} [options] - function options 43 * @param {number} [options.alpha=0.05] - significance level 44 * @param {string} [options.alternative='two-sided'] - alternative hypothesis (`two-sided`, `less` or `greater`) 45 * @param {PositiveNumber} [options.ratio=1] - ratio of population variances under H0 46 * @throws {TypeError} x argument has to be a typed array or array of numbers 47 * @throws {TypeError} y argument has to be a typed array or array of numbers 48 * @throws {TypeError} options has to be simple object 49 * @throws {TypeError} alpha option has to be a number primitive 50 * @throws {RangeError} alpha option has to be a number in the interval `[0,1]` 51 * @throws {TypeError} alternative option has to be a string primitive 52 * @throws {Error} alternative option must be `two-sided`, `less` or `greater` 53 * @throws {TypeError} ratio option has to be a number primitive 54 * @returns {Object} test result object 55 * 56 * @example 57 * var x = [ 610, 610, 550, 590, 565, 570 ]; 58 * var y = [ 560, 550, 580, 550, 560, 590, 550, 590 ]; 59 * 60 * var out = vartest( x, y ); 61 */ 62 function vartest( x, y, options ) { 63 var estimate; 64 var alpha; 65 var ratio; 66 var beta; 67 var cint; 68 var opts; 69 var pval; 70 var stat; 71 var xvar; 72 var yvar; 73 var alt; 74 var err; 75 var out; 76 var dfX; 77 var dfY; 78 79 if ( !isTypedArrayLike( x ) && !isNumberArray( x ) ) { 80 throw new TypeError( 'invalid argument. First argument `x` must be a numeric array. Value: `' + x + '`.' ); 81 } 82 if ( !isTypedArrayLike( y ) && !isNumberArray( y ) ) { 83 throw new TypeError( 'invalid argument. Second argument `y` must be a numeric array. Value: `' + y + '`.' ); 84 } 85 opts = {}; 86 if ( options ) { 87 err = validate( opts, options ); 88 if ( err ) { 89 throw err; 90 } 91 } 92 ratio = opts.ratio || 1.0; 93 if ( opts.alpha === void 0 ) { 94 alpha = 0.05; 95 } else { 96 alpha = opts.alpha; 97 } 98 if ( alpha < 0.0 || alpha > 1.0 ) { 99 throw new RangeError( 'invalid argument. Option `alpha` must be a number in the range 0 to 1. Value: `' + alpha + '`.' ); 100 } 101 dfX = x.length - 1; 102 dfY = y.length - 1; 103 104 xvar = variance( x.length, 1, x, 1 ); 105 yvar = variance( y.length, 1, y, 1 ); 106 107 estimate = xvar / yvar; 108 stat = estimate / ratio; 109 pval = fCDF( stat, dfX, dfY ); 110 111 alt = opts.alternative || 'two-sided'; 112 switch ( alt ) { 113 case 'two-sided': 114 pval = 2.0 * min( pval, 1.0 - pval ); 115 beta = alpha / 2.0; 116 cint = [ 117 estimate / fQuantile( 1.0 - beta, dfX, dfY ), 118 estimate / fQuantile( beta, dfX, dfY ) 119 ]; 120 break; 121 case 'greater': 122 pval = 1.0 - pval; 123 cint = [ 124 estimate / fQuantile( 1.0 - alpha, dfX, dfY ), 125 PINF 126 ]; 127 break; 128 case 'less': 129 cint = [ 130 0.0, 131 estimate / fQuantile( alpha, dfX, dfY ) 132 ]; 133 break; 134 default: 135 throw new Error( 'Invalid option. `alternative` must be either `two-sided`, `less` or `greater`. Value: `' + alt + '`' ); 136 } 137 out = {}; 138 setReadOnly( out, 'rejected', pval <= alpha ); 139 setReadOnly( out, 'alpha', alpha ); 140 setReadOnly( out, 'pValue', pval ); 141 setReadOnly( out, 'statistic', stat ); 142 setReadOnly( out, 'ci', cint ); 143 setReadOnly( out, 'alternative', alt ); 144 setReadOnly( out, 'xvar', xvar ); 145 setReadOnly( out, 'yvar', yvar ); 146 setReadOnly( out, 'dfX', dfX ); 147 setReadOnly( out, 'dfY', dfY ); 148 setReadOnly( out, 'method', 'F test for comparing two variances' ); 149 setReadOnly( out, 'nullValue', ratio ); 150 setReadOnly( out, 'print', print ); 151 return out; 152 } 153 154 155 // EXPORTS // 156 157 module.exports = vartest;