Skip to content

Commit 7cf0bfd

Browse files
apfossdevapfossdev
committed
refactor: add accessor protocol support to stats/base/mean #5629
Refactor the mean function to add support for the accessor protocol. This change ensures that the function can handle array-like objects with custom accessors, improving flexibility and compatibility with various data structures. - Refactor mean function in main.js to delegate to ndarray.js - Update ndarray.js to handle accessor protocol - Add tests for accessor protocol support - Fix JSDoc comments and examples for accuracy Fixes: #5629 --- 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: passed - 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 --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na --- --- type: pre_push_report description: Results of running various checks prior to pushing changes. report: - task: run_javascript_examples status: na - task: run_c_examples status: na - task: run_cpp_examples status: na - task: run_javascript_readme_examples status: na - task: run_c_benchmarks status: na - task: run_cpp_benchmarks status: na - task: run_fortran_benchmarks status: na - task: run_javascript_benchmarks status: na - task: run_julia_benchmarks status: na - task: run_python_benchmarks status: na - task: run_r_benchmarks status: na - task: run_javascript_tests status: na ---
1 parent 1770970 commit 7cf0bfd

File tree

14 files changed

+228
-175
lines changed

14 files changed

+228
-175
lines changed

‎lib/node_modules/@stdlib/stats/base/mean/README.md‎

Lines changed: 17 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -51,33 +51,29 @@ The [arithmetic mean][arithmetic-mean] is defined as
5151
var mean = require( '@stdlib/stats/base/mean' );
5252
```
5353

54-
#### mean( N, x, stride )
54+
#### mean( N, x, strideX )
5555

5656
Computes the [arithmetic mean][arithmetic-mean] of a strided array `x`.
5757

5858
```javascript
5959
var x = [ 1.0, -2.0, 2.0 ];
60-
var N = x.length;
6160

62-
var v = mean( N, x, 1 );
61+
var v = mean( x.length, x, 1 );
6362
// returns ~0.3333
6463
```
6564

6665
The function has the following parameters:
6766

6867
- **N**: number of indexed elements.
6968
- **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array].
70-
- **stride**: index increment for `x`.
69+
- **strideX**: stride length for `x`.
7170

72-
The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [arithmetic mean][arithmetic-mean] of every other element in `x`,
71+
The `N` and `stride` parameters determine which elements in the strided array are accessed at runtime. For example, to compute the [arithmetic mean][arithmetic-mean] of every other element in `x`,
7372

7473
```javascript
75-
var floor = require( '@stdlib/math/base/special/floor' );
76-
7774
var x = [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0 ];
78-
var N = floor( x.length / 2 );
7975

80-
var v = mean( N, x, 2 );
76+
var v = mean( 4, x, 2 );
8177
// returns 1.25
8278
```
8379

@@ -87,42 +83,36 @@ Note that indexing is relative to the first index. To introduce an offset, use [
8783

8884
```javascript
8985
var Float64Array = require( '@stdlib/array/float64' );
90-
var floor = require( '@stdlib/math/base/special/floor' );
9186

9287
var x0 = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] );
9388
var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
9489

95-
var N = floor( x0.length / 2 );
96-
97-
var v = mean( N, x1, 2 );
90+
var v = mean( 4, x1, 2 );
9891
// returns 1.25
9992
```
10093

101-
#### mean.ndarray( N, x, stride, offset )
94+
#### mean.ndarray( N, x, strideX, offsetX )
10295

10396
Computes the [arithmetic mean][arithmetic-mean] of a strided array using alternative indexing semantics.
10497

10598
```javascript
10699
var x = [ 1.0, -2.0, 2.0 ];
107100
var N = x.length;
108101

109-
var v = mean.ndarray( N, x, 1, 0 );
102+
var v = mean.ndarray( x.length, x, 1, 0 );
110103
// returns ~0.33333
111104
```
112105

113106
The function has the following additional parameters:
114107

115-
- **offset**: starting index for `x`.
108+
- **offsetX**: starting index for `x`.
116109

117110
While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the [arithmetic mean][arithmetic-mean] for every other value in `x` starting from the second value
118111

119112
```javascript
120-
var floor = require( '@stdlib/math/base/special/floor' );
121-
122113
var x = [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ];
123-
var N = floor( x.length / 2 );
124114

125-
var v = mean.ndarray( N, x, 2, 1 );
115+
var v = mean.ndarray( 4, x, 2, 1 );
126116
// returns 1.25
127117
```
128118

@@ -135,6 +125,7 @@ var v = mean.ndarray( N, x, 2, 1 );
135125
## Notes
136126

137127
- If `N <= 0`, both functions return `NaN`.
128+
- Both functions support array-like objects having getter and setter accessors for array element access (e.g., [`@stdlib/array/base/accessor`][@stdlib/array/base/accessor]).
138129
- Depending on the environment, the typed versions ([`dmean`][@stdlib/stats/base/dmean], [`smean`][@stdlib/stats/base/smean], etc.) are likely to be significantly more performant.
139130

140131
</section>
@@ -148,18 +139,12 @@ var v = mean.ndarray( N, x, 2, 1 );
148139
<!-- eslint no-undef: "error" -->
149140

150141
```javascript
151-
var randu = require( '@stdlib/random/base/randu' );
152-
var round = require( '@stdlib/math/base/special/round' );
153-
var Float64Array = require( '@stdlib/array/float64' );
142+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
154143
var mean = require( '@stdlib/stats/base/mean' );
155144

