feat: add @stdlib/stats/strided/dttest

lib/node_modules/@stdlib/stats/strided/dttest/README.md

@@ -0,0 +1,220 @@
+<!--
+
+@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.
+
+-->
+
+<!-- lint disable max-heading-length -->
+
+# dttest
+
+> Compute a one-sample Student's t-test for a double-precision floating-point strided array.
+
+<section class="intro">
+
+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`.
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## 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 {...}
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## 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`.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## 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 );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+## See Also
+
+-   <span class="package-name">[`@stdlib/stats/strided/dztest`][@stdlib/stats/strided/dztest]</span><span class="delimiter">: </span><span class="description">compute a one-sample Z-test for a double-precision floating-point strided array.</span>
+-   <span class="package-name">[`@stdlib/stats/strided/sttest`][@stdlib/stats/strided/sttest]</span><span class="delimiter">: </span><span class="description">compute a one-sample Student's t-test for a single-precision floating-point strided array.</span>
+-   <span class="package-name">[`@stdlib/stats/ttest`][@stdlib/stats/ttest]</span><span class="delimiter">: </span><span class="description">one-sample and paired Student's t-test.</span>
+
+</section>
+
+<!-- /.related -->
+
+[@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

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 );
+}