diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/README.md b/lib/node_modules/@stdlib/stats/strided/dttest/README.md new file mode 100644 index 000000000000..fd1966420110 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/README.md @@ -0,0 +1,220 @@ + + + + +# dttest + +> Compute a one-sample Student's t-test for a double-precision floating-point strided array. + +
+ +A one-sample t-test compares the mean of a set of measurements `X` to a given constant `μ0` when the population standard deviation is **unknown** and must be estimated from the data. Under the null hypothesis, the test statistic + +``` +t = (x̄ - μ0) / (s / √N) +``` + +follows a Student's t-distribution with `N - 1` degrees of freedom, where `x̄` is the sample mean and `s` is the sample standard deviation. + +The test supports three null hypotheses `H0`: + +- `H0: μ ≥ μ0` versus the alternative hypothesis `H1: μ < μ0`. +- `H0: μ ≤ μ0` versus the alternative hypothesis `H1: μ > μ0`. +- `H0: μ = μ0` versus the alternative hypothesis `H1: μ ≠ μ0`. + +
+ + + +
+ +## Usage + +```javascript +var dttest = require( '@stdlib/stats/strided/dttest' ); +``` + +#### dttest( N, alternative, alpha, mu, x, strideX, out ) + +Computes a one-sample Student's t-test for a double-precision floating-point strided array. + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + +var out = {}; +var results = dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); +// returns {...} + +var bool = ( results === out ); +// returns true +``` + +The function has the following parameters: + +- **N**: number of indexed elements. Must be greater than `1`. +- **alternative**: alternative hypothesis. Must be one of `'two-sided'`, `'greater'`, or `'less'`. +- **alpha**: significance level in `[0,1]`. +- **mu**: mean value under the null hypothesis. +- **x**: input [`Float64Array`][@stdlib/array/float64]. +- **strideX**: stride length for `x`. +- **out**: output results object. On return, the object will have the following properties: + - **rejected**: boolean indicating whether the null hypothesis was rejected. + - **alternative**: the alternative hypothesis string. + - **alpha**: significance level. + - **pValue**: p-value of the test. + - **statistic**: value of the t-statistic. + - **ci**: two-element array containing the confidence interval bounds. + - **df**: degrees of freedom (`N - 1`). + - **nullValue**: mean under the null hypothesis. + - **mean**: sample mean. + - **sd**: standard error of the mean. + +The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to perform a one-sample t-test over every other element in `x`, + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var x = new Float64Array( [ 4.0, 0.0, 4.0, 0.0, 6.0, 0.0, 6.0, 0.0, 5.0, 0.0 ] ); + +var out = {}; +var results = dttest( 5, 'two-sided', 0.05, 5.0, x, 2, out ); +// returns {...} +``` + +Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +// Initial two elements are excluded from computation: +var x0 = new Float64Array( [ 0.0, 0.0, 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT * 2 ); + +var out = {}; +var results = dttest( 5, 'two-sided', 0.05, 5.0, x1, 1, out ); +// returns {...} +``` + +#### dttest.ndarray( N, alternative, alpha, mu, x, strideX, offsetX, out ) + +Computes a one-sample Student's t-test for a double-precision floating-point strided array using alternative indexing semantics. + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + +var out = {}; +var results = dttest.ndarray( x.length, 'two-sided', 0.05, 5.0, x, 1, 0, out ); +// returns {...} + +var bool = ( results === out ); +// returns true +``` + +The function has the following additional parameters: + +- **offsetX**: starting index for `x`. + +While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the `offsetX` parameter supports indexing semantics based on a starting index. For example, to perform a one-sample t-test starting from the third element, + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); + +var x = new Float64Array( [ 0.0, 0.0, 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + +var out = {}; +var results = dttest.ndarray( 5, 'two-sided', 0.05, 5.0, x, 1, 2, out ); +// returns {...} +``` + +
+ + + +
+ +## Notes + +- If `N <= 1`, the function returns an object with all numeric fields set to `NaN` and `rejected` set to `false`. +- If `alpha` is not in the interval `[0,1]` or is `NaN`, the function returns an object with all numeric fields set to `NaN`. +- Unlike the z-test, the t-test does **not** require a known population standard deviation. The standard deviation is estimated from the data, and the degrees of freedom are `N - 1`. +- The confidence interval is computed using the t-distribution quantile corresponding to the chosen `alpha` and `alternative`. + +
+ + + +
+ +## Examples + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); +var dttest = require( '@stdlib/stats/strided/dttest' ); + +// Simulate data drawn from N(5, 1): +var x = new Float64Array( [ 4.2, 5.1, 4.8, 5.5, 4.9, 5.3, 4.7, 5.0, 5.2, 4.6 ] ); + +// Two-sided test: is the mean equal to 5? +var out = {}; +dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); +console.log( 'statistic: %d', out.statistic ); +console.log( 'p-value: %d', out.pValue ); +console.log( 'ci: [%d, %d]', out.ci[ 0 ], out.ci[ 1 ] ); +console.log( 'rejected: %s', out.rejected ); + +// One-sided test: is the mean greater than 4? +dttest( x.length, 'greater', 0.05, 4.0, x, 1, out ); +console.log( '\ngreater-than test (mu=4):' ); +console.log( 'p-value: %d', out.pValue ); +console.log( 'rejected: %s', out.rejected ); +``` + +
+ + + + + + + + + +[@stdlib/array/float64]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/float64 + +[@stdlib/stats/strided/dztest]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/strided/dztest + +[@stdlib/stats/strided/sttest]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/strided/sttest + +[@stdlib/stats/ttest]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/ttest + +[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/benchmark/benchmark.js b/lib/node_modules/@stdlib/stats/strided/dttest/benchmark/benchmark.js new file mode 100644 index 000000000000..4c11e2d0db4d --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/benchmark/benchmark.js @@ -0,0 +1,90 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var uniform = require( '@stdlib/random/base/uniform' ).factory; +var isObject = require( '@stdlib/assert/is-plain-object' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var Float64Array = require( '@stdlib/array/float64' ); +var pkg = require( './../package.json' ).name; +var dttest = require( './../lib' ); + + +// VARIABLES // + +var rand = uniform( -10.0, 10.0 ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x; + var i; + + x = new Float64Array( len ); + for ( i = 0; i < len; i++ ) { + x[ i ] = rand(); + } + return benchmark; + + function benchmark( b ) { + var out; + var i; + + out = {}; + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + dttest( len, 'two-sided', 0.05, 0.0, x, 1, out ); + if ( typeof out.pValue !== 'number' ) { + b.fail( 'should return a number' ); + } + } + b.toc(); + if ( !isObject( out ) ) { + b.fail( 'should return an object' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +var MIN = 1; +var MAX = 6; +var len; +var f; +var i; + +for ( i = MIN; i <= MAX; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg + ':len=' + len, f ); +} diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/docs/repl.txt b/lib/node_modules/@stdlib/stats/strided/dttest/docs/repl.txt new file mode 100644 index 000000000000..4094df3be1d0 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/docs/repl.txt @@ -0,0 +1,123 @@ + +{{alias}}( N, alternative, alpha, mu, x, strideX, out ) + Computes a one-sample Student's t-test for a double-precision floating-point + strided array. + + The `N` and stride parameters determine which elements in the strided array + are accessed at runtime. + + Indexing is relative to the first index. To introduce an offset, use a typed + array view. + + Parameters + ---------- + N: integer + Number of indexed elements. Must be greater than 1. + + alternative: string + Alternative hypothesis. Must be one of the following: + + - two-sided: mean is not equal to null value. + - greater: mean is larger than null value. + - less: mean is less than null value. + + alpha: number + Significance level in the interval [0,1]. + + mu: number + Value of the mean under the null hypothesis. + + x: Float64Array + Input array. + + strideX: integer + Stride length. + + out: Object + Output results object. Will be populated with the following fields: + + - rejected: boolean indicating whether the null hypothesis was rejected. + - alternative: the alternative hypothesis. + - alpha: significance level. + - pValue: p-value of the test. + - statistic: value of the t-statistic. + - ci: two-element array containing the confidence interval. + - df: degrees of freedom (N-1). + - nullValue: mean under the null hypothesis. + - mean: sample mean. + - sd: standard error of the mean. + + Returns + ------- + out: Object + Results object. + + Examples + -------- + > var x = new {{alias:@stdlib/array/float64}}( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + > var out = {}; + > var res = {{alias}}( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); + > res.pValue + 1.0 + > res.statistic + 0.0 + > res.rejected + false + + +{{alias}}.ndarray( N, alternative, alpha, mu, x, strideX, offsetX, out ) + Computes a one-sample Student's t-test for a double-precision floating-point + strided array using alternative indexing semantics. + + While typed array views mandate a view offset based on the underlying + buffer, the offset parameter supports indexing semantics based on a starting + index. + + Parameters + ---------- + N: integer + Number of indexed elements. Must be greater than 1. + + alternative: string + Alternative hypothesis. Must be one of the following: + + - two-sided: mean is not equal to null value. + - greater: mean is larger than null value. + - less: mean is less than null value. + + alpha: number + Significance level in the interval [0,1]. + + mu: number + Value of the mean under the null hypothesis. + + x: Float64Array + Input array. + + strideX: integer + Stride length. + + offsetX: integer + Starting index. + + out: Object + Output results object. + + Returns + ------- + out: Object + Results object. + + Examples + -------- + > var x = new {{alias:@stdlib/array/float64}}( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + > var out = {}; + > var res = {{alias}}.ndarray( x.length, 'two-sided', 0.05, 5.0, x, 1, 0, out ); + > res.pValue + 1.0 + > res.statistic + 0.0 + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/docs/types/index.d.ts b/lib/node_modules/@stdlib/stats/strided/dttest/docs/types/index.d.ts new file mode 100644 index 000000000000..e7bc1fd52faa --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/docs/types/index.d.ts @@ -0,0 +1,180 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +// TypeScript Version: 4.1 + +/** +* Alternative hypothesis. +*/ +type Alternative = 'two-sided' | 'greater' | 'less'; + +/** +* Interface describing a "base" results object. +*/ +interface BaseResults { + /** + * Boolean indicating whether the null hypothesis was rejected. + */ + rejected: boolean; + + /** + * Alternative hypothesis. + */ + alternative: Alternative; + + /** + * Significance level. + */ + alpha: number; + + /** + * p-value. + */ + pValue: number; + + /** + * Test statistic (t-score). + */ + statistic: number; + + /** + * Confidence interval (two-element array). + */ + ci: Float64Array; + + /** + * Degrees of freedom (N-1). + */ + df: number; + + /** + * Value of the mean under the null hypothesis. + */ + nullValue: number; + + /** + * Sample mean. + */ + mean: number; + + /** + * Standard error of the mean. + */ + sd: number; +} + +/** +* Interface describing `dttest`. +*/ +interface Routine { + /** + * Computes a one-sample Student's t-test for a double-precision floating-point strided array. + * + * @param N - number of indexed elements + * @param alternative - alternative hypothesis + * @param alpha - significance level + * @param mu - mean under the null hypothesis + * @param x - input array + * @param strideX - stride length + * @param out - output results object + * @returns results object + * + * @example + * var Float64Array = require( '@stdlib/array/float64' ); + * + * var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + * + * var out = {}; + * var results = dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); + * // returns {...} + * + * var bool = ( results === out ); + * // returns true + */ + ( N: number, alternative: Alternative, alpha: number, mu: number, x: Float64Array, strideX: number, out: T ): T; + + /** + * Computes a one-sample Student's t-test for a double-precision floating-point strided array using alternative indexing semantics. + * + * @param N - number of indexed elements + * @param alternative - alternative hypothesis + * @param alpha - significance level + * @param mu - mean under the null hypothesis + * @param x - input array + * @param strideX - stride length + * @param offsetX - starting index + * @param out - output results object + * @returns results object + * + * @example + * var Float64Array = require( '@stdlib/array/float64' ); + * + * var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + * + * var out = {}; + * var results = dttest.ndarray( x.length, 'two-sided', 0.05, 5.0, x, 1, 0, out ); + * // returns {...} + * + * var bool = ( results === out ); + * // returns true + */ + ndarray( N: number, alternative: Alternative, alpha: number, mu: number, x: Float64Array, strideX: number, offsetX: number, out: T ): T; +} + +/** +* Computes a one-sample Student's t-test for a double-precision floating-point strided array. +* +* @param N - number of indexed elements +* @param alternative - alternative hypothesis +* @param alpha - significance level +* @param mu - mean under the null hypothesis +* @param x - input array +* @param strideX - stride length +* @param out - output results object +* @returns results object +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest.ndarray( x.length, 'two-sided', 0.05, 5.0, x, 1, 0, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +*/ +declare var dttest: Routine; + + +// EXPORTS // + +export = dttest; diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/examples/index.js b/lib/node_modules/@stdlib/stats/strided/dttest/examples/index.js new file mode 100644 index 000000000000..75a965ac453f --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/examples/index.js @@ -0,0 +1,59 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +var Float64Array = require( '@stdlib/array/float64' ); +var dttest = require( './../lib' ); + +// Example 1: Two-sided one-sample t-test +var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +var out = {}; +dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); +console.log( 'Two-sided test (mu=5):' ); +console.log( ' statistic: %d', out.statistic ); +console.log( ' p-value: %d', out.pValue ); +console.log( ' df: %d', out.df ); +console.log( ' rejected: %s', out.rejected ); +console.log( ' ci: [%d, %d]', out.ci[ 0 ], out.ci[ 1 ] ); + +// Example 2: One-sided test (greater) +var y = new Float64Array( [ 2.5, 3.0, 3.5, 4.0, 4.5, 5.0 ] ); +out = {}; +dttest( y.length, 'greater', 0.05, 3.0, y, 1, out ); +console.log( '\nGreater-than test (mu=3):' ); +console.log( ' statistic: %d', out.statistic ); +console.log( ' p-value: %d', out.pValue ); +console.log( ' rejected: %s', out.rejected ); + +// Example 3: Non-unit stride (every other element) +var z = new Float64Array( [ 1.0, 0.0, 2.0, 0.0, 3.0, 0.0, 4.0, 0.0, 5.0, 0.0 ] ); +out = {}; +dttest( 5, 'two-sided', 0.05, 0.0, z, 2, out ); +console.log( '\nNon-unit stride (stride=2, picks [1,2,3,4,5]):' ); +console.log( ' mean: %d', out.mean ); +console.log( ' statistic: %d', out.statistic ); +console.log( ' p-value: %d', out.pValue ); + +// Example 4: ndarray interface with offset +var w = new Float64Array( [ 0.0, 0.0, 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +out = {}; +dttest.ndarray( 5, 'two-sided', 0.05, 0.0, w, 1, 2, out ); +console.log( '\nndarray interface (offset=2, reads [4,4,6,6,5]):' ); +console.log( ' mean: %d', out.mean ); +console.log( ' statistic: %d', out.statistic ); diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/lib/dttest.js b/lib/node_modules/@stdlib/stats/strided/dttest/lib/dttest.js new file mode 100644 index 000000000000..1edb5ed2da9f --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/lib/dttest.js @@ -0,0 +1,60 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var stride2offset = require( '@stdlib/strided/base/stride2offset' ); +var ndarray = require( './ndarray.js' ); + + +// MAIN // + +/** +* Computes a one-sample Student's t-test for a double-precision floating-point strided array. +* +* @param {PositiveInteger} N - number of indexed elements +* @param {(integer|string)} alternative - alternative hypothesis +* @param {number} alpha - significance level +* @param {number} mu - mean under the null hypothesis +* @param {Float64Array} x - input array +* @param {integer} strideX - stride length +* @param {Object} out - output results object +* @returns {Object} results object +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +*/ +function dttest( N, alternative, alpha, mu, x, strideX, out ) { + return ndarray( N, alternative, alpha, mu, x, strideX, stride2offset( N, strideX ), out ); +} + + +// EXPORTS // + +module.exports = dttest; diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/lib/index.js b/lib/node_modules/@stdlib/stats/strided/dttest/lib/index.js new file mode 100644 index 000000000000..e57676d4fa96 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/lib/index.js @@ -0,0 +1,76 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/** +* Compute a one-sample Student's t-test for a double-precision floating-point strided array. +* +* @module @stdlib/stats/strided/dttest +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var dttest = require( '@stdlib/stats/strided/dttest' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* var dttest = require( '@stdlib/stats/strided/dttest' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest.ndarray( x.length, 'two-sided', 0.05, 0.0, x, 1, 0, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +*/ + +// MODULES // + +var join = require( 'path' ).join; +var tryRequire = require( '@stdlib/utils/try-require' ); +var isError = require( '@stdlib/assert/is-error' ); +var main = require( './main.js' ); + + +// MAIN // + +var dttest; +var tmp = tryRequire( join( __dirname, './native.js' ) ); +if ( isError( tmp ) ) { + dttest = main; +} else { + dttest = tmp; +} + + +// EXPORTS // + +module.exports = dttest; + +// exports: { "ndarray": "dttest.ndarray" } diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/lib/main.js b/lib/node_modules/@stdlib/stats/strided/dttest/lib/main.js new file mode 100644 index 000000000000..a7c668e03ea2 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/lib/main.js @@ -0,0 +1,35 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var dttest = require( './dttest.js' ); +var ndarray = require( './ndarray.js' ); + + +// MAIN // + +setReadOnly( dttest, 'ndarray', ndarray ); + + +// EXPORTS // + +module.exports = dttest; diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/lib/ndarray.js b/lib/node_modules/@stdlib/stats/strided/dttest/lib/ndarray.js new file mode 100644 index 000000000000..4dfbcf18d69e --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/lib/ndarray.js @@ -0,0 +1,152 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var resolveStr = require( '@stdlib/stats/base/ztest/alternative-resolve-str' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var tCDF = require( '@stdlib/stats/base/dists/t/cdf' ); +var tQuantile = require( '@stdlib/stats/base/dists/t/quantile' ); +var dmeanvar = require( '@stdlib/stats/strided/dmeanvar' ).ndarray; +var sqrt = require( '@stdlib/math/base/special/sqrt' ); +var abs = require( '@stdlib/math/base/special/abs' ); +var Float64Array = require( '@stdlib/array/float64' ); +var PINF = require( '@stdlib/constants/float64/pinf' ); +var NINF = require( '@stdlib/constants/float64/ninf' ); + + +// VARIABLES // + +// Workspace for mean and variance output from dmeanvar: +var MV_WORKSPACE = new Float64Array( 2 ); + +// Workspace for storing confidence intervals: +var CI_WORKSPACE = new Float64Array( 2 ); + + +// MAIN // + +/** +* Computes a one-sample Student's t-test for a double-precision floating-point strided array using alternative indexing semantics. +* +* @param {PositiveInteger} N - number of indexed elements +* @param {(integer|string)} alternative - alternative hypothesis +* @param {number} alpha - significance level +* @param {number} mu - mean under the null hypothesis +* @param {Float64Array} x - input array +* @param {integer} strideX - stride length +* @param {NonNegativeInteger} offsetX - starting index +* @param {Object} out - output results object +* @returns {Object} results object +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); +* +* var out = {}; +* var results = dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, 0, out ); +* // returns {...} +* +* var bool = ( results === out ); +* // returns true +*/ +function dttest( N, alternative, alpha, mu, x, strideX, offsetX, out ) { + var pValue; + var stderr; + var xmean; + var xvar; + var stat; + var alt; + var df; + var tq; + + alt = resolveStr( alternative ); + if ( + N <= 1 || + isnan( alpha ) || + isnan( mu ) || + alpha < 0.0 || + alpha > 1.0 || + alt === null + ) { + CI_WORKSPACE[ 0 ] = NaN; + CI_WORKSPACE[ 1 ] = NaN; + out.rejected = false; + out.alternative = alt; + out.alpha = NaN; + out.pValue = NaN; + out.statistic = NaN; + out.ci = CI_WORKSPACE; + out.df = NaN; + out.nullValue = NaN; + out.mean = NaN; + out.sd = NaN; + return out; + } + // Compute the mean and variance in a single pass: + dmeanvar( N, 1, x, strideX, offsetX, MV_WORKSPACE, 1, 0 ); + xmean = MV_WORKSPACE[ 0 ]; + xvar = MV_WORKSPACE[ 1 ]; + + // Degrees of freedom: + df = N - 1; + + // Standard error of the mean: + stderr = sqrt( xvar / N ); + + // Compute the test statistic: + stat = ( xmean - mu ) / stderr; + + // Compute p-value and confidence interval: + if ( alt === 'less' ) { + pValue = tCDF( stat, df ); + tq = tQuantile( 1.0 - alpha, df ); + CI_WORKSPACE[ 0 ] = NINF; + CI_WORKSPACE[ 1 ] = mu + ( (stat + tq) * stderr ); + } else if ( alt === 'greater' ) { + pValue = 1.0 - tCDF( stat, df ); + tq = tQuantile( 1.0 - alpha, df ); + CI_WORKSPACE[ 0 ] = mu + ( (stat - tq) * stderr ); + CI_WORKSPACE[ 1 ] = PINF; + } else { // 'two-sided' + pValue = 2.0 * tCDF( -abs( stat ), df ); + tq = tQuantile( 1.0 - (alpha / 2.0), df ); + CI_WORKSPACE[ 0 ] = mu + ( (stat - tq) * stderr ); + CI_WORKSPACE[ 1 ] = mu + ( (stat + tq) * stderr ); + } + // Return test results: + out.rejected = ( pValue <= alpha ); + out.alternative = alt; + out.alpha = alpha; + out.pValue = pValue; + out.statistic = stat; + out.ci = CI_WORKSPACE; + out.df = df; + out.nullValue = mu; + out.mean = xmean; + out.sd = stderr; + return out; +} + + +// EXPORTS // + +module.exports = dttest; diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/package.json b/lib/node_modules/@stdlib/stats/strided/dttest/package.json new file mode 100644 index 000000000000..2e827eb140cb --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/package.json @@ -0,0 +1,73 @@ +{ + "name": "@stdlib/stats/strided/dttest", + "version": "0.0.0", + "description": "Compute a one-sample Student's t-test for a double-precision floating-point strided array.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "browser": "./lib/main.js", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdmath", + "statistics", + "stats", + "mathematics", + "math", + "strided", + "strided array", + "typed", + "array", + "float64", + "double", + "float64array", + "ttest", + "t-test", + "student", + "hypothesis", + "testing" + ], + "__stdlib__": {} +} diff --git a/lib/node_modules/@stdlib/stats/strided/dttest/test/test.js b/lib/node_modules/@stdlib/stats/strided/dttest/test/test.js new file mode 100644 index 000000000000..cb402c7d7123 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/strided/dttest/test/test.js @@ -0,0 +1,216 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2025 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var abs = require( '@stdlib/math/base/special/abs' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var Float64Array = require( '@stdlib/array/float64' ); +var PINF = require( '@stdlib/constants/float64/pinf' ); +var NINF = require( '@stdlib/constants/float64/ninf' ); +var dttest = require( './../lib' ); + + +// VARIABLES // + +var EPS = 1.0e-7; // tolerance for floating-point comparisons + + +// FUNCTIONS // + +/** +* Returns true if two numbers are approximately equal. +* +* @private +* @param {number} a - first number +* @param {number} b - second number +* @param {number} [tol] - tolerance +* @returns {boolean} boolean indicating whether numbers are approximately equal +*/ +function approxEqual( a, b, tol ) { + if ( tol === void 0 ) { + tol = EPS; + } + if ( a === b ) { + return true; + } + return abs( a - b ) <= tol * Math.max( 1.0, abs( a ), abs( b ) ); +} + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof dttest, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached `ndarray` method is a function', function test( t ) { + t.strictEqual( typeof dttest.ndarray, 'function', 'ndarray export is a function' ); + t.end(); +}); + +tape( 'the function returns the output object', function test( t ) { + var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + var out = {}; + var res = dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, out ); + t.strictEqual( res, out, 'returns output object' ); + t.end(); +}); + +tape( 'two-sided test: known values (mu=0, alpha=0.05)', function test( t ) { + // Reference: R ttest result for c(4,4,6,6,5), mu=0, two-sided + // t.test(c(4,4,6,6,5), mu=0) => t=11.180, df=4, p-value=0.000369 + var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + var out = {}; + dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, out ); + + t.strictEqual( out.df, 4, 'degrees of freedom = 4' ); + t.ok( approxEqual( out.statistic, 11.180339887, 1e-6 ), 'statistic ≈ 11.180' ); + t.ok( approxEqual( out.pValue, 0.000369, 1e-3 ), 'pValue ≈ 0.000369' ); + t.ok( approxEqual( out.mean, 5.0, 1e-10 ), 'mean = 5.0' ); + t.strictEqual( out.rejected, true, 'null hypothesis rejected' ); + t.strictEqual( out.alternative, 'two-sided', 'alternative = two-sided' ); + t.strictEqual( out.nullValue, 0.0, 'nullValue = 0.0' ); + t.end(); +}); + +tape( 'two-sided test: fail to reject when mu equals sample mean', function test( t ) { + // t.test(c(4,4,6,6,5), mu=5) => t=0, p-value=1 + var x = new Float64Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] ); + var out = {}; + dttest( x.length, 'two-sided', 0.05, 5.0, x, 1, out ); + + t.ok( approxEqual( out.statistic, 0.0, 1e-10 ), 'statistic = 0' ); + t.ok( approxEqual( out.pValue, 1.0, 1e-10 ), 'pValue = 1.0' ); + t.strictEqual( out.rejected, false, 'null hypothesis not rejected' ); + t.end(); +}); + +tape( 'less alternative', function test( t ) { + // t.test(c(1,2,3,4,5), mu=4, alternative='less') + // t = -1.4142, df = 4, p-value = 0.1151 + var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); + var out = {}; + dttest( x.length, 'less', 0.05, 4.0, x, 1, out ); + + t.strictEqual( out.alternative, 'less', 'alternative = less' ); + t.ok( approxEqual( out.statistic, -1.4142135623730951, 1e-6 ), 'statistic ≈ -1.9365' ); + t.ok( approxEqual( out.pValue, 0.11509982054024949, 1e-4 ), 'pValue ≈ 0.0627' ); + t.strictEqual( out.rejected, false, 'null hypothesis not rejected at alpha=0.05' ); + t.strictEqual( out.ci[ 0 ], NINF, 'ci lower = -Inf' ); + t.end(); +}); + +tape( 'greater alternative', function test( t ) { + // t.test(c(1,2,3,4,5), mu=2, alternative='greater') + // t = 1.9365, df = 4, p-value = 0.0627 + var x = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); + var out = {}; + dttest( x.length, 'greater', 0.05, 2.0, x, 1, out ); + + t.strictEqual( out.alternative, 'greater', 'alternative = greater' ); + t.ok( approxEqual( out.statistic, 1.4142135623730951, 1e-6 ), 'statistic ≈ 1.9365' ); + t.ok( approxEqual( out.pValue, 0.11509982054024949, 1e-4 ), 'pValue ≈ 0.0627' ); + t.strictEqual( out.rejected, false, 'null hypothesis not rejected at alpha=0.05' ); + t.strictEqual( out.ci[ 1 ], PINF, 'ci upper = +Inf' ); + t.end(); +}); + +tape( 'non-unit stride (stride=2 picks every other element)', function test( t ) { + // x[0,2,4] = [1,3,5], same as Float64Array([1,3,5]) one-sample test + var x = new Float64Array( [ 1.0, 99.0, 3.0, 99.0, 5.0 ] ); + var ref = new Float64Array( [ 1.0, 3.0, 5.0 ] ); + var out1 = {}; + var out2 = {}; + dttest( 3, 'two-sided', 0.05, 0.0, x, 2, out1 ); + dttest( 3, 'two-sided', 0.05, 0.0, ref, 1, out2 ); + + t.ok( approxEqual( out1.statistic, out2.statistic, 1e-10 ), 'stride=2 matches unit stride on same elements' ); + t.ok( approxEqual( out1.pValue, out2.pValue, 1e-10 ), 'p-values match' ); + t.end(); +}); + +tape( 'negative stride reads array in reverse', function test( t ) { + // Reversed array should give same statistic as forward + var x = new Float64Array( [ 5.0, 4.0, 3.0, 2.0, 1.0 ] ); + var ref = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0 ] ); + var out1 = {}; + var out2 = {}; + dttest( 5, 'two-sided', 0.05, 0.0, x, -1, out1 ); + dttest( 5, 'two-sided', 0.05, 0.0, ref, 1, out2 ); + + t.ok( approxEqual( out1.statistic, out2.statistic, 1e-10 ), 'negative stride gives same statistic' ); + t.end(); +}); + +tape( 'returns NaN fields when N <= 1', function test( t ) { + var x = new Float64Array( [ 5.0 ] ); + var out = {}; + dttest( 1, 'two-sided', 0.05, 0.0, x, 1, out ); + + t.ok( isnan( out.statistic ), 'statistic is NaN for N=1' ); + t.ok( isnan( out.pValue ), 'pValue is NaN for N=1' ); + t.strictEqual( out.rejected, false, 'rejected is false' ); + t.end(); +}); + +tape( 'returns NaN fields when alpha is NaN', function test( t ) { + var x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + var out = {}; + dttest( x.length, 'two-sided', NaN, 0.0, x, 1, out ); + + t.ok( isnan( out.pValue ), 'pValue is NaN' ); + t.ok( isnan( out.statistic ), 'statistic is NaN' ); + t.end(); +}); + +tape( 'returns NaN fields when alpha is out of [0,1]', function test( t ) { + var x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + var out = {}; + dttest( x.length, 'two-sided', 1.5, 0.0, x, 1, out ); + + t.ok( isnan( out.pValue ), 'pValue is NaN when alpha > 1' ); + t.end(); +}); + +tape( 'confidence interval is ordered (lower <= upper) for two-sided', function test( t ) { + var x = new Float64Array( [ 2.0, 4.0, 6.0, 8.0, 10.0 ] ); + var out = {}; + dttest( x.length, 'two-sided', 0.05, 0.0, x, 1, out ); + + t.ok( out.ci[ 0 ] <= out.ci[ 1 ], 'CI is ordered' ); + t.end(); +}); + +tape( 'ndarray method: uses offset correctly', function test( t ) { + // Start from index 2: [3,4,5] + var x = new Float64Array( [ 99.0, 99.0, 3.0, 4.0, 5.0 ] ); + var ref = new Float64Array( [ 3.0, 4.0, 5.0 ] ); + var out1 = {}; + var out2 = {}; + dttest.ndarray( 3, 'two-sided', 0.05, 0.0, x, 1, 2, out1 ); + dttest.ndarray( 3, 'two-sided', 0.05, 0.0, ref, 1, 0, out2 ); + + t.ok( approxEqual( out1.statistic, out2.statistic, 1e-10 ), 'offset=2 matches reference' ); + t.end(); +});