Skip to content

Commit 155daca

Browse files
SergeantQuickscoperSergeantQuickscoper
committed
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: #5628 Authored-by: Don Chacko <[email protected]>
1 parent 9980e59 commit 155daca

File tree

11 files changed

+848
-0
lines changed

11 files changed

+848
-0
lines changed

‎lib/node_modules/@stdlib/stats/incr/nanwmean/README.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2019 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+
# incrnanwmean
22+
23+
> Compute a [weighted arithmetic mean][weighted-arithmetic-mean] incrementally, while ignoring `NaN` values.
24+
25+
<section class="intro">
26+
27+
The [weighted arithmetic mean][weighted-arithmetic-mean] is defined as
28+
29+
<!-- <equation class="equation" label="eq:weighted_arithmetic_mean" align="center" raw="\bar{x} = \frac{\displaystyle\sum_{i=0}^{n-1} w_{i} x_{i}}{\displaystyle\sum_{i=0}^{n-1} w_{i}}" alt="Equation for the weighted arithmetic mean."> -->
30+
31+
```math
32+
\bar{x} = \frac{\displaystyle\sum_{i=0}^{n-1} w_{i} x_{i}}{\displaystyle\sum_{i=0}^{n-1} w_{i}}
33+
```
34+
35+
<!-- <div class="equation" align="center" data-raw-text="\bar{x} = \frac{\displaystyle\sum_{i=0}^{n-1} w_{i} x_{i}}{\displaystyle\sum_{i=0}^{n-1} w_{i}}" data-equation="eq:weighted_arithmetic_mean">
36+
<img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@adbea9806383f70c982e3191475c874efba1296b/lib/node_modules/@stdlib/stats/incr/wmean/docs/img/equation_weighted_arithmetic_mean.svg" alt="Equation for the weighted arithmetic mean.">
37+
<br>
38+
</div> -->
39+
40+
<!-- </equation> -->
41+
42+
</section>
43+
44+
<!-- /.intro -->
45+
46+
<section class="usage">
47+
48+
## Usage
49+
50+
```javascript
51+
var incrnanwmean = require( '@stdlib/stats/incr/wmean' );
52+
```
53+
54+
#### incrnanwmean()
55+
56+
Returns an accumulator `function` which incrementally computes a [weighted arithmetic mean][weighted-arithmetic-mean], while ignoring NaN values.
57+
58+
```javascript
59+
var accumulator = incrwmean();
60+
```
61+
62+
#### accumulator( \[x, w] )
63+
64+
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.
65+
66+
```javascript
67+
var accumulator = incrnanwmean();
68+
69+
var mu = accumulator( 2.0, 1.0 );
70+
// returns 2.0
71+
72+
mu = accumulator( 2.0, 0.5 );
73+
// returns 2.0
74+
75+
mu = accumulator( 3.0, 1.5 );
76+
// returns 2.5
77+
78+
mu = accumulator();
79+
// returns 2.5
80+
81+
mu = accumulator( NaN, 2 );
82+
// returns 2.5
83+
84+
mu = accumulator( 2, NaN );
85+
// returns 2.5
86+
87+
mu = accumulator( NaN, NaN );
88+
// returns 2.5
89+
```
90+
91+
</section>
92+
93+
<!-- /.usage -->
94+
95+
<section class="notes">
96+
97+
</section>
98+
99+
<!-- /.notes -->
100+
101+
<section class="examples">
102+
103+
## Examples
104+
105+
<!-- eslint no-undef: "error" -->
106+
107+
```javascript
108+
var randu = require( '@stdlib/random/base/randu' );
109+
var incrnanwmean = require( './../lib' );
110+
111+
var accumulator;
112+
var mean;
113+
var v;
114+
var w;
115+
var i;
116+
117+
accumulator = incrnanwmean();
118+
119+
for ( i = 0; i < 100; i++ ) {
120+
if ( randu() < 0.2 ) {
121+
v = NaN;
122+
w = NaN;
123+
} else {
124+
v = randu() * 100.0;
125+
w = randu() * 10.0;
126+
}
127+
accumulator( v, w );
128+
}
129+
console.log( accumulator() );
130+
```
131+
132+
</section>
133+
134+
<!-- /.examples -->
135+
136+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
137+
138+
<section class="related">
139+
140+
* * *
141+
142+
## See Also
143+
144+
- [`@stdlib/stats/incr/nansum`](../nansum): compute an algebraic sum incrementally, while ignoring NaN values.
145+
- [`@stdlib/stats/incr/wmean`](../wmean): compute an arithmetic mean incrementally.
146+
- [`@stdlib/stats/incr/nanmean`](../nanmean): compute an arithmetic mean incrementally, while ignoring NaN values.
147+
148+
149+
<!-- /.related -->
150+
151+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
152+
153+
<section class="links">
154+
155+
[weighted-arithmetic-mean]: https://en.wikipedia.org/wiki/Weighted_arithmetic_mean
156+
157+
<!-- <related-links> -->
158+
159+
[@stdlib/stats/incr/ewmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/ewmean
160+
161+
[@stdlib/stats/incr/mean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mean
162+
163+
[@stdlib/stats/incr/mmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mmean
164+
165+
<!-- </related-links> -->
166+
167+
</section>
168+
169+
<!-- /.links -->

‎lib/node_modules/@stdlib/stats/incr/nanwmean/benchmark/benchmark.js‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var bench = require( '@stdlib/bench' );
24+
var randu = require( '@stdlib/random/base/randu' );
25+
var pkg = require( './../package.json' ).name;
26+
var incrnanwmean = require( './../lib' );
27+
28+
29+
// MAIN //
30+
31+
bench( pkg, function benchmark( b ) {
32+
var f;
33+
var i;
34+
b.tic();
35+
for ( i = 0; i < b.iterations; i++ ) {
36+
f = incrnanwmean();
37+
if ( typeof f !== 'function' ) {
38+
b.fail( 'should return a function' );
39+
}
40+
}
41+
b.toc();
42+
if ( typeof f !== 'function' ) {
43+
b.fail( 'should return a function' );
44+
}
45+
b.pass( 'benchmark finished' );
46+
b.end();
47+
});
48+
49+
bench( pkg+'::accumulator', function benchmark( b ) {
50+
var acc;
51+
var v;
52+
var w;
53+
var i;
54+
55+
acc = incrnanwmean();
56+
57+
b.tic();
58+
for ( i = 0; i < b.iterations; i++ ) {
59+
v = ( randu() < 0.2 ) ? NaN : randu() * 100.0;
60+
w = ( randu() < 0.2 ) ? NaN : randu() * 10.0;
61+
acc( v, w );
62+
}
63+
b.toc();
64+
b.pass( 'benchmark finished' );
65+
b.end();
66+
});

‎lib/node_modules/@stdlib/stats/incr/nanwmean/docs/img/equation_weighted_arithmetic_mean.svg‎

Lines changed: 63 additions & 0 deletions
Loading

‎lib/node_modules/@stdlib/stats/incr/nanwmean/docs/repl.txt‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{{alias}}()
2+
Returns an accumulator function which incrementally computes a weighted
3+
arithmetic mean, ignoring `NaN` values.
4+
5+
If provided arguments, the accumulator function returns an updated weighted
6+
mean. If not provided arguments, the accumulator function returns the
7+
current weighted mean.
8+
9+
If provided `NaN` for either a value or a weight, the accumulated value
10+
remains unchanged and does not include the `NaN` values in computations.
11+
12+
The accumulator function accepts two arguments:
13+
14+
- x: value.
15+
- w: weight.
16+
17+
Returns
18+
-------
19+
acc: Function
20+
Accumulator function.
21+
22+
Examples
23+
--------
24+
> var accumulator = {{alias}}();
25+
> var mu = accumulator()
26+
null
27+
> mu = accumulator( 2.0, 1.0 )
28+
2.0
29+
> mu = accumulator( NaN, 1.0 )
30+
2.0
31+
> mu = accumulator( 3.0, 2.0 )
32+
2.6666666666666665
33+
> mu = accumulator( 4.0, NaN )
34+
2.6666666666666665
35+
> mu = accumulator( 5.0, 3.0 )
36+
3.5
37+
> mu = accumulator()
38+
3.5
39+
40+
See Also
41+
--------

0 commit comments

Comments
 (0)