From 155daca0783cce9b27c4fe0b820f512bf8ba3d52 Mon Sep 17 00:00:00 2001 From: Don Roy Chacko Date: Sun, 30 Mar 2025 01:30:22 +0530 Subject: [PATCH 1/6] feat (stats/incr/nanwmean): adds nanwmean package to the stats/incr/* namespace This commit adds a package which provides a way to compute the mean of a set of numbers while ignoring NaN values. It is made to address [RFC] Issue #5628, and as suggested in the issue, it is based on a thin wrapper around wmean, similar to the relationship between nansum and sum, mainting API consistency and design. This commit includes appropriate documentation and tests for the new purpose of the package, styles of which are consistent to the stats/incr/* namespace. Fixes: #5628 [RFC] Private-ref: https://github.com/stdlib-js/stdlib/issues/5628 Authored-by: Don Chacko --- .../@stdlib/stats/incr/nanwmean/README.md | 169 ++++++++++++++++++ .../incr/nanwmean/benchmark/benchmark.js | 66 +++++++ .../img/equation_weighted_arithmetic_mean.svg | 63 +++++++ .../@stdlib/stats/incr/nanwmean/docs/repl.txt | 41 +++++ .../stats/incr/nanwmean/docs/types/index.d.ts | 63 +++++++ .../stats/incr/nanwmean/docs/types/test.ts | 66 +++++++ .../stats/incr/nanwmean/examples/index.js | 44 +++++ .../@stdlib/stats/incr/nanwmean/lib/index.js | 54 ++++++ .../@stdlib/stats/incr/nanwmean/lib/main.js | 75 ++++++++ .../@stdlib/stats/incr/nanwmean/package.json | 70 ++++++++ .../@stdlib/stats/incr/nanwmean/test/test.js | 137 ++++++++++++++ 11 files changed, 848 insertions(+) create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/README.md create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/docs/img/equation_weighted_arithmetic_mean.svg create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/index.d.ts create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/package.json create mode 100644 lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md new file mode 100644 index 000000000000..06b2fa057460 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -0,0 +1,169 @@ + + +# incrnanwmean + +> Compute a [weighted arithmetic mean][weighted-arithmetic-mean] incrementally, while ignoring `NaN` values. + +
+ +The [weighted arithmetic mean][weighted-arithmetic-mean] is defined as + + + +```math +\bar{x} = \frac{\displaystyle\sum_{i=0}^{n-1} w_{i} x_{i}}{\displaystyle\sum_{i=0}^{n-1} w_{i}} +``` + + + + + +
+ + + +
+ +## Usage + +```javascript +var incrnanwmean = require( '@stdlib/stats/incr/wmean' ); +``` + +#### incrnanwmean() + +Returns an accumulator `function` which incrementally computes a [weighted arithmetic mean][weighted-arithmetic-mean], while ignoring NaN values. + +```javascript +var accumulator = incrwmean(); +``` + +#### accumulator( \[x, w] ) + +If provided an input value `x` and a weight `w`, the accumulator function returns an updated weighted mean. If not provided any input values, the accumulator function returns the current mean. + +```javascript +var accumulator = incrnanwmean(); + +var mu = accumulator( 2.0, 1.0 ); +// returns 2.0 + +mu = accumulator( 2.0, 0.5 ); +// returns 2.0 + +mu = accumulator( 3.0, 1.5 ); +// returns 2.5 + +mu = accumulator(); +// returns 2.5 + +mu = accumulator( NaN, 2 ); +// returns 2.5 + +mu = accumulator( 2, NaN ); +// returns 2.5 + +mu = accumulator( NaN, NaN ); +// returns 2.5 +``` + +
+ + + +
+ +
+ + + +
+ +## Examples + + + +```javascript +var randu = require( '@stdlib/random/base/randu' ); +var incrnanwmean = require( './../lib' ); + +var accumulator; +var mean; +var v; +var w; +var i; + +accumulator = incrnanwmean(); + +for ( i = 0; i < 100; i++ ) { + if ( randu() < 0.2 ) { + v = NaN; + w = NaN; + } else { + v = randu() * 100.0; + w = randu() * 10.0; + } + accumulator( v, w ); +} +console.log( accumulator() ); +``` + +
+ + + + + +
+ +* * * + +## See Also + +- [`@stdlib/stats/incr/nansum`](../nansum): compute an algebraic sum incrementally, while ignoring NaN values. +- [`@stdlib/stats/incr/wmean`](../wmean): compute an arithmetic mean incrementally. +- [`@stdlib/stats/incr/nanmean`](../nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. + + + + + + +
+ +[weighted-arithmetic-mean]: https://en.wikipedia.org/wiki/Weighted_arithmetic_mean + + + +[@stdlib/stats/incr/ewmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/ewmean + +[@stdlib/stats/incr/mean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mean + +[@stdlib/stats/incr/mmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mmean + + + +
+ + diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js new file mode 100644 index 000000000000..174c66f7bc74 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js @@ -0,0 +1,66 @@ +/** +* @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 randu = require( '@stdlib/random/base/randu' ); +var pkg = require( './../package.json' ).name; +var incrnanwmean = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var f; + var i; + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + f = incrnanwmean(); + if ( typeof f !== 'function' ) { + b.fail( 'should return a function' ); + } + } + b.toc(); + if ( typeof f !== 'function' ) { + b.fail( 'should return a function' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( pkg+'::accumulator', function benchmark( b ) { + var acc; + var v; + var w; + var i; + + acc = incrnanwmean(); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = ( randu() < 0.2 ) ? NaN : randu() * 100.0; + w = ( randu() < 0.2 ) ? NaN : randu() * 10.0; + acc( v, w ); + } + b.toc(); + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/img/equation_weighted_arithmetic_mean.svg b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/img/equation_weighted_arithmetic_mean.svg new file mode 100644 index 000000000000..28531390be9c --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/img/equation_weighted_arithmetic_mean.svg @@ -0,0 +1,63 @@ + +x overbar equals StartFraction sigma-summation Underscript i equals 0 Overscript n minus 1 Endscripts w Subscript i Baseline x Subscript i Baseline Over sigma-summation Underscript i equals 0 Overscript n minus 1 Endscripts w Subscript i Baseline EndFraction + + + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt new file mode 100644 index 000000000000..d48a0740ebf0 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt @@ -0,0 +1,41 @@ +{{alias}}() + Returns an accumulator function which incrementally computes a weighted + arithmetic mean, ignoring `NaN` values. + + If provided arguments, the accumulator function returns an updated weighted + mean. If not provided arguments, the accumulator function returns the + current weighted mean. + + If provided `NaN` for either a value or a weight, the accumulated value + remains unchanged and does not include the `NaN` values in computations. + + The accumulator function accepts two arguments: + + - x: value. + - w: weight. + + Returns + ------- + acc: Function + Accumulator function. + + Examples + -------- + > var accumulator = {{alias}}(); + > var mu = accumulator() + null + > mu = accumulator( 2.0, 1.0 ) + 2.0 + > mu = accumulator( NaN, 1.0 ) + 2.0 + > mu = accumulator( 3.0, 2.0 ) + 2.6666666666666665 + > mu = accumulator( 4.0, NaN ) + 2.6666666666666665 + > mu = accumulator( 5.0, 3.0 ) + 3.5 + > mu = accumulator() + 3.5 + + See Also + -------- diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/index.d.ts b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/index.d.ts new file mode 100644 index 000000000000..ae26ac2e452f --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/index.d.ts @@ -0,0 +1,63 @@ +/* +* @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 + +/// + +/** +* If provided values, returns an updated weighted mean; otherwise, returns the current weighted mean. +* +* @param x - value +* @param w - weight +* @returns weighted mean +*/ +type accumulator = ( x?: number, w?: number ) => number | null; + +/** +* Returns an accumulator function which incrementally computes a weighted mean, ignoring `NaN` values. +* +* @returns accumulator function +* +* @example +* var accumulator = incrnanwmean(); +* +* var v = accumulator(); +* // returns null +* +* v = accumulator( 2.0, 1.0 ); +* // returns 2.0 +* +* v = accumulator( 3.0, 2.0 ); +* // returns 2.666... +* +* v = accumulator( NaN, 1.0 ); +* // returns 2.666... +* +* v = accumulator( 4.0, 3.0 ); +* // returns 3.166... +* +* v = accumulator(); +* // returns 3.166... +*/ +declare function incrnanwmean(): accumulator; + + +// EXPORTS // + +export = incrnanwmean; diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts new file mode 100644 index 000000000000..cd62121c2923 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts @@ -0,0 +1,66 @@ +/* +* @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. +*/ + +import incrnanwmean = require( './index' ); + + +// TESTS // + +// The function returns an accumulator function... +{ + incrnanwmean(); // $ExpectType accumulator +} + +// The compiler throws an error if the function is provided arguments... +{ + incrnanwmean( '5' ); // $ExpectError + incrnanwmean( 5 ); // $ExpectError + incrnanwmean( true ); // $ExpectError + incrnanwmean( false ); // $ExpectError + incrnanwmean( null ); // $ExpectError + incrnanwmean( undefined ); // $ExpectError + incrnanwmean( [] ); // $ExpectError + incrnanwmean( {} ); // $ExpectError + incrnanwmean( ( x: number ): number => x ); // $ExpectError +} + +// The function returns an accumulator function which returns an accumulated result... +{ + const acc = incrnanwmean(); + + acc(); // $ExpectType number | null + acc( 3.14, 2.0 ); // $ExpectType number | null +} + +// The compiler throws an error if the returned accumulator function is provided invalid arguments... +{ + const acc = incrnanwmean(); + + acc( '5', 1.0 ); // $ExpectError + acc( 3.14, '2' ); // $ExpectError + acc( true, 2.0 ); // $ExpectError + acc( 3.14, false ); // $ExpectError + acc( null, 1.0 ); // $ExpectError + acc( 3.14, null ); // $ExpectError + acc( [], 1.0 ); // $ExpectError + acc( 3.14, [] ); // $ExpectError + acc( {}, 1.0 ); // $ExpectError + acc( 3.14, {} ); // $ExpectError + acc( ( x: number ): number => x, 1.0 ); // $ExpectError + acc( 3.14, ( x: number ): number => x ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js new file mode 100644 index 000000000000..922a9f7963a5 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js @@ -0,0 +1,44 @@ +/** +* @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 randu = require( '@stdlib/random/base/randu' ); +var incrnanwmean = require( './../lib' ); + +var accumulator; +var mean; +var v; +var w; +var i; + +accumulator = incrnanwmean(); + +console.log( '\nValue\tWeight\tMean\n' ); +for ( i = 0; i < 100; i++ ) { + if ( randu() < 0.2 ) { + v = NaN; + w = NaN; + } else { + v = randu() * 100.0; + w = randu() * 10.0; + } + mean = accumulator( v, w ); + console.log( '%d\t%d\t%d', v.toFixed( 4 ), w.toFixed( 4 ), ( mean === null ) ? NaN : mean.toFixed( 4 ) ); +} +console.log( '\nFinal weighted mean: %d\n', accumulator() ); diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js new file mode 100644 index 000000000000..6bb47ab2ffc6 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js @@ -0,0 +1,54 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2020 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 weighted mean incrementally, ignoring `NaN` values. +* +* @module @stdlib/stats/incr/nanwmean +* +* @example +* var incrnanwmean = require( '@stdlib/stats/incr/nanwmean' ); +* +* var accumulator = incrnanwmean(); +* +* var mean = accumulator(); +* // returns null +* +* mean = accumulator( 2.0, 1.0 ); +* // returns 2.0 +* +* mean = accumulator( NaN, 1.0 ); +* // returns 2.0 +* +* mean = accumulator( -5.0, 2.0 ); +* // returns -2.0 +* +* mean = accumulator(); +* // returns -2.0 +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js new file mode 100644 index 000000000000..611c27e49d1e --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js @@ -0,0 +1,75 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2020 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 isnan = require( '@stdlib/math/base/assert/is-nan' ); +var incrwmean = require( '@stdlib/stats/incr/wmean' ); + + +// MAIN // + +/** +* Returns an accumulator function which incrementally computes a weighted mean, ignoring `NaN` values. +* +* @returns {Function} accumulator function +* +* @example +* var accumulator = incrnanwmean(); +* +* var mean = accumulator(); +* // returns null +* +* mean = accumulator( 2.0, 1.0 ); +* // returns 2.0 +* +* mean = accumulator( NaN, 1.0 ); +* // returns 2.0 +* +* mean = accumulator( -5.0, 2.0 ); +* // returns -2.0 +* +* mean = accumulator(); +* // returns -2.0 +*/ +function incrnanwmean() { + var wmean = incrwmean(); + return accumulator; + + /** + * If provided arguments, the accumulator function returns an updated weighted mean. If not provided arguments, the accumulator function returns the current weighted mean. + * + * @private + * @param {number} [x] - value + * @param {number} [w] - weight + * @returns {(number|null)} weighted mean or null + */ + function accumulator( x, w ) { + if ( arguments.length === 0 || isnan( x ) || isnan( w ) ) { + return wmean(); + } + return wmean( x, w ); + } +} + + +// EXPORTS // + +module.exports = incrnanwmean; \ No newline at end of file diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/package.json b/lib/node_modules/@stdlib/stats/incr/nanwmean/package.json new file mode 100644 index 000000000000..ccf2c2737bf7 --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/package.json @@ -0,0 +1,70 @@ +{ + "name": "@stdlib/stats/incr/nanwmean", + "version": "0.0.0", + "description": "Compute a weighted arithmetic mean incrementally, ignoring NaN values.", + "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", + "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", + "average", + "avg", + "mean", + "arithmetic mean", + "central tendency", + "incremental", + "accumulator", + "weighted mean", + "nan", + "ignore nan" + ] +} + diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js new file mode 100644 index 000000000000..afdddc79b5eb --- /dev/null +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js @@ -0,0 +1,137 @@ +/** +* @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 isnan = require( '@stdlib/math/base/assert/is-nan' ); +var EPS = require( '@stdlib/constants/float64/eps' ); +var abs = require( '@stdlib/math/base/special/abs' ); +var incrnanwmean = require( './../lib' ); + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof incrnanwmean, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns an accumulator function', function test( t ) { + t.strictEqual( typeof incrnanwmean(), 'function', 'returns a function' ); + t.end(); +}); + +tape( 'the initial accumulated value is `null`', function test( t ) { + var acc = incrnanwmean(); + t.equal( acc(), null, 'returns expected value' ); + t.end(); +}); + +tape( 'the accumulator function incrementally computes a weighted arithmetic mean, ignoring NaN values', function test( t ) { + var expected; + var actual; + var delta; + var dataX; + var dataW; + var xwSum; + var wSum; + var acc; + var tol; + var N; + var x; + var w; + var i; + + dataX = [ 2.0, NaN, 3.0, NaN, 2.0, 4.0, NaN, 3.0, 4.0 ]; + dataW = [ 1.0, 2.0, 2.0, NaN, 0.1, 1.8, 9.9, 3.6, NaN ]; + N = dataX.length; + + acc = incrnanwmean(); + + xwSum = 0.0; + wSum = 0.0; + for ( i = 0; i < N; i++ ) { + x = dataX[ i ]; + w = dataW[ i ]; + + if ( !isnan( x ) && !isnan( w ) ) { + xwSum += x * w; + wSum += w; + } + + expected = ( wSum === 0 ) ? null : xwSum / wSum; + actual = acc( x, w ); + + if ( expected === null ) { + t.equal( actual, null, 'returns expected null' ); + } else { + delta = abs( actual - expected ); + tol = EPS * abs( expected ); + t.ok( delta <= tol, 'within tolerance. x: ' + x + '. w: ' + w + '. Value: ' + actual + '. Expected: ' + expected + '. Tolerance: ' + tol + '.' ); + } + } + t.end(); +}); + +tape( 'if not provided arguments, the accumulator function returns the current weighted mean', function test( t ) { + var dataX; + var dataW; + var acc; + var i; + + dataX = [ 2.0, 3.0, 1.0 ]; + dataW = [ 2.0, 2.0, 1.0 ]; + acc = incrnanwmean(); + for ( i = 0; i < dataX.length; i++ ) { + acc( dataX[ i ], dataW[ i ] ); + } + t.equal( acc(), 2.2, 'returns the current accumulated mean' ); + t.end(); +}); + +tape( 'if provided only `NaN` values, the accumulator function does not update the mean', function test( t ) { + var acc = incrnanwmean(); + acc( 10, 2 ); + acc( NaN, NaN ); + acc( NaN, 3 ); + acc( 5, NaN ); + + t.equal( acc(), 10, 'ignores NaN inputs and keeps the previous mean' ); + t.end(); +}); + +tape( 'if no valid weights are provided, the accumulator returns `null`', function test( t ) { + var acc = incrnanwmean(); + acc( NaN, NaN ); + acc( NaN, NaN ); + t.equal( acc(), null, 'returns null when no valid weights are given' ); + t.end(); +}); + +tape( 'if provided `NaN` for either a value or a weight, the accumulator function ignores the input', function test( t ) { + var acc = incrnanwmean(); + acc( 2.0, 1.0 ); + acc( NaN, 3.0 ); + acc( 3.0, NaN ); + + t.equal( acc(), 2.0, 'ignores invalid inputs and maintains correct mean' ); + t.end(); +}); From 4974c8293d5e5cb6c4981b2b30357c355e293260 Mon Sep 17 00:00:00 2001 From: Don Roy Chacko <52739172+SergeantQuickscoper@users.noreply.github.com> Date: Mon, 31 Mar 2025 19:51:38 +0530 Subject: [PATCH 2/6] fixup! feat: feat (stats/incr/nanwmean): adds nanwmean package to the stats/incr/* namespace This commit adds minor changes to the README.md of the nanwmean package, to improve clarity and fix a mistake in the usage section where a different package was used. Author: Don Roy Chacko Reviewed-by: hrshya Co-authored-by: Harsh <149176984+hrshya@users.noreply.github.com> Signed-off-by: Don Roy Chacko <52739172+SergeantQuickscoper@users.noreply.github.com> --- lib/node_modules/@stdlib/stats/incr/nanwmean/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index 06b2fa057460..c99735cfe970 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -20,7 +20,7 @@ limitations under the License. # incrnanwmean -> Compute a [weighted arithmetic mean][weighted-arithmetic-mean] incrementally, while ignoring `NaN` values. +> Compute a [weighted arithmetic mean][weighted-arithmetic-mean] incrementally, ignoring `NaN` values.
@@ -48,15 +48,15 @@ The [weighted arithmetic mean][weighted-arithmetic-mean] is defined as ## Usage ```javascript -var incrnanwmean = require( '@stdlib/stats/incr/wmean' ); +var incrnanwmean = require( '@stdlib/stats/incr/nanwmean' ); ``` #### incrnanwmean() -Returns an accumulator `function` which incrementally computes a [weighted arithmetic mean][weighted-arithmetic-mean], while ignoring NaN values. +Returns an accumulator `function` which incrementally computes a [weighted arithmetic mean][weighted-arithmetic-mean], ignoring NaN values. ```javascript -var accumulator = incrwmean(); +var accumulator = incrnanwmean(); ``` #### accumulator( \[x, w] ) From 028dc5374e7fd0f767d53ef9b3a9eb435d7c9004 Mon Sep 17 00:00:00 2001 From: Don Roy Chacko Date: Sat, 5 Apr 2025 12:30:15 +0530 Subject: [PATCH 3/6] fixup! feat (stats/incr/nanwmean): fixes lint errors This commit fixes the lint errors in the nanwmean module. The changes are applied to the following files: - nanwmean/README.md - nanwmean/docs/repl.txt - nanwmean/lib/index.js - nanwmean/lib/main.js - nanwmean/test/test.js Improvements include: - Correcting indentation and spacing issues - Switch to LF line endings --- .../@stdlib/stats/incr/nanwmean/README.md | 41 ++++++++----------- .../@stdlib/stats/incr/nanwmean/docs/repl.txt | 6 +-- .../@stdlib/stats/incr/nanwmean/lib/index.js | 2 +- .../@stdlib/stats/incr/nanwmean/lib/main.js | 8 ++-- .../@stdlib/stats/incr/nanwmean/test/test.js | 5 ++- 5 files changed, 27 insertions(+), 35 deletions(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index c99735cfe970..d28e564652e8 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -2,13 +2,13 @@ @license Apache-2.0 -Copyright (c) 2019 The Stdlib Authors. +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 + 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, @@ -84,7 +84,7 @@ mu = accumulator( NaN, 2 ); mu = accumulator( 2, NaN ); // returns 2.5 -mu = accumulator( NaN, NaN ); +mu = accumulator( NaN, NaN ); // returns 2.5 ``` @@ -106,7 +106,7 @@ mu = accumulator( NaN, NaN ); ```javascript var randu = require( '@stdlib/random/base/randu' ); -var incrnanwmean = require( './../lib' ); +var incrnanwmean = require( '@stdlib/stats/incr/nanwmean' ); var accumulator; var mean; @@ -117,14 +117,14 @@ var i; accumulator = incrnanwmean(); for ( i = 0; i < 100; i++ ) { - if ( randu() < 0.2 ) { - v = NaN; - w = NaN; - } else { - v = randu() * 100.0; - w = randu() * 10.0; - } - accumulator( v, w ); + if ( randu() < 0.2 ) { + v = NaN; + w = NaN; + } else { + v = randu() * 100.0; + w = randu() * 10.0; + } + accumulator( v, w ); } console.log( accumulator() ); ``` @@ -141,10 +141,11 @@ console.log( accumulator() ); ## See Also -- [`@stdlib/stats/incr/nansum`](../nansum): compute an algebraic sum incrementally, while ignoring NaN values. -- [`@stdlib/stats/incr/wmean`](../wmean): compute an arithmetic mean incrementally. -- [`@stdlib/stats/incr/nanmean`](../nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. +* [`@stdlib/stats/incr/nansum`](https://github.com/stdlib-js/stats-incr-nansum): compute an algebraic sum incrementally, while ignoring NaN values. +* [`@stdlib/stats/incr/wmean`](https://github.com/stdlib-js/stats-incr-wmean): compute an arithmetic mean incrementally. +* [`@stdlib/stats/incr/nanmean`](https://github.com/stdlib-js/stats-incr-nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. +
@@ -154,16 +155,6 @@ console.log( accumulator() ); [weighted-arithmetic-mean]: https://en.wikipedia.org/wiki/Weighted_arithmetic_mean - - -[@stdlib/stats/incr/ewmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/ewmean - -[@stdlib/stats/incr/mean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mean - -[@stdlib/stats/incr/mmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mmean - - -
diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt index d48a0740ebf0..b1e9037b6697 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt @@ -6,7 +6,7 @@ mean. If not provided arguments, the accumulator function returns the current weighted mean. - If provided `NaN` for either a value or a weight, the accumulated value + If provided `NaN` for either a value or a weight, the accumulated value remains unchanged and does not include the `NaN` values in computations. The accumulator function accepts two arguments: @@ -33,9 +33,9 @@ > mu = accumulator( 4.0, NaN ) 2.6666666666666665 > mu = accumulator( 5.0, 3.0 ) - 3.5 + 3.833333333333333 > mu = accumulator() - 3.5 + 3.833333333333333 See Also -------- diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js index 6bb47ab2ffc6..8f9572736c75 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2020 The Stdlib Authors. +* 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. diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js index 611c27e49d1e..96d82b0350f5 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2020 The Stdlib Authors. +* 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. @@ -44,10 +44,10 @@ var incrwmean = require( '@stdlib/stats/incr/wmean' ); * // returns 2.0 * * mean = accumulator( -5.0, 2.0 ); -* // returns -2.0 +* // returns -2.666666666666666 * * mean = accumulator(); -* // returns -2.0 +* // returns -2.666666666666666 */ function incrnanwmean() { var wmean = incrwmean(); @@ -72,4 +72,4 @@ function incrnanwmean() { // EXPORTS // -module.exports = incrnanwmean; \ No newline at end of file +module.exports = incrnanwmean; diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js index afdddc79b5eb..b29b28853509 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js @@ -24,7 +24,8 @@ var tape = require( 'tape' ); var isnan = require( '@stdlib/math/base/assert/is-nan' ); var EPS = require( '@stdlib/constants/float64/eps' ); var abs = require( '@stdlib/math/base/special/abs' ); -var incrnanwmean = require( './../lib' ); +var incrnanwmean = require( './../lib' ); + // TESTS // @@ -131,7 +132,7 @@ tape( 'if provided `NaN` for either a value or a weight, the accumulator functio acc( 2.0, 1.0 ); acc( NaN, 3.0 ); acc( 3.0, NaN ); - + t.equal( acc(), 2.0, 'ignores invalid inputs and maintains correct mean' ); t.end(); }); From cb7d379fe2355b63b366fd4ef71e2c5774d95376 Mon Sep 17 00:00:00 2001 From: Don Roy Chacko Date: Sat, 5 Apr 2025 12:47:35 +0530 Subject: [PATCH 4/6] fixup! feat (stats/incr/nanwmean): fixes remark lint errors This commit fixes remark lint errors in the README.md file for the `@stdlib/stats/incr/nanwmean` package. Authored By: Don Roy Chacko --- lib/node_modules/@stdlib/stats/incr/nanwmean/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index d28e564652e8..b72ad061a740 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -141,9 +141,9 @@ console.log( accumulator() ); ## See Also -* [`@stdlib/stats/incr/nansum`](https://github.com/stdlib-js/stats-incr-nansum): compute an algebraic sum incrementally, while ignoring NaN values. -* [`@stdlib/stats/incr/wmean`](https://github.com/stdlib-js/stats-incr-wmean): compute an arithmetic mean incrementally. -* [`@stdlib/stats/incr/nanmean`](https://github.com/stdlib-js/stats-incr-nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. +- [`@stdlib/stats/incr/nansum`](https://github.com/stdlib-js/stats-incr-nansum): compute an algebraic sum incrementally, while ignoring NaN values. +- [`@stdlib/stats/incr/wmean`](https://github.com/stdlib-js/stats-incr-wmean): compute an arithmetic mean incrementally. +- [`@stdlib/stats/incr/nanmean`](https://github.com/stdlib-js/stats-incr-nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. From a2378d03e35f7c35390ab8947a83013829c225fb Mon Sep 17 00:00:00 2001 From: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> Date: Sat, 5 Apr 2025 10:13:00 +0000 Subject: [PATCH 5/6] fix: resolve lint errors --- lib/node_modules/@stdlib/stats/incr/nanwmean/README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index b72ad061a740..ba0bce205cdb 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -137,14 +137,6 @@ console.log( accumulator() );
-* * * - -## See Also - -- [`@stdlib/stats/incr/nansum`](https://github.com/stdlib-js/stats-incr-nansum): compute an algebraic sum incrementally, while ignoring NaN values. -- [`@stdlib/stats/incr/wmean`](https://github.com/stdlib-js/stats-incr-wmean): compute an arithmetic mean incrementally. -- [`@stdlib/stats/incr/nanmean`](https://github.com/stdlib-js/stats-incr-nanmean): compute an arithmetic mean incrementally, while ignoring NaN values. -
From 896bbf3a25d6b5e44f77709399e688989cf5065e Mon Sep 17 00:00:00 2001 From: Don Roy Chacko Date: Sat, 5 Apr 2025 15:58:52 +0530 Subject: [PATCH 6/6] fixup! feat (stats/incr/nanwmean): fix final license header lint This commit is a license header lint fix for the nanwmean module for the README.md file. --- lib/node_modules/@stdlib/stats/incr/nanwmean/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index b72ad061a740..4eab625ee1c1 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -8,7 +8,7 @@ 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 + 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,