Skip to content

Commit 589bf2a

Browse files
Orthodox-64Orthodox-64
authored
feat: add stats/base/ndarray/meanpw
PR-URL: #8396 Reviewed-by: Athan Reines <kgryte@gmail.com> Reviewed-by: Gururaj Gurram <gururajgurram1512@gmail.com>
1 parent 4c81241 commit 589bf2a

File tree

11 files changed

+779
-0
lines changed

11 files changed

+779
-0
lines changed

‎lib/node_modules/@stdlib/stats/base/ndarray/meanpw/README.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 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+
# meanpw
22+
23+
> Compute the [arithmetic mean][arithmetic-mean] of a one-dimensional ndarray using pairwise summation.
24+
25+
<section class="intro">
26+
27+
The [arithmetic mean][arithmetic-mean] is defined as
28+
29+
<!-- <equation class="equation" label="eq:arithmetic_mean" align="center" raw="\mu = \frac{1}{n} \sum_{i=0}^{n-1} x_i" alt="Equation for the arithmetic mean."> -->
30+
31+
```math
32+
\mu = \frac{1}{n} \sum_{i=0}^{n-1} x_i
33+
```
34+
35+
<!-- <div class="equation" align="center" data-raw-text="\mu = \frac{1}{n} \sum_{i=0}^{n-1} x_i" data-equation="eq:arithmetic_mean">
36+
<img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@develop/lib/node_modules/%40stdlib/stats/base/ndarray/meanpw/docs/img/equation_arithmetic_mean.svg" alt="Equation for the 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 meanpw = require( '@stdlib/stats/base/ndarray/meanpw' );
52+
```
53+
54+
#### meanpw( arrays )
55+
56+
Computes the [arithmetic mean][arithmetic-mean] of a one-dimensional ndarray using pairwise summation.
57+
58+
```javascript
59+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
60+
61+
var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
62+
var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
63+
64+
var v = meanpw( [ x ] );
65+
// returns 2.5
66+
```
67+
68+
The function has the following parameters:
69+
70+
- **arrays**: array-like object containing a one-dimensional input ndarray.
71+
72+
</section>
73+
74+
<!-- /.usage -->
75+
76+
<section class="notes">
77+
78+
## Notes
79+
80+
- If provided an empty one-dimensional ndarray, the function returns `NaN`.
81+
- In general, pairwise summation is more numerically stable than ordinary recursive summation (i.e., "simple" summation), with slightly worse performance. While not the most numerically stable summation technique (e.g., compensated summation techniques such as the Kahan–Babuška-Neumaier algorithm are generally more numerically stable), pairwise summation strikes a reasonable balance between numerical stability and performance. If either numerical stability or performance is more desirable for your use case, consider alternative summation techniques.
82+
83+
</section>
84+
85+
<!-- /.notes -->
86+
87+
<section class="examples">
88+
89+
## Examples
90+
91+
<!-- eslint-disable no-console -->
92+
93+
```javascript
94+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
95+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
96+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
97+
var meanpw = require( '@stdlib/stats/base/ndarray/meanpw' );
98+
99+
var xbuf = discreteUniform( 10, -50, 50, {
100+
'dtype': 'generic'
101+
});
102+
var x = new ndarray( 'generic', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
103+
console.log( ndarray2array( x ) );
104+
105+
var v = meanpw( [ x ] );
106+
console.log( v );
107+
```
108+
109+
</section>
110+
111+
<!-- /.examples -->
112+
113+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
114+
115+
<section class="related">
116+
117+
</section>
118+
119+
<!-- /.related -->
120+
121+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
122+
123+
<section class="links">
124+
125+
[arithmetic-mean]: https://en.wikipedia.org/wiki/Arithmetic_mean
126+
127+
</section>
128+
129+
<!-- /.links -->

‎lib/node_modules/@stdlib/stats/base/ndarray/meanpw/benchmark/benchmark.js‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
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 uniform = require( '@stdlib/random/array/uniform' );
25+
var isnan = require( '@stdlib/math/base/assert/is-nan' );
26+
var pow = require( '@stdlib/math/base/special/pow' );
27+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
28+
var pkg = require( './../package.json' ).name;
29+
var meanpw = require( './../lib' );
30+
31+
32+
// VARIABLES //
33+
34+
var options = {
35+
'dtype': 'generic'
36+
};
37+
38+
39+
// FUNCTIONS //
40+
41+
/**
42+
* Creates a benchmark function.
43+
*
44+
* @private
45+
* @param {PositiveInteger} len - array length
46+
* @returns {Function} benchmark function
47+
*/
48+
function createBenchmark( len ) {
49+
var xbuf;
50+
var x;
51+
52+
xbuf = uniform( len, -10.0, 10.0, options );
53+
x = new ndarray( options.dtype, xbuf, [ len ], [ 1 ], 0, 'row-major' );
54+
55+
return benchmark;
56+
57+
function benchmark( b ) {
58+
var v;
59+
var i;
60+
61+
b.tic();
62+
for ( i = 0; i < b.iterations; i++ ) {
63+
v = meanpw( [ x ] );
64+
if ( isnan( v ) ) {
65+
b.fail( 'should not return NaN' );
66+
}
67+
}
68+
b.toc();
69+
if ( isnan( v ) ) {
70+
b.fail( 'should not return NaN' );
71+
}
72+
b.pass( 'benchmark finished' );
73+
b.end();
74+
}
75+
}
76+
77+
78+
// MAIN //
79+
80+
/**
81+
* Main execution sequence.
82+
*
83+
* @private
84+
*/
85+
function main() {
86+
var len;
87+
var min;
88+
var max;
89+
var f;
90+
var i;
91+
92+
min = 1; // 10^min
93+
max = 6; // 10^max
94+
95+
for ( i = min; i <= max; i++ ) {
96+
len = pow( 10, i );
97+
f = createBenchmark( len );
98+
bench( pkg+':len='+len, f );
99+
}
100+
}
101+
102+
main();

‎lib/node_modules/@stdlib/stats/base/ndarray/meanpw/docs/img/equation_arithmetic_mean.svg‎

Lines changed: 42 additions & 0 deletions
Loading

‎lib/node_modules/@stdlib/stats/base/ndarray/meanpw/docs/repl.txt‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
{{alias}}( arrays )
3+
Computes the arithmetic mean of a one-dimensional ndarray using pairwise
4+
summation.
5+
6+
If provided an empty ndarray, the function returns `NaN`.
7+
8+
Parameters
9+
----------
10+
arrays: ArrayLikeObject<ndarray>
11+
Array-like object containing a one-dimensional input ndarray.
12+
13+
Returns
14+
-------
15+
out: number
16+
Arithmetic mean.
17+
18+
Examples
19+
--------
20+
> var xbuf = [ 1.0, -2.0, 2.0 ];
21+
> var dt = 'generic';
22+
> var sh = [ xbuf.length ];
23+
> var sx = [ 1 ];
24+
> var ox = 0;
25+
> var ord = 'row-major';
26+
> var x = new {{alias:@stdlib/ndarray/ctor}}( dt, xbuf, sh, sx, ox, ord );
27+
> {{alias}}( [ x ] )
28+
~0.3333
29+
30+
See Also
31+
--------
32+

‎lib/node_modules/@stdlib/stats/base/ndarray/meanpw/docs/types/index.d.ts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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+
// TypeScript Version: 4.1
20+
21+
/// <reference types="@stdlib/types"/>
22+
23+
import { ndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Computes the arithmetic mean of a one-dimensional ndarray using pairwise summation.
27+
*
28+
* @param arrays - array-like object containing an input ndarray
29+
* @returns arithmetic mean
30+
*
31+
* @example
32+
* var ndarray = require( '@stdlib/ndarray/base/ctor' );
33+
*
34+
* var xbuf = [ 1.0, 3.0, 4.0, 2.0 ];
35+
* var x = new ndarray( 'generic', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
36+
*
37+
* var v = meanpw( [ x ] );
38+
* // returns 2.5
39+
*/
40+
declare function meanpw<T extends ndarray = ndarray>( arrays: [ T ] ): number;
41+
42+
43+
// EXPORTS //
44+
45+
export = meanpw;

0 commit comments

Comments
 (0)