Skip to content

Commit f642f04

Browse files
Vinit-PanditkgryteAayush Khannastdlib-bot
authored
feat: add C ndarray interface and refactor implementation for stats/base/svariancewd
PR-URL: #4370 (review) Co-authored-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Aayush Khanna <aayushiitbhu23@gmail.com> Co-authored-by: Aayush Khanna <aayushiitbhu23@gmail.com> Co-authored-by: stdlib-bot <noreply@stdlib.io>
1 parent f482c99 commit f642f04

23 files changed

+364
-246
lines changed

lib/node_modules/@stdlib/stats/base/svariancewd/README.md

Lines changed: 135 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -98,17 +98,16 @@ The use of the term `n-1` is commonly referred to as Bessel's correction. Note,
9898
var svariancewd = require( '@stdlib/stats/base/svariancewd' );
9999
```
100100

101-
#### svariancewd( N, correction, x, stride )
101+
#### svariancewd( N, correction, x, strideX )
102102

103103
Computes the [variance][variance] of a single-precision floating-point strided array `x` using Welford's algorithm.
104104

105105
```javascript
106106
var Float32Array = require( '@stdlib/array/float32' );
107107

108108
var x = new Float32Array( [ 1.0, -2.0, 2.0 ] );
109-
var N = x.length;
110109

111-
var v = svariancewd( N, 1, x, 1 );
110+
var v = svariancewd( x.length, 1, x, 1 );
112111
// returns ~4.3333
113112
```
114113

@@ -117,18 +116,16 @@ The function has the following parameters:
117116
- **N**: number of indexed elements.
118117
- **correction**: degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [variance][variance] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [variance][variance] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the unbiased sample [variance][variance], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
119118
- **x**: input [`Float32Array`][@stdlib/array/float32].
120-
- **stride**: index increment for `x`.
119+
- **strideX**: stride length for `x`.
121120

122-
The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [variance][variance] of every other element in `x`,
121+
The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the [variance][variance] of every other element in `x`,
123122

124123
```javascript
125124
var Float32Array = require( '@stdlib/array/float32' );
126-
var floor = require( '@stdlib/math/base/special/floor' );
127125

128126
var x = new Float32Array( [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ] );
129-
var N = floor( x.length / 2 );
130127

131-
var v = svariancewd( N, 1, x, 2 );
128+
var v = svariancewd( 4, 1, x, 2 );
132129
// returns 6.25
133130
```
134131

@@ -138,45 +135,39 @@ Note that indexing is relative to the first index. To introduce an offset, use [
138135

139136
```javascript
140137
var Float32Array = require( '@stdlib/array/float32' );
141-
var floor = require( '@stdlib/math/base/special/floor' );
142138

143139
var x0 = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
144140
var x1 = new Float32Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
145141

146-
var N = floor( x0.length / 2 );
147-
148-
var v = svariancewd( N, 1, x1, 2 );
142+
var v = svariancewd( 4, 1, x1, 2 );
149143
// returns 6.25
150144
```
151145

152-
#### svariancewd.ndarray( N, correction, x, stride, offset )
146+
#### svariancewd.ndarray( N, correction, x, strideX, offsetX )
153147

154148
Computes the [variance][variance] of a single-precision floating-point strided array using Welford's algorithm and alternative indexing semantics.
155149

156150
```javascript
157151
var Float32Array = require( '@stdlib/array/float32' );
158152

159153
var x = new Float32Array( [ 1.0, -2.0, 2.0 ] );
160-
var N = x.length;
161154

162-
var v = svariancewd.ndarray( N, 1, x, 1, 0 );
155+
var v = svariancewd.ndarray( x.length, 1, x, 1, 0 );
163156
// returns ~4.33333
164157
```
165158

166159
The function has the following additional parameters:
167160

168-
- **offset**: starting index for `x`.
161+
- **offsetX**: starting index for `x`.
169162

170-
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 calculate the [variance][variance] for every other value in `x` starting from the second value
163+
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 calculate the [variance][variance] for every other element in `x` starting from the second element
171164

172165
```javascript
173166
var Float32Array = require( '@stdlib/array/float32' );
174-
var floor = require( '@stdlib/math/base/special/floor' );
175167

176168
var x = new Float32Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
177-
var N = floor( x.length / 2 );
178169

179-
var v = svariancewd.ndarray( N, 1, x, 2, 1 );
170+
var v = svariancewd.ndarray( 4, 1, x, 2, 1 );
180171
// returns 6.25
181172
```
182173

@@ -202,18 +193,12 @@ var v = svariancewd.ndarray( N, 1, x, 2, 1 );
202193
<!-- eslint no-undef: "error" -->
203194

204195
```javascript
205-
var randu = require( '@stdlib/random/base/randu' );
206-
var round = require( '@stdlib/math/base/special/round' );
207-
var Float32Array = require( '@stdlib/array/float32' );
196+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
208197
var svariancewd = require( '@stdlib/stats/base/svariancewd' );
209198

