Skip to content

Commit

Permalink
feat: add C ndarray interface and refactor implementation for `stat…
Browse files Browse the repository at this point in the history 
…s/base/dsnanmeanwd`

PR-URL: #4496
Reviewed-by: Athan Reines <[email protected]>
Reviewed-by: Aayush Khanna <[email protected]>
Co-authored-by: stdlib-bot <[email protected]>
  • Loading branch information
@Neerajpathak07 @stdlib-bot
Neerajpathak07 and stdlib-bot authored Feb 8, 2025
1 parent 885fa05 commit aacf454
Show file tree
Hide file tree
Showing 22 changed files with 412 additions and 260 deletions.
144 changes: 120 additions & 24 deletions lib/node_modules/@stdlib/stats/base/dsnanmeanwd/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,84 +51,79 @@ The [arithmetic mean][arithmetic-mean] is defined as
var dsnanmeanwd = require( '@stdlib/stats/base/dsnanmeanwd' );
```

#### dsnanmeanwd( N, x, stride )
#### dsnanmeanwd( N, x, strideX )

Computes the [arithmetic mean][arithmetic-mean] of a single-precision floating-point strided array `x`, ignoring `NaN` values, using Welford's algorithm with extended accumulation, and returning an extended precision result.

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

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

var v = dsnanmeanwd( N, x, 1 );
var v = dsnanmeanwd( x.length, x, 1 );
// returns ~0.3333
```

The function has the following parameters:

- **N**: number of indexed elements.
- **x**: input [`Float32Array`][@stdlib/array/float32].
- **stride**: index increment for `x`.
- **strideX**: stride length for `x`.

The `N` and stride parameters determine which elements in `x` are accessed at runtime. For example, to compute the [arithmetic mean][arithmetic-mean] of every other element in `x`,

The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [arithmetic mean][arithmetic-mean] of every other element in `x`,
<!-- eslint-disable max-len -->

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

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

var v = dsnanmeanwd( N, x, 2 );
var v = dsnanmeanwd( 5, x, 2 );
// returns 1.25
```

Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.

<!-- eslint-disable stdlib/capitalized-comments -->
<!-- eslint-disable stdlib/capitalized-comments, max-len -->

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

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

var N = floor( x0.length / 2 );

var v = dsnanmeanwd( N, x1, 2 );
var v = dsnanmeanwd( 5, x1, 2 );
// returns 1.25
```

#### dsnanmeanwd.ndarray( N, x, stride, offset )
#### dsnanmeanwd.ndarray( N, x, strideX, offsetX )

Computes the [arithmetic mean][arithmetic-mean] of a single-precision floating-point strided array, ignoring `NaN` values and using Welford's algorithm with extended accumulation and alternative indexing semantics.

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

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

var v = dsnanmeanwd.ndarray( N, x, 1, 0 );
var v = dsnanmeanwd.ndarray( x.length, x, 1, 0 );
// returns ~0.33333
```

The function has the following additional parameters:

- **offset**: starting index for `x`.
- **offsetX**: starting index for `x`.

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 [arithmetic mean][arithmetic-mean] for every other element in `x` starting from the second element

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 [arithmetic mean][arithmetic-mean] for every other value in `x` starting from the second value
<!-- eslint-disable max-len -->

```javascript
var Float32Array = require( '@stdlib/array/float32' );
var floor = require( '@stdlib/math/base/special/floor' );

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

var v = dsnanmeanwd.ndarray( N, x, 2, 1 );
var v = dsnanmeanwd.ndarray( 5, x, 2, 1 );
// returns 1.25
```

Expand Down Expand Up @@ -181,6 +176,107 @@ console.log( v );

<!-- /.examples -->

<!-- C usage documentation. -->

<section class="usage">

### Usage

```c
#include "stdlib/stats/base/dsnanmeanwd.h"
```

#### stdlib_strided_dsnanmeanwd( N, \*X, strideX )

Computes the arithmetic mean of a single-precision floating-point strided array, ignoring `NaN` values, using Welford's algorithm with extended accumulation, and returning an extended precision result.

```c
const float x[] = { 1.0f, 2.0f, 0.0f/0.0f, 3.0f, 0.0f/0.0f, 4.0f, 5.0f, 6.0f, 0.0f/0.0f, 7.0f, 8.0f, 0.0f/0.0f };

double v = stdlib_strided_dsnanmeanwd( 6, x, 2 );
// returns ~4.6667
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **X**: `[in] float*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
```c
double stdlib_strided_dsnanmeanwd( const CBLAS_INT N, const float *X, const CBLAS_INT strideX );
```

#### stdlib_strided_dsnanmeanwd_ndarray( N, \*X, strideX, offsetX )

Computes the arithmetic mean of a single-precision floating-point strided array, ignoring `NaN` values and using Welford's algorithm with extended accumulation and alternative indexing semantics.

```c
const float x[] = { 1.0f, 2.0f, 0.0f/0.0f, 3.0f, 0.0f/0.0f, 4.0f, 5.0f, 6.0f, 0.0f/0.0f, 7.0f, 8.0f, 0.0f/0.0f };

double v = stdlib_strided_dsnanmeanwd_ndarray( 6, x, 2, 0 );
// returns ~4.6667
```
The function accepts the following arguments:
- **N**: `[in] CBLAS_INT` number of indexed elements.
- **X**: `[in] float*` input array.
- **strideX**: `[in] CBLAS_INT` stride length for `X`.
- **offsetX**: `[in] CBLAS_INT` starting index for `X`.
```c
double stdlib_strided_dsnanmeanwd_ndarray( const CBLAS_INT N, const float *X, const CBLAS_INT strideX, const CBLAS_INT offsetX );
```

</section>

<!-- /.usage -->

<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="notes">

</section>

<!-- /.notes -->

<!-- C API usage examples. -->

<section class="examples">

### Examples

```c
#include "stdlib/stats/base/dsnanmeanwd.h"
#include <stdio.h>

