Skip to content

Commit 1cfff5d

Browse files
Orthodox-64Orthodox-64
authored
feat: add stats/base/ndarray/meanors
PR-URL: #8407 Reviewed-by: Athan Reines <[email protected]>
1 parent d7012a5 commit 1cfff5d

File tree

11 files changed

+778
-0
lines changed

11 files changed

+778
-0
lines changed

‎lib/node_modules/@stdlib/stats/base/ndarray/meanors/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+
# meanors
22+
23+
> Compute the [arithmetic mean][arithmetic-mean] of a one-dimensional ndarray using ordinary recursive 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/meanors/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 meanors = require( '@stdlib/stats/base/ndarray/meanors' );
52+
```
53+
54+
#### meanors( arrays )
55+
56+
Computes the [arithmetic mean][arithmetic-mean] of a one-dimensional ndarray using ordinary recursive 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 = meanors( [ 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+
- Ordinary recursive summation (i.e., "simple" summation) is performant, but can incur significant numerical error. If performance is paramount and error tolerated, using ordinary recursive summation to compute the arithmetic mean is acceptable; in all other cases, exercise due caution.
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 meanors = require( '@stdlib/stats/base/ndarray/meanors' );
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 = meanors( [ 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/meanors/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 meanors = 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 = meanors( [ 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/meanors/docs/img/equation_arithmetic_mean.svg‎

Lines changed: 42 additions & 0 deletions
Loading

‎lib/node_modules/@stdlib/stats/base/ndarray/meanors/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 ordinary
4+
recursive 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/meanors/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 ordinary recursive 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 = meanors( [ x ] );
38+
* // returns 2.5
39+
*/
40+
declare function meanors<T extends ndarray = ndarray>( arrays: [ T ] ): number;
41+
42+
43+
// EXPORTS //
44+
45+
export = meanors;

0 commit comments

Comments
 (0)