Skip to content

Commit 0c3ca0a

Browse files
kgrytekgryte
committed
feat: add stats/strided/sztest
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: skipped - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: passed - task: lint_c_examples status: passed - task: lint_c_benchmarks status: passed - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---
1 parent 017fc80 commit 0c3ca0a

33 files changed

+4600
-0
lines changed

‎lib/node_modules/@stdlib/stats/strided/sztest/README.md

Lines changed: 390 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,390 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
<!-- lint disable max-heading-length -->
22+
23+
# sztest
24+
25+
> Compute a one-sample Z-test for a single-precision floating-point strided array.
26+
27+
<section class="intro">
28+
29+
A Z-test commonly refers to a one-sample location test which compares the mean of a set of measurements `X` to a given constant when the standard deviation is known. A Z-test supports testing three different null hypotheses `H0`:
30+
31+
- `H0: μ ≥ μ0` versus the alternative hypothesis `H1: μ < μ0`.
32+
- `H0: μ ≤ μ0` versus the alternative hypothesis `H1: μ > μ0`.
33+
- `H0: μ = μ0` versus the alternative hypothesis `H1: μ ≠ μ0`.
34+
35+
</section>
36+
37+
<!-- /.intro -->
38+
39+
<section class="usage">
40+
41+
## Usage
42+
43+
```javascript
44+
var sztest = require( '@stdlib/stats/strided/sztest' );
45+
```
46+
47+
#### sztest( N, alternative, alpha, mu, sigma, x, strideX, out )
48+
49+
Computes a one-sample Z-test for a single-precision floating-point strided array.
50+
51+
```javascript
52+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
53+
var Float32Array = require( '@stdlib/array/float32' );
54+
55+
var x = new Float32Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] );
56+
57+
var results = new Results();
58+
var out = sztest( x.length, 'two-sided', 0.05, 0.0, 1.0, x, 1, results );
59+
// returns {...}
60+
61+
var bool = ( out === results );
62+
// returns true
63+
```
64+
65+
The function has the following parameters:
66+
67+
- **N**: number of indexed elements.
68+
- **alternative**: [alternative hypothesis][@stdlib/stats/base/ztest/alternatives].
69+
- **alpha**: significance level.
70+
- **mu**: mean value under the null hypothesis.
71+
- **sigma**: known standard deviation.
72+
- **x**: input [`Float32Array`][@stdlib/array/float32].
73+
- **strideX**: stride length for `x`.
74+
- **out**: output [results object][@stdlib/stats/base/ztest/one-sample/results/float32].
75+
76+
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to perform a one-sample Z-test over every other element in `x`,
77+
78+
<!-- eslint-disable max-len -->
79+
80+
```javascript
81+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
82+
var Float32Array = require( '@stdlib/array/float32' );
83+
84+
var x = new Float32Array( [ 4.0, 0.0, 4.0, 0.0, 6.0, 0.0, 6.0, 0.0, 5.0, 0.0 ] );
85+
86+
var results = new Results();
87+
var out = sztest( 5, 'two-sided', 0.05, 0.0, 1.0, x, 2, results );
88+
// returns {...}
89+
90+
var bool = ( out === results );
91+
// returns true
92+
```
93+
94+
Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
95+
96+
<!-- eslint-disable stdlib/capitalized-comments -->
97+
98+
```javascript
99+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
100+
var Float32Array = require( '@stdlib/array/float32' );
101+
102+
var x0 = new Float32Array( [ 0.0, 4.0, 4.0, 6.0, 6.0, 5.0 ] );
103+
var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
104+
105+
var results = new Results();
106+
var out = sztest( x1.length, 'two-sided', 0.05, 0.0, 1.0, x1, 1, results );
107+
// returns {...}
108+
109+
var bool = ( out === results );
110+
// returns true
111+
```
112+
113+
#### sztest.ndarray( N, alternative, alpha, mu, sigma, x, strideX, offsetX, out )
114+
115+
Computes a one-sample Z-test for a single-precision floating-point strided array using alternative indexing semantics.
116+
117+
```javascript
118+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
119+
var Float32Array = require( '@stdlib/array/float32' );
120+
121+
var x = new Float32Array( [ 4.0, 4.0, 6.0, 6.0, 5.0 ] );
122+
123+
var results = new Results();
124+
var out = sztest.ndarray( x.length, 'two-sided', 0.05, 0.0, 1.0, x, 1, 0, results );
125+
// returns {...}
126+
127+
var bool = ( out === results );
128+
// returns true
129+
```
130+
131+
The function has the following additional parameters:
132+
133+
- **offsetX**: starting index for `x`.
134+
135+
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to perform a one-sample Z-test over every other element in `x` starting from the second element
136+
137+
```javascript
138+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
139+
var Float32Array = require( '@stdlib/array/float32' );
140+
141+
var x = new Float32Array( [ 0.0, 4.0, 0.0, 4.0, 0.0, 6.0, 0.0, 6.0, 0.0, 5.0 ] );
142+
143+
var results = new Results();
144+
var out = sztest.ndarray( 5, 'two-sided', 0.05, 0.0, 1.0, x, 2, 1, results );
145+
// returns {...}
146+
147+
var bool = ( out === results );
148+
// returns true
149+
```
150+
151+
</section>
152+
153+
<!-- /.usage -->
154+
155+
<section class="notes">
156+
157+
## Notes
158+
159+
- As a general rule of thumb, a Z-test is most reliable when `N >= 50`. For smaller sample sizes or when the standard deviation is unknown, prefer a t-test.
160+
161+
</section>
162+
163+
<!-- /.notes -->
164+
165+
<section class="examples">
166+
167+
## Examples
168+
169+
<!-- eslint no-undef: "error" -->
170+
171+
```javascript
172+
var Results = require( '@stdlib/stats/base/ztest/one-sample/results/float32' );
173+
var normal = require( '@stdlib/random/array/normal' );
174+
var sztest = require( '@stdlib/stats/strided/sztest' );
175+
176+
var x = normal( 1000, 0.0, 1.0, {
177+
'dtype': 'float32'
178+
});
179+
180+
var results = new Results();
181+
var out = sztest( x.length, 'two-sided', 0.05, 0.0, 1.0, x, 1, results );
182+
// returns {...}
183+
184+
console.log( out.toString() );
185+
```
186+
187+
</section>
188+
189+
<!-- /.examples -->
190+
191+
<!-- C interface documentation. -->
192+
193+
* * *
194+
195+
<section class="c">
196+
197+
## C APIs
198+
199+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
200+
201+
<section class="intro">
202+
203+
</section>
204+
205+
<!-- /.intro -->
206+
207+
<!-- C usage documentation. -->
208+
209+
<section class="usage">
210+
211+
### Usage
212+
213+
```c
214+
#include "stdlib/stats/strided/sztest.h"
215+
```
216+
217+
#### stdlib_strided_sztest( N, alternative, alpha, mu, sigma, \*X, strideX, \*results )
218+
219+
Computes a one-sample Z-test for a single-precision floating-point strided array.
220+
221+
```c
222+
#include "stdlib/stats/base/ztest/one-sample/results/float32.h"
223+
#include "stdlib/stats/base/ztest/alternatives.h"
224+
225+
struct stdlib_stats_ztest_one_sample_float32_results results = {
226+
.rejected = false,
227+
.alpha = 0.0f,
228+
.alternative = STDLIB_STATS_ZTEST_TWO_SIDED,
229+
.pValue = 0.0f,
230+
.statistic = 0.0f,
231+
.ci = { 0.0f, 0.0f },
232+
.nullValue = 0.0f,
233+
.sd = 0.0f
234+
};
235+
236+
const float x[] = { 4.0f, 4.0f, 6.0f, 6.0f, 5.0f };
237+
238+
stdlib_strided_sztest( 5, STDLIB_STATS_ZTEST_TWO_SIDED, 0.05f, 0.0f, 1.0f, x, 1, &results );
239+
```
240+
241+
The function accepts the following arguments:
242+
243+
- **N**: `[in] CBLAS_INT` number of indexed elements.
244+
- **alternative**: `[in] enum STDLIB_STATS_ZTEST_ALTERNATIVE` [alternative hypothesis][@stdlib/stats/base/ztest/alternatives].
245+
- **alpha**: `[in] float` significance level.
246+
- **mu**: `[in] float` value of the mean under the null hypothesis.
247+
- **sigma** `[in] float` known standard deviation.
248+
- **X**: `[in] float*` input array.
249+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
250+
- **results**: `[out] struct stdlib_stats_ztest_one_sample_results_float32*` output [results object][@stdlib/stats/base/ztest/one-sample/results/float32].
251+
252+
```c
253+
void stdlib_strided_sztest( const CBLAS_INT N, const enum STDLIB_STATS_ZTEST_ALTERNATIVE alternative, const float alpha, const float mu, const float sigma, const float *X, const CBLAS_INT strideX, struct stdlib_stats_ztest_one_sample_float32_results *results );
254+
```
255+
256+
#### stdlib_strided_sztest_ndarray( N, alternative, alpha, mu, sigma, \*X, strideX, offsetX, \*results )
257+
258+
Computes a one-sample Z-test for a single-precision floating-point strided array using alternative indexing semantics.
259+
260+
```c
261+
#include "stdlib/stats/base/ztest/one-sample/results/float32.h"
262+
#include "stdlib/stats/base/ztest/alternatives.h"
263+
264+
struct stdlib_stats_ztest_one_sample_float32_results results = {
265+
.rejected = false,
266+
.alpha = 0.0f,
267+
.alternative = STDLIB_STATS_ZTEST_TWO_SIDED,
268+
.pValue = 0.0f,
269+
.statistic = 0.0f,
270+
.ci = { 0.0f, 0.0f },
271+
.nullValue = 0.0f,
272+
.sd = 0.0f
273+
};
274+
275+
const float x[] = { 4.0f, 4.0f, 6.0f, 6.0f, 5.0f };
276+
277+
stdlib_strided_sztest_ndarray( 5, STDLIB_STATS_ZTEST_TWO_SIDED, 0.05f, 0.0f, 1.0f, x, 1, 0, &results );
278+
```
279+
280+
The function accepts the following arguments:
281+
282+
- **N**: `[in] CBLAS_INT` number of indexed elements.
283+
- **alternative**: `[in] enum STDLIB_STATS_ZTEST_ALTERNATIVE` [alternative hypothesis][@stdlib/stats/base/ztest/alternatives].
284+
- **alpha**: `[in] float` significance level.
285+
- **mu**: `[in] float` value of the mean under the null hypothesis.
286+
- **sigma** `[in] float` known standard deviation.
287+
- **X**: `[in] float*` input array.
288+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
289+
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
290+
- **results**: `[out] struct stdlib_stats_ztest_one_sample_results_float32*` output [results object][@stdlib/stats/base/ztest/one-sample/results/float32].
291+
292+
```c
293+
void stdlib_strided_sztest_ndarray( const CBLAS_INT N, const enum STDLIB_STATS_ZTEST_ALTERNATIVE alternative, const float alpha, const float mu, const float sigma, const float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX, struct stdlib_stats_ztest_one_sample_float32_results *results );
294+
```
295+
296+
</section>
297+
298+
<!-- /.usage -->
299+
300+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
301+
302+
<section class="notes">
303+
304+
</section>
305+
306+
<!-- /.notes -->
307+
308+
<!-- C API usage examples. -->
309+
310+
<section class="examples">
311+
312+
### Examples
313+
314+
```c
315+
#include "stdlib/stats/strided/sztest.h"
316+
#include "stdlib/stats/base/ztest/one-sample/results/float32.h"
317+
#include "stdlib/stats/base/ztest/alternatives.h"
318+
#include <stdbool.h>
319+
#include <stdio.h>
320+
321+
int main( void ) {
322+
// Create a strided array:
323+
const float x[] = { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f, 7.0f, 8.0f };
324+
325+
// Specify the number of elements:
326+
const int N = 4;
327+
328+
// Specify the stride length:
329+
const int strideX = 2;
330+
331+
// Initialize a results object:
332+
struct stdlib_stats_ztest_one_sample_float32_results results = {
333+
.rejected = false,
334+
.alpha = 0.0f,
335+
.alternative = STDLIB_STATS_ZTEST_TWO_SIDED,
336+
.pValue = 0.0f,
337+
.statistic = 0.0f,
338+
.ci = { 0.0f, 0.0f },
339+
.nullValue = 0.0f,
340+
.sd = 0.0f
341+
};
342+
343+
// Compute a Z-test:
344+
stdlib_strided_sztest( N, STDLIB_STATS_ZTEST_TWO_SIDED, 0.05f, 5.0f, 3.0f, x, strideX, &results );
345+
346+
// Print the result:
347+
printf( "Statistic: %f\n", results.statistic );
348+
printf( "Null hypothesis was %s\n", ( results.rejected ) ? "rejected" : "not rejected" );
349+
}
350+
```
351+
352+
</section>
353+
354+
<!-- /.examples -->
355+
356+
</section>
357+
358+
<!-- /.c -->
359+
360+
<section class="references">
361+
362+
</section>
363+
364+
<!-- /.references -->
365+
366+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
367+
368+
<section class="related">
369+
370+
</section>
371+
372+
<!-- /.related -->
373+
374+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
375+
376+
<section class="links">
377+
378+
[variance]: https://en.wikipedia.org/wiki/Variance
379+
380+
[@stdlib/array/float32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/float32
381+
382+
[@stdlib/stats/base/ztest/alternatives]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/ztest/alternatives
383+
384+
[@stdlib/stats/base/ztest/one-sample/results/float32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/ztest/one-sample/results/float32
385+
386+
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
387+
388+
</section>
389+
390+
<!-- /.links -->

0 commit comments

Comments
 (0)