210-
var x;
211-
var i;
212-
213-
x = new Float32Array( 10 );
214-
for ( i = 0; i < x.length; i++ ) {
215-
x[ i ] = round( (randu()*100.0) - 50.0 );
216-
}
199+
var x = discreteUniform( 10, -50, 50, {
200+
'dtype': 'float32'
201+
});
217202
console.log( x );
218203

219204
var v = svariancewd( x.length, 1, x, 1 );
@@ -224,10 +209,130 @@ console.log( v );
224209

225210
<!-- /.examples -->
226211

212+
<!-- C interface documentation. -->
213+
227214
* * *
228215

216+
<section class="c">
217+
218+
## C APIs
219+
220+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
221+
222+
<section class="intro">
223+
224+
</section>
225+
226+
<!-- /.intro -->
227+
228+
<!-- C usage documentation. -->
229+
230+
<section class="usage">
231+
232+
### Usage
233+
234+
```c
235+
#include "stdlib/stats/base/svariancewd.h"
236+
```
237+
238+
#### stdlib_strided_svariancewd( N, correction, \*X, strideX )
239+
240+
Computes the [variance][variance] of a single-precision floating-point strided array using Welford's algorithm.
241+
242+
```c
243+
const float x[] = { 1.0f, -2.0f, 2.0f };
244+
245+
float v = stdlib_strided_svariancewd( 3, 1, x, 1 );
246+
// returns ~4.3333f
247+
```
248+
249+
The function accepts the following arguments:
250+
251+
- **N**: `[in] CBLAS_INT` number of indexed elements.
252+
- **correction**: `[in] float` degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [variance][variance] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [variance][variance] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the unbiased sample [variance][variance], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
253+
- **X**: `[in] float*` input array.
254+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
255+
256+
257+
```c
258+
float stdlib_strided_svariancewd( const CBLAS_INT N, const float correction, const float *X, const CBLAS_INT strideX );
259+
```
260+
261+
#### stdlib_strided_svariancewd_ndarray( N, correction, \*X, strideX, offsetX )
262+
263+
Computes the [variance][variance] of a single-precision floating-point strided array using Welford's algorithm and alternative indexing semantics.
264+
265+
```c
266+
const float x[] = { 1.0f, -2.0f, 2.0f };
267+
268+
float v = stdlib_strided_svariancewd_ndarray( 3, 1, x, 1, 0 );
269+
// returns ~4.33333f
270+
```
271+
272+
The function accepts the following arguments:
273+
274+
- **N**: `[in] CBLAS_INT` number of indexed elements.
275+
- **correction** `[in] float`: degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [variance][variance] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [variance][variance] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the unbiased sample [variance][variance], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
276+
- **X**: `[in] float*` input array.
277+
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
278+
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
279+
280+
```c
281+
float stdlib_strided_svariancewd_ndarray( const CBLAS_INT N, const float correction, const float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
282+
```
283+
284+
</section>
285+
286+
<!-- /.usage -->
287+
288+
<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
289+
290+
<section class="notes">
291+
292+
</section>
293+
294+
<!-- /.notes -->
295+
296+
<!-- C API usage examples. -->
297+
298+
<section class="examples">
299+
300+
### Examples
301+
302+
```c
303+
#include "stdlib/stats/base/svariancewd.h"
304+
#include <stdio.h>
305+
306+
int main( void ) {
307+
// Create a strided array:
308+
const float x[] = { 2.0f, 1.0f, 2.0f, -2.0f, -2.0f, 2.0f, 3.0f, 4.0f };
309+
310+
// Specify the number of elements:
311+
const int N = 4;
312+
313+
// Specify the stride length:
314+
const int strideX = 2;
315+
316+
// Compute the variance:
317+
float v = stdlib_strided_svariancewd( N, 1.0f, x, strideX );
318+
319+
// Print the result:
320+
printf( "sample variance: %f\n", v );
321+
}
322+
```
323+
324+
</section>
325+
326+
<!-- /.examples -->
327+
328+
</section>
329+
330+
<!-- /.c -->
331+
229332
<section class="references">
230333
334+
* * *
335+
231336
## References
232337
233338
- Welford, B. P. 1962. "Note on a Method for Calculating Corrected Sums of Squares and Products." _Technometrics_ 4 (3). Taylor & Francis: 419–20. doi:[10.1080/00401706.1962.10490022][@welford:1962a].

lib/node_modules/@stdlib/stats/base/svariancewd/benchmark/benchmark.js

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,20 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
2525
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2626
var pow = require( '@stdlib/math/base/special/pow' );
27-
var Float32Array = require( '@stdlib/array/float32' );
2827
var pkg = require( './../package.json' ).name;
2928
var svariancewd = require( './../lib/svariancewd.js' );
3029

3130

