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/9] 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() ); +``` + +
+ + + + + + 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/9] 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/9] 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() ); 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/9] 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, From 6c7e667cddda32f1e04e9d67e72669912fa6ac33 Mon Sep 17 00:00:00 2001 From: Kovidhraj Kotegiri Date: Wed, 28 Jan 2026 17:16:10 +0530 Subject: [PATCH 7/9] test: add missing test coverage for stats/incr/nanwmean --- 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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed --- --- .../@stdlib/stats/incr/nanwmean/test/test.js | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) 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 b29b28853509..6c946c61a19b 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js @@ -136,3 +136,33 @@ tape( 'if provided `NaN` for either a value or a weight, the accumulator functio t.equal( acc(), 2.0, 'ignores invalid inputs and maintains correct mean' ); t.end(); }); +tape( 'if not provided a weight, the accumulator function returns NaN', function test( t ) { + var acc = incrnanwmean(); + + acc( 2.0, 1.0 ); + t.strictEqual( isnan(acc( 3.0 )), true, 'returns current mean when weight is missing' ); + + t.end(); +}); +tape( 'Nan inputs do not poison future accumulated values', function test( t ) { + var acc = incrnanwmean(); + + acc( 2.0, 1.0 ); + acc( NaN, 1.0 ); + acc( 4.0, 1.0 ); + + t.equal( acc(), 3.0, 'NaN does not posion accumulator state' ); + t.end(); +}); +tape( 'calling the accumulator with no arguments after NaN inputs does not change state', function test( t ) { + var acc = incrnanwmean(); + + acc( 2.0, 1.0); + acc( NaN, 1.0); + + var v1 = acc(); + var v2 = acc(); + + t.equal( v1, v2, 'getting is independent' ); + t.end(); +}); \ No newline at end of file From 21fe8ec1e2e47f73945749748262ad406910ba64 Mon Sep 17 00:00:00 2001 From: Kovidhraj Kotegiri Date: Wed, 28 Jan 2026 17:37:24 +0530 Subject: [PATCH 8/9] chore: update license headers for nanwmean --- 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: na - task: lint_repl_help status: na - 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: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - 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 --- --- lib/node_modules/@stdlib/stats/incr/nanwmean/README.md | 2 +- .../@stdlib/stats/incr/nanwmean/benchmark/benchmark.js | 2 +- lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts | 2 +- lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js | 2 +- lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js | 2 +- lib/node_modules/@stdlib/stats/incr/nanwmean/lib/main.js | 2 +- lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md index 329921e50faf..ddfafccc9de3 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/README.md @@ -2,7 +2,7 @@ @license Apache-2.0 -Copyright (c) 2025 The Stdlib Authors. +Copyright (c) 2026 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/benchmark/benchmark.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js index 174c66f7bc74..f7c4b84633eb 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2025 The Stdlib Authors. +* Copyright (c) 2026 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/docs/types/test.ts b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts index cd62121c2923..6e86f9d176d9 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/docs/types/test.ts @@ -1,7 +1,7 @@ /* * @license Apache-2.0 * -* Copyright (c) 2025 The Stdlib Authors. +* Copyright (c) 2026 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/examples/index.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js index 922a9f7963a5..4afce87024b8 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/examples/index.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2025 The Stdlib Authors. +* Copyright (c) 2026 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/index.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/lib/index.js index 8f9572736c75..501bde92aea8 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) 2025 The Stdlib Authors. +* Copyright (c) 2026 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 96d82b0350f5..d3d450b855f3 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) 2025 The Stdlib Authors. +* Copyright (c) 2026 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/test/test.js b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js index 6c946c61a19b..ec52a5230572 100644 --- a/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js +++ b/lib/node_modules/@stdlib/stats/incr/nanwmean/test/test.js @@ -1,7 +1,7 @@ /** * @license Apache-2.0 * -* Copyright (c) 2025 The Stdlib Authors. +* Copyright (c) 2026 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. From 80566a8b97b67b43225d4fa420edf8193bd3e0df Mon Sep 17 00:00:00 2001 From: Kovidhraj Kotegiri Date: Wed, 28 Jan 2026 17:41:04 +0530 Subject: [PATCH 9/9] chore: update license headers for nanwmean --- 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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - 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 --- --- .../@stdlib/stats/incr/nanwmean/docs/types/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index ae26ac2e452f..a724a7818b02 100644 --- 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 @@ -1,7 +1,7 @@ /* * @license Apache-2.0 * -* Copyright (c) 2025 The Stdlib Authors. +* Copyright (c) 2026 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.