main.js (5215B)
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 isPositiveNumber = require( '@stdlib/assert/is-positive-number' ).isPrimitive; 24 var isNumberArray = require( '@stdlib/assert/is-number-array' ).primitives; 25 var isTypedArrayLike = require( '@stdlib/assert/is-typed-array-like' ); 26 var setReadOnly = require( '@stdlib/utils/define-read-only-property' ); 27 var cdfFactory = require( './../../base/dists/normal/cdf' ).factory; 28 var quantileFactory = require( './../../base/dists/normal/quantile' ).factory; 29 var sqrt = require( '@stdlib/math/base/special/sqrt' ); 30 var abs = require( '@stdlib/math/base/special/abs' ); 31 var mean = require( './../../base/mean' ); 32 var NINF = require( '@stdlib/constants/float64/ninf' ); 33 var PINF = require( '@stdlib/constants/float64/pinf' ); 34 var validate = require( './validate.js' ); 35 var print = require( './print.js' ); // eslint-disable-line stdlib/no-redeclare 36 37 38 // VARIABLES // 39 40 var normalCDF = cdfFactory( 0.0, 1.0 ); 41 var normalQuantile = quantileFactory( 0.0, 1.0 ); 42 43 44 // MAIN // 45 46 /** 47 * Computes a one-sample z-test. 48 * 49 * @param {NumericArray} x - data array 50 * @param {PositiveNumber} sigma - known standard deviation 51 * @param {Options} [options] - function options 52 * @param {number} [options.alpha=0.05] - significance level 53 * @param {string} [options.alternative='two-sided'] - alternative hypothesis (`two-sided`, `less` or `greater`) 54 * @param {number} [options.mu=0] - mean under H0 55 * @throws {TypeError} x argument has to be a typed array or array of numbers 56 * @throws {TypeError} sigma argument has to be a positive number 57 * @throws {TypeError} options has to be simple object 58 * @throws {TypeError} alpha option has to be a number primitive 59 * @throws {RangeError} alpha option has to be a number in the interval `[0,1]` 60 * @throws {TypeError} alternative option has to be a string primitive 61 * @throws {Error} alternative option must be `two-sided`, `less` or `greater` 62 * @throws {TypeError} mu option has to be a number primitive 63 * @throws {TypeError} sigma option has to be a positive number 64 * @returns {Object} test result object 65 * 66 * @example 67 * var arr = [ 4, 4, 6, 6, 5 ]; 68 * var out = ztest( arr, 1.0, { 69 * 'mu': 5 70 * }); 71 * 72 * @example 73 * var arr = [ 4, 4, 6, 6, 5 ]; 74 * var out = ztest( arr, 1.0, { 75 * 'alternative': 'greater' 76 * }); 77 */ 78 function ztest( x, sigma, options ) { 79 var stderr; 80 var alpha; 81 var xmean; 82 var cint; 83 var pval; 84 var opts; 85 var stat; 86 var alt; 87 var err; 88 var out; 89 var len; 90 var mu; 91 92 if ( !isTypedArrayLike( x ) && !isNumberArray( x ) ) { 93 throw new TypeError( 'invalid argument. First argument `x` must be a numeric array. Value: `' + x + '`.' ); 94 } 95 if ( !isPositiveNumber( sigma ) ) { 96 throw new TypeError( 'invalid argument. Second argument `sigma` must be a positive number. Value: `' + sigma + '`.' ); 97 } 98 len = x.length; 99 opts = {}; 100 if ( options ) { 101 err = validate( opts, options ); 102 if ( err ) { 103 throw err; 104 } 105 } 106 mu = opts.mu || 0.0; 107 if ( opts.alpha === void 0 ) { 108 alpha = 0.05; 109 } else { 110 alpha = opts.alpha; 111 } 112 if ( alpha < 0.0 || alpha > 1.0 ) { 113 throw new RangeError( 'invalid argument. Option `alpha` must be a number in the range 0 to 1. Value: `' + alpha + '`.' ); 114 } 115 if ( len < 2 ) { 116 throw new Error( 'invalid argument. First argument `x` must contain at least two elements. Value: `' + x + '`' ); 117 } 118 stderr = sqrt( sigma*sigma / len ); 119 xmean = mean( len, x, 1 ); 120 stat = ( xmean - mu ) / stderr; 121 122 alt = opts.alternative || 'two-sided'; 123 switch ( alt ) { 124 case 'two-sided': 125 pval = 2.0 * normalCDF( -abs(stat) ); 126 cint = [ 127 stat - normalQuantile( 1.0-(alpha/2.0) ), 128 stat + normalQuantile( 1.0-(alpha/2.0) ) 129 ]; 130 cint[ 0 ] = mu + (cint[ 0 ] * stderr); 131 cint[ 1 ] = mu + (cint[ 1 ] * stderr); 132 break; 133 case 'greater': 134 pval = 1.0 - normalCDF( stat ); 135 cint = [ stat - normalQuantile( 1.0-alpha ), PINF ]; 136 cint[ 0 ] = mu + (cint[ 0 ] * stderr); 137 break; 138 case 'less': 139 pval = normalCDF( stat ); 140 cint = [ NINF, stat + normalQuantile( 1.0-alpha ) ]; 141 cint[ 1 ] = mu + (cint[ 1 ] * stderr); 142 break; 143 default: 144 throw new Error( 'Invalid option. `alternative` must be either `two-sided`, `less` or `greater`. Value: `' + alt + '`' ); 145 } 146 out = {}; 147 setReadOnly( out, 'rejected', pval <= alpha ); 148 setReadOnly( out, 'alpha', alpha ); 149 setReadOnly( out, 'pValue', pval ); 150 setReadOnly( out, 'statistic', stat ); 151 setReadOnly( out, 'ci', cint ); 152 setReadOnly( out, 'alternative', alt ); 153 setReadOnly( out, 'nullValue', mu ); 154 setReadOnly( out, 'sd', stderr ); 155 setReadOnly( out, 'method', 'One-sample z-test' ); 156 setReadOnly( out, 'print', print ); 157 return out; 158 } 159 160 161 // EXPORTS // 162 163 module.exports = ztest;