31+
// VARIABLES //
32+
33+
var options = {
34+
'dtype': 'float32'
35+
};
36+
37+
3238
// FUNCTIONS //
3339

3440
/**
@@ -39,13 +45,7 @@ var svariancewd = require( './../lib/svariancewd.js' );
3945
* @returns {Function} benchmark function
4046
*/
4147
function createBenchmark( len ) {
42-
var x;
43-
var i;
44-
45-
x = new Float32Array( len );
46-
for ( i = 0; i < x.length; i++ ) {
47-
x[ i ] = ( randu()*20.0 ) - 10.0;
48-
}
48+
var x = uniform( len, -10, 10, options );
4949
return benchmark;
5050

5151
function benchmark( b ) {

lib/node_modules/@stdlib/stats/base/svariancewd/benchmark/benchmark.native.js

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,10 @@
2121
// MODULES //
2222

2323
var resolve = require( 'path' ).resolve;
24+
var uniform = require( '@stdlib/random/array/uniform' );
2425
var bench = require( '@stdlib/bench' );
25-
var randu = require( '@stdlib/random/base/randu' );
2626
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2727
var pow = require( '@stdlib/math/base/special/pow' );
28-
var Float32Array = require( '@stdlib/array/float32' );
2928
var tryRequire = require( '@stdlib/utils/try-require' );
3029
var pkg = require( './../package.json' ).name;
3130

@@ -36,6 +35,9 @@ var svariancewd = tryRequire( resolve( __dirname, './../lib/svariancewd.native.j
3635
var opts = {
3736
'skip': ( svariancewd instanceof Error )
3837
};
38+
var options = {
39+
'dtype': 'float32'
40+
};
3941

4042

4143
// FUNCTIONS //
@@ -48,13 +50,7 @@ var opts = {
4850
* @returns {Function} benchmark function
4951
*/
5052
function createBenchmark( len ) {
51-
var x;
52-
var i;
53-
54-
x = new Float32Array( len );
55-
for ( i = 0; i < x.length; i++ ) {
56-
x[ i ] = ( randu()*20.0 ) - 10.0;
57-
}
53+
var x = uniform( len, -10, 10, options );
5854
return benchmark;
5955

6056
function benchmark( b ) {

lib/node_modules/@stdlib/stats/base/svariancewd/benchmark/benchmark.ndarray.js

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,20 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
2524
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2625
var pow = require( '@stdlib/math/base/special/pow' );
27-
var Float32Array = require( '@stdlib/array/float32' );
26+
var uniform = require( '@stdlib/random/array/uniform' );
2827
var pkg = require( './../package.json' ).name;
2928
var svariancewd = require( './../lib/ndarray.js' );
3029

3130

31+
// VARIABLES //
32+
33+
var options = {
34+
'dtype': 'float32'
35+
};
36+
37+
3238
// FUNCTIONS //
3339

3440
/**
@@ -39,13 +45,7 @@ var svariancewd = require( './../lib/ndarray.js' );
3945
* @returns {Function} benchmark function
4046
*/
4147
function createBenchmark( len ) {
42-
var x;
43-
var i;
44-
45-
x = new Float32Array( len );
46-
for ( i = 0; i < x.length; i++ ) {
47-
x[ i ] = ( randu()*20.0 ) - 10.0;
48-
}
48+
var x = uniform( len, -10, 10, options );
4949
return benchmark;
5050

5151
function benchmark( b ) {

lib/node_modules/@stdlib/stats/base/svariancewd/benchmark/benchmark.ndarray.native.js

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,10 @@
2222

2323
var resolve = require( 'path' ).resolve;
2424
var bench = require( '@stdlib/bench' );
25-
var randu = require( '@stdlib/random/base/randu' );
2625
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2726
var pow = require( '@stdlib/math/base/special/pow' );
28-
var Float32Array = require( '@stdlib/array/float32' );
2927
var tryRequire = require( '@stdlib/utils/try-require' );
28+
var uniform = require( '@stdlib/random/array/uniform' );
3029
var pkg = require( './../package.json' ).name;
3130

3231

@@ -36,6 +35,9 @@ var svariancewd = tryRequire( resolve( __dirname, './../lib/ndarray.native.js' )
3635
var opts = {
3736
'skip': ( svariancewd instanceof Error )
3837
};
38+
var options = {
39+
'dtype': 'float32'
40+
};
3941

4042

4143
// FUNCTIONS //
@@ -48,13 +50,7 @@ var opts = {
4850
* @returns {Function} benchmark function
4951
*/
5052
function createBenchmark( len ) {
51-
var x;
52-
var i;
53-
54-
x = new Float32Array( len );
55-
for ( i = 0; i < x.length; i++ ) {
56-
x[ i ] = ( randu()*20.0 ) - 10.0;
57-
}
53+
var x = uniform( len, -10, 10, options );
5854
return benchmark;
5955

6056
function benchmark( b ) {

0 commit comments

Comments
 (0)