int main( void ) {
// Create a strided array:
const float x[] = { 1.0f, 2.0f, 0.0f/0.0f, 3.0f, 0.0f/0.0f, 4.0f, 5.0f, 6.0f, 0.0f/0.0f, 7.0f, 8.0f, 0.0f/0.0f };

// Specify the number of elements:
const int N = 6;

// Specify the stride length:
const int strideX = 2;

// Compute the arithmetic mean:
double v = stdlib_strided_dsnanmeanwd( N, x, strideX );

// Print the result:
printf( "mean: %f\n", v );
}
```
</section>
<!-- /.examples -->
</section>
<!-- /.c -->
* * *
<section class="references">
Expand Down
30 changes: 17 additions & 13 deletions lib/node_modules/@stdlib/stats/base/dsnanmeanwd/benchmark/benchmark.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,30 @@
// MODULES //

var bench = require( '@stdlib/bench' );
var randu = require( '@stdlib/random/base/randu' );
var uniform = require( '@stdlib/random/base/uniform' );
var bernoulli = require( '@stdlib/random/base/bernoulli' );
var filledarrayBy = require( '@stdlib/array/filled-by' );
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var pow = require( '@stdlib/math/base/special/pow' );
var Float32Array = require( '@stdlib/array/float32' );
var pkg = require( './../package.json' ).name;
var dsnanmeanwd = require( './../lib/dsnanmeanwd.js' );


// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.8 ) < 1 ) {
return NaN;
}
return uniform( -10.0, 10.0 );
}

/**
* Creates a benchmark function.
*
Expand All @@ -39,17 +53,7 @@ var dsnanmeanwd = require( './../lib/dsnanmeanwd.js' );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x;
var i;

x = new Float32Array( len );
for ( i = 0; i < x.length; i++ ) {
if ( randu() < 0.2 ) {
x[ i ] = NaN;
} else {
x[ i ] = ( randu()*20.0 ) - 10.0;
}
}
var x = filledarrayBy( len, 'float32', rand );
return benchmark;

function benchmark( b ) {
Expand Down
30 changes: 17 additions & 13 deletions lib/node_modules/@stdlib/stats/base/dsnanmeanwd/benchmark/benchmark.native.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,11 @@

var resolve = require( 'path' ).resolve;
var bench = require( '@stdlib/bench' );
var randu = require( '@stdlib/random/base/randu' );
var uniform = require( '@stdlib/random/base/uniform' );
var bernoulli = require( '@stdlib/random/base/bernoulli' );
var filledarrayBy = require( '@stdlib/array/filled-by' );
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var pow = require( '@stdlib/math/base/special/pow' );
var Float32Array = require( '@stdlib/array/float32' );
var tryRequire = require( '@stdlib/utils/try-require' );
var pkg = require( './../package.json' ).name;

Expand All @@ -40,6 +41,19 @@ var opts = {

// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.8 ) < 1 ) {
return NaN;
}
return uniform( -10.0, 10.0 );
}

/**
* Creates a benchmark function.
*
Expand All @@ -48,17 +62,7 @@ var opts = {
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x;
var i;

x = new Float32Array( len );
for ( i = 0; i < x.length; i++ ) {
if ( randu() < 0.2 ) {
x[ i ] = NaN;
} else {
x[ i ] = ( randu()*20.0 ) - 10.0;
}
}
var x = filledarrayBy( len, 'float32', rand );
return benchmark;

function benchmark( b ) {
Expand Down
30 changes: 17 additions & 13 deletions lib/node_modules/@stdlib/stats/base/dsnanmeanwd/benchmark/benchmark.ndarray.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,30 @@
// MODULES //

var bench = require( '@stdlib/bench' );
var randu = require( '@stdlib/random/base/randu' );
var uniform = require( '@stdlib/random/base/uniform' );
var bernoulli = require( '@stdlib/random/base/bernoulli' );
var filledarrayBy = require( '@stdlib/array/filled-by' );
var isnan = require( '@stdlib/math/base/assert/is-nan' );
var pow = require( '@stdlib/math/base/special/pow' );
var Float32Array = require( '@stdlib/array/float32' );
var pkg = require( './../package.json' ).name;
var dsnanmeanwd = require( './../lib/ndarray.js' );


// FUNCTIONS //

/**
* Returns a random number.
*
* @private
* @returns {number} random number
*/
function rand() {
if ( bernoulli( 0.8 ) < 1 ) {
return NaN;
}
return uniform( -10.0, 10.0 );
}

/**
* Creates a benchmark function.
*
Expand All @@ -39,17 +53,7 @@ var dsnanmeanwd = require( './../lib/ndarray.js' );
* @returns {Function} benchmark function
*/
function createBenchmark( len ) {
var x;
var i;

x = new Float32Array( len );
for ( i = 0; i < x.length; i++ ) {
if ( randu() < 0.2 ) {
x[ i ] = NaN;
} else {
x[ i ] = ( randu()*20.0 ) - 10.0;
}
}
var x = filledarrayBy( len, 'float32', rand );
return benchmark;

function benchmark( b ) {
Expand Down
Loading

1 comment on commit aacf454

@stdlib-bot
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coverage Report

Package Statements Branches Functions Lines
stats/base/dsnanmeanwd $\color{green}402/402$
$\color{green}+100.00\%$ 		$\color{green}23/23$
$\color{green}+100.00\%$ 		$\color{green}4/4$
$\color{green}+100.00\%$ 		$\color{green}402/402$
$\color{green}+100.00\%$

The above coverage report was generated for the changes in this push.

Please sign in to comment.