Skip to content

Commit ece0def

Browse files
MeKaustubh07MeKaustubh07
committed
feat: add stats/base/ndarray/sdsmeanors
1 parent e7054b7 commit ece0def

11 files changed

Lines changed: 790 additions & 0 deletions

File tree

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
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+
# sdsmeanors
22+
23+
> Compute the [arithmetic mean][arithmetic-mean] of a single-precision floating-point ndarray using ordinary recursive summation with extended accumulation.
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 sdsmeanors = require( '@stdlib/stats/base/ndarray/sdsmeanors' );
52+
```
53+
54+
#### sdsmeanors( arrays )
55+
56+
Computes the [arithmetic mean][arithmetic-mean] of a single-precision floating-point ndarray using ordinary recursive summation with extended accumulation.
57+
58+
```javascript
59+
var Float32Array = require( '@stdlib/array/float32' );
60+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
61+
62+
var xbuf = new Float32Array( [ 1.0, 3.0, 4.0, 2.0 ] );
63+
var x = new ndarray( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
64+
65+
var v = sdsmeanors( [ x ] );
66+
// returns 2.5
67+
```
68+
69+
The function has the following parameters:
70+
71+
- **arrays**: array-like object containing a one-dimensional input ndarray.
72+
73+
</section>
74+
75+
<!-- /.usage -->
76+
77+
<section class="notes">
78+
79+
## Notes
80+
81+
- If provided an empty one-dimensional ndarray, the function returns `NaN`.
82+
- Accumulated intermediate values are stored as double-precision floating-point numbers.
83+
- 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.
84+
85+
</section>
86+
87+
<!-- /.notes -->
88+
89+
<section class="examples">
90+
91+
## Examples
92+
93+
<!-- eslint-disable no-console -->
94+
95+
```javascript
96+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
97+
var ndarray = require( '@stdlib/ndarray/base/ctor' );
98+
var ndarray2array = require( '@stdlib/ndarray/to-array' );
99+
var sdsmeanors = require( '@stdlib/stats/base/ndarray/sdsmeanors' );
100+
101+
var xbuf = discreteUniform( 10, -50, 50, {
102+
'dtype': 'float32'
103+
});
104+
var x = new ndarray( 'float32', xbuf, [ xbuf.length ], [ 1 ], 0, 'row-major' );
105+
console.log( ndarray2array( x ) );
106+
107+
var v = sdsmeanors( [ x ] );
108+
console.log( v );
109+
```
110+
111+
</section>
112+
113+
<!-- /.examples -->
114+
115+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
116+
117+
<section class="related">
118+
119+
</section>
120+
121+
<!-- /.related -->
122+
123+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
124+
125+
<section class="links">
126+
127+
[arithmetic-mean]: https://en.wikipedia.org/wiki/Arithmetic_mean
128+
129+
</section>
130+
131+
<!-- /.links -->

‎lib/node_modules/@stdlib/stats/base/ndarray/sdsmeanors/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 isnanf = require( '@stdlib/math/base/assert/is-nanf' );
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 sdsmeanors = require( './../lib' );
30+
31+
32+
// VARIABLES //
33+
34+
var options = {
35+
'dtype': 'float32'
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 = sdsmeanors( [ x ] );
64+
if ( isnanf( v ) ) {
65+
b.fail( 'should not return NaN' );
66+
}
67+
}
68+
b.toc();
69+
if ( isnanf( 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/sdsmeanors/docs/img/equation_arithmetic_mean.svg‎

Lines changed: 42 additions & 0 deletions
Loading

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

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

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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 { float32ndarray } from '@stdlib/types/ndarray';
24+
25+
/**
26+
* Computes the arithmetic mean of a single-precision floating-point ndarray using ordinary recursive summation with extended accumulation.
27+
*
28+
* @param arrays - array-like object containing an input ndarray
29+
* @returns arithmetic mean
30+
*
31+
* @example
32+
* var Float32Array = require( '@stdlib/array/float32' );
33+
* var ndarray = require( '@stdlib/ndarray/base/ctor' );
34+
*
35+
* var xbuf = new Float32Array( [ 1.0, 3.0, 4.0, 2.0 ] );
36+
* var x = new ndarray( 'float32', xbuf, [ 4 ], [ 1 ], 0, 'row-major' );
37+
*
38+
* var v = sdsmeanors( [ x ] );
39+
* // returns 2.5
40+
*/
41+
declare function sdsmeanors( arrays: [ float32ndarray ] ): number;
42+
43+
44+
// EXPORTS //
45+
46+
export = sdsmeanors;

0 commit comments

Comments
 (0)