156-
var x;
157-
var i;
158-
159-
x = new Float64Array( 10 );
160-
for ( i = 0; i < x.length; i++ ) {
161-
x[ i ] = round( (randu()*100.0) - 50.0 );
162-
}
145+
var x = discreteUniform( 10, -50, 50, {
146+
'dtype': 'float64'
147+
});
163148
console.log( x );
164149

165150
var v = mean( x.length, x, 1 );
@@ -196,6 +181,8 @@ console.log( v );
196181

197182
[mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
198183

184+
[@stdlib/array/base/accessor]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/accessor
185+
199186
<!-- <related-links> -->
200187

201188
[@stdlib/stats/base/dmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/base/dmean

‎lib/node_modules/@stdlib/stats/base/mean/benchmark/benchmark.js‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,18 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
2525
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2626
var pow = require( '@stdlib/math/base/special/pow' );
2727
var pkg = require( './../package.json' ).name;
28-
var mean = require( './../lib/mean.js' );
28+
var mean = require( './../lib/main.js' );
29+
30+
31+
// VARIABLES //
32+
33+
var options = {
34+
'dtype': 'generic'
35+
};
2936

3037

3138
// FUNCTIONS //
@@ -38,13 +45,7 @@ var mean = require( './../lib/mean.js' );
3845
* @returns {Function} benchmark function
3946
*/
4047
function createBenchmark( len ) {
41-
var x;
42-
var i;
43-
44-
x = [];
45-
for ( i = 0; i < len; i++ ) {
46-
x.push( ( randu()*20.0 ) - 10.0 );
47-
}
48+
var x = uniform( len, -10, 10, options );
4849
return benchmark;
4950

5051
function benchmark( b ) {

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

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,20 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
2525
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2626
var pow = require( '@stdlib/math/base/special/pow' );
2727
var pkg = require( './../package.json' ).name;
2828
var mean = require( './../lib/ndarray.js' );
2929

3030

31+
// VARIABLES //
32+
33+
var options = {
34+
'dtype': 'generic'
35+
};
36+
37+
3138
// FUNCTIONS //
3239

3340
/**
@@ -38,13 +45,7 @@ var mean = require( './../lib/ndarray.js' );
3845
* @returns {Function} benchmark function
3946
*/
4047
function createBenchmark( len ) {
41-
var x;
42-
var i;
43-
44-
x = [];
45-
for ( i = 0; i < len; i++ ) {
46-
x.push( ( randu()*20.0 ) - 10.0 );
47-
}
48+
var x = uniform( len, -10, 10, options );
4849
return benchmark;
4950

5051
function benchmark( b ) {

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

Lines changed: 16 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11

2-
{{alias}}( N, x, stride )
2+
{{alias}}( N, x, strideX )
33
Computes the arithmetic mean of a strided array.
44

5-
The `N` and `stride` parameters determine which elements in `x` are accessed
6-
at runtime.
5+
The `N` and `stride` parameters determine which elements in the strided
6+
array are accessed at runtime.
77

8-
Indexing is relative to the first index. To introduce an offset, use a typed
9-
array view.
8+
Indexing is relative to the first index. To introduce an offset, use a
9+
typed array view.
1010

1111
If `N <= 0`, the function returns `NaN`.
1212

@@ -18,8 +18,8 @@
1818
x: Array<number>|TypedArray
1919
Input array.
2020

21-
stride: integer
22-
Index increment.
21+
strideX: integer
22+
Stride length.
2323

2424
Returns
2525
-------
@@ -33,22 +33,19 @@
3333
> {{alias}}( x.length, x, 1 )
3434
~0.3333
3535

36-
// Using `N` and `stride` parameters:
36+
// Using `N` and stride parameters:
3737
> x = [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0 ];
38-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
39-
> var stride = 2;
40-
> {{alias}}( N, x, stride )
38+
> {{alias}}( 3, x, 2 )
4139
~0.3333
4240

4341
// Using view offsets:
4442
> var x0 = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ] );
4543
> var x1 = new {{alias:@stdlib/array/float64}}( x0.buffer, x0.BYTES_PER_ELEMENT*1 );
46-
> N = {{alias:@stdlib/math/base/special/floor}}( x0.length / 2 );
47-
> stride = 2;
48-
> {{alias}}( N, x1, stride )
44+
> {{alias}}( 3, x1, 2 )
4945
~-0.3333
5046

51-
{{alias}}.ndarray( N, x, stride, offset )
47+
48+
{{alias}}.ndarray( N, x, strideX, offsetX )
5249
Computes the arithmetic mean of a strided array using alternative indexing
5350
semantics.
5451

@@ -64,10 +61,10 @@
6461
x: Array<number>|TypedArray
6562
Input array.
6663

67-
stride: integer
68-
Index increment.
64+
strideX: integer
65+
Stride length.
6966

70-
offset: integer
67+
offsetX: integer
7168
Starting index.
7269

7370
Returns
@@ -84,8 +81,7 @@
8481

8582
// Using offset parameter:
8683
> var x = [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ];
87-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
88-
> {{alias}}.ndarray( N, x, 2, 1 )
84+
> {{alias}}.ndarray( 3, x, 2, 1 )
8985
~-0.3333
9086

9187
See Also

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

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,12 @@
2020

2121
/// <reference types="@stdlib/types"/>
2222

23-
import { NumericArray } from '@stdlib/types/array';
23+
import { NumericArray, Collection, AccessorArrayLike } from '@stdlib/types/array';
24+
25+
/**
26+
* Input array.
27+
*/
28+
type InputArray = NumericArray | Collection<number> | AccessorArrayLike<number>;
2429

2530
/**
2631
* Interface describing `mean`.
@@ -31,7 +36,7 @@ interface Routine {
3136
*
3237
* @param N - number of indexed elements
3338
* @param x - input array
34-
* @param stride - stride length
39+
* @param strideX - stride length
3540
* @returns arithmetic mean
3641
*
3742
* @example
@@ -40,15 +45,15 @@ interface Routine {
4045
* var v = mean( x.length, x, 1 );
4146
* // returns ~0.3333
4247
*/
43-
( N: number, x: NumericArray, stride: number ): number;
48+
( N: number, x: InputArray, strideX: number ): number;
4449

4550
/**
4651
* Computes the arithmetic mean of a strided array using alternative indexing semantics.
4752
*
4853
* @param N - number of indexed elements
4954
* @param x - input array
50-
* @param stride - stride length
51-
* @param offset - starting index
55+
* @param strideX - stride length
56+
* @param offsetX - starting index
5257
* @returns arithmetic mean
5358
*
5459
* @example
@@ -57,15 +62,15 @@ interface Routine {
5762
* var v = mean.ndarray( x.length, x, 1, 0 );
5863
* // returns ~0.3333
5964
*/
60-
ndarray( N: number, x: NumericArray, stride: number, offset: number ): number;
65+
ndarray( N: number, x: InputArray, strideX: number, offsetX: number ): number;
6166
}
6267

6368
/**
6469
* Computes the arithmetic mean of a strided array.
6570
*
6671
* @param N - number of indexed elements
6772
* @param x - input array
68-
* @param stride - stride length
73+
* @param strideX - stride length
6974
* @returns arithmetic mean
7075
*
7176
* @example

‎lib/node_modules/@stdlib/stats/base/mean/docs/types/test.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
* limitations under the License.
1717
*/
1818

19+
import AccessorArray = require( '@stdlib/array/base/accessor' );
1920
import mean = require( './index' );
2021

2122

@@ -26,6 +27,7 @@ import mean = require( './index' );
2627
const x = new Float64Array( 10 );
2728

2829
mean( x.length, x, 1 ); // $ExpectType number
30+
mean( x.length, new AccessorArray( x ), 1 ); // $ExpectType number
2931
}
3032

3133
// The compiler throws an error if the function is provided a first argument which is not a number...
@@ -85,6 +87,7 @@ import mean = require( './index' );
8587
const x = new Float64Array( 10 );
8688

8789
mean.ndarray( x.length, x, 1, 0 ); // $ExpectType number
90+
mean.ndarray( x.length, new AccessorArray( x ), 1, 0 ); // $ExpectType number
8891
}
8992

9093
// The compiler throws an error if the `ndarray` method is provided a first argument which is not a number...

‎lib/node_modules/@stdlib/stats/base/mean/examples/index.js‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,18 +18,12 @@
1818

1919
'use strict';
2020

21-
var randu = require( '@stdlib/random/base/randu' );
22-
var round = require( '@stdlib/math/base/special/round' );
23-
var Float64Array = require( '@stdlib/array/float64' );
21+
var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
2422
var mean = require( './../lib' );
2523

26-
var x;
27-
var i;
28-
29-
x = new Float64Array( 10 );
30-
for ( i = 0; i < x.length; i++ ) {
31-
x[ i ] = round( (randu()*100.0) - 50.0 );
32-
}
24+
var x = discreteUniform( 10, -50, 50, {
25+
'dtype': 'float64'
26+
});
3327
console.log( x );
3428

3529
var v = mean( x.length, x, 1 );

0 commit comments

Comments
 (0)