feat: add support for accessor arrays and refactor stats/base/stdevwd

lib/node_modules/@stdlib/stats/base/stdevwd/README.md

@@ -113,7 +113,7 @@ The function has the following parameters:
 
 -   **N**: number of indexed elements.
 -   **correction**: degrees of freedom adjustment. Setting this parameter to a value other than `0` has the effect of adjusting the divisor during the calculation of the [standard deviation][standard-deviation] according to `N-c` where `c` corresponds to the provided degrees of freedom adjustment. When computing the [standard deviation][standard-deviation] of a population, setting this parameter to `0` is the standard choice (i.e., the provided array contains data constituting an entire population). When computing the corrected sample [standard deviation][standard-deviation], setting this parameter to `1` is the standard choice (i.e., the provided array contains data sampled from a larger population; this is commonly referred to as Bessel's correction).
--   **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array].
+-   **x**: input [`Array`][mdn-array], [`typed array`][mdn-typed-array], or accessor array.
 -   **stride**: index increment for `x`.
 
 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [standard deviation][standard-deviation] of every other element in `x`,
@@ -172,6 +172,23 @@ var v = stdevwd.ndarray( N, 1, x, 2, 1 );
 // returns 2.5
 ```
 
+```javascript
+var stdevwd = require( '@stdlib/stats/base/stdevwd' );
+
+var accessorArray = {
+    get(i) {
+        return [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ][i];
+    },
+    set(i, v) {
+        // No-op for this example
+    },
+    length: 8
+};
+
+var v = stdevwd.ndarray( 4, 1, accessorArray, 2, 1 );
+console.log( v );
+```
+
 </section>
 
 <!-- /.usage -->
@@ -213,6 +230,25 @@ var v = stdevwd( x.length, 1, x, 1 );
 console.log( v );
 ```
 
+```javascript
+var stdevwd = require( '@stdlib/stats/base/stdevwd' );
+
+var accessorArray = {
+    get(i) {
+        return [ 1.0, -2.0, 3.0, -4.0, 5.0 ][i];
+    },
+    set(i, v) {
+        // No-op for this example
+    },
+    length: 5
+};
+
+var v = stdevwd( accessorArray.length, 1, accessorArray, 1 );
+console.log( v );
+```
+
+-   The function supports accessor arrays, which provide an alternative way to define strided arrays using `get` and `set` methods for data access.
+
 </section>
 
 <!-- /.examples -->

lib/node_modules/@stdlib/stats/base/stdevwd/benchmark/benchmark.js

@@ -31,19 +31,19 @@ var stdevwd = require( './../lib/stdevwd.js' );
 // FUNCTIONS //
 
 /**
-* Creates a benchmark function.
+* Creates a benchmark function for a native array.
 *
 * @private
 * @param {PositiveInteger} len - array length
 * @returns {Function} benchmark function
 */
-function createBenchmark( len ) {
+function createNativeBenchmark( len ) {
 	var x;
 	var i;
 
-	x = [];
+	x = new Array( len );
 	for ( i = 0; i < len; i++ ) {
-		x.push( ( randu()*20.0 ) - 10.0 );
+		x[ i ] = ( randu()*20.0 ) - 10.0;
 	}
 	return benchmark;
 
@@ -67,6 +67,51 @@ function createBenchmark( len ) {
 	}
 }
 
+/**
+* Creates a benchmark function for an accessor array.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createAccessorBenchmark( len ) {
+	var data;
+	var x;
+	var i;
+
+	data = new Array( len );
+	for ( i = 0; i < len; i++ ) {
+		data[ i ] = ( randu()*20.0 ) - 10.0;
+	}
+	x = {
+		'get': function get( i ) {
+			return data[ i ];
+		},
+		'set': function set() {},
+		'length': data.length
+	};
+	return benchmark;
+
+	function benchmark( b ) {
+		var v;
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			v = stdevwd( x.length, 1, x, 1 );
+			if ( isnan( v ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
 
 // MAIN //
 
@@ -87,9 +132,11 @@ function main() {
 
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
-		f = createBenchmark( len );
-		bench( pkg+':len='+len, f );
+		f = createNativeBenchmark( len );
+		bench( pkg+':native:len='+len, f );
+		f = createAccessorBenchmark( len );
+		bench( pkg+':accessors:len='+len, f );
 	}
 }
 
-main();
+main();

lib/node_modules/@stdlib/stats/base/stdevwd/benchmark/benchmark.ndarray.js

@@ -31,19 +31,19 @@ var stdevwd = require( './../lib/ndarray.js' );
 // FUNCTIONS //
 
 /**
-* Creates a benchmark function.
+* Creates a benchmark function for a native array.
 *
 * @private
 * @param {PositiveInteger} len - array length
 * @returns {Function} benchmark function
 */
-function createBenchmark( len ) {
+function createNativeBenchmark( len ) {
 	var x;
 	var i;
 
-	x = [];
+	x = new Array( len );
 	for ( i = 0; i < len; i++ ) {
-		x.push( ( randu()*20.0 ) - 10.0 );
+		x[ i ] = ( randu()*20.0 ) - 10.0;
 	}
 	return benchmark;
 
@@ -67,6 +67,51 @@ function createBenchmark( len ) {
 	}
 }
 
+/**
+* Creates a benchmark function for an accessor array.
+*
+* @private
+* @param {PositiveInteger} len - array length
+* @returns {Function} benchmark function
+*/
+function createAccessorBenchmark( len ) {
+	var data;
+	var x;
+	var i;
+
+	data = new Array( len );
+	for ( i = 0; i < len; i++ ) {
+		data[ i ] = ( randu()*20.0 ) - 10.0;
+	}
+	x = {
+		'get': function get( i ) {
+			return data[ i ];
+		},
+		'set': function set() {},
+		'length': data.length
+	};
+	return benchmark;
+
+	function benchmark( b ) {
+		var v;
+		var i;
+
+		b.tic();
+		for ( i = 0; i < b.iterations; i++ ) {
+			v = stdevwd( x.length, 1, x, 1, 0 );
+			if ( isnan( v ) ) {
+				b.fail( 'should not return NaN' );
+			}
+		}
+		b.toc();
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+		b.pass( 'benchmark finished' );
+		b.end();
+	}
+}
+
 
 // MAIN //
 
@@ -87,9 +132,11 @@ function main() {
 
 	for ( i = min; i <= max; i++ ) {
 		len = pow( 10, i );
-		f = createBenchmark( len );
-		bench( pkg+':ndarray:len='+len, f );
+		f = createNativeBenchmark( len );
+		bench( pkg+':ndarray:native:len='+len, f );
+		f = createAccessorBenchmark( len );
+		bench( pkg+':ndarray:accessors:len='+len, f );
 	}
 }
 
-main();
+main();

lib/node_modules/@stdlib/stats/base/stdevwd/docs/repl.txt

@@ -1,4 +1,3 @@
-
 {{alias}}( N, correction, x, stride )
     Computes the standard deviation of a strided array using Welford's
     algorithm.
@@ -7,7 +6,7 @@
     at runtime.
 
     Indexing is relative to the first index. To introduce an offset, use a typed
-    array view.
+    array view or accessor array.
 
     If `N <= 0`, the function returns `NaN`.
 
@@ -20,16 +19,16 @@
         Degrees of freedom adjustment. Setting this parameter to a value other
         than `0` has the effect of adjusting the divisor during the calculation
         of the standard deviation according to `N - c` where `c` corresponds to
-        the provided degrees of freedom adjustment. When computing the standard
+        the provided degrees of freedom adjustment.When computing the standard
         deviation of a population, setting this parameter to `0` is the standard
         choice (i.e., the provided array contains data constituting an entire
         population). When computing the corrected sample standard deviation,
         setting this parameter to `1` is the standard choice (i.e., the provided
         array contains data sampled from a larger population; this is commonly
         referred to as Bessel's correction).
 
-    x: Array<number>|TypedArray
-        Input array.
+    x: Array<number>|TypedArray|AccessorArray
+        Input array (regular, typed, or accessor array).
 
     stride: integer
         Index increment.
@@ -46,6 +45,15 @@
     > {{alias}}( x.length, 1, x, 1 )
     ~2.0817
 
+    // Using accessor array:
+    > var accessorArray = {
+    >     'get': (i) => [1.0, -2.0, 2.0][i],
+    >     'set': (i,v) => {},
+    >     'length': 3
+    > };
+    > {{alias}}( accessorArray.length, 1, accessorArray, 1 )
+    ~2.0817
+
     // Using `N` and `stride` parameters:
     > x = [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0 ];
     > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
@@ -86,8 +94,8 @@
         array contains data sampled from a larger population; this is commonly
         referred to as Bessel's correction).
 
-    x: Array<number>|TypedArray
-        Input array.
+    x: Array<number>|TypedArray|AccessorArray
+        Input array (regular, typed, or accessor array).
 
     stride: integer
         Index increment.
@@ -107,12 +115,20 @@
     > {{alias}}.ndarray( x.length, 1, x, 1, 0 )
     ~2.0817
 
+    // Using accessor array:
+    > var accessorArray = {
+    >     'get': (i) => [1.0, -2.0, 2.0][i],
+    >     'set': (i,v) => {},
+    >     'length': 3
+    > };
+    > {{alias}}.ndarray( accessorArray.length, 1, accessorArray, 1, 0 )
+    ~2.0817
+
     // Using offset parameter:
     > var x = [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ];
     > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
     > {{alias}}.ndarray( N, 1, x, 2, 1 )
     ~2.0817
 
     See Also
-    --------
-
+    --------

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

@@ -1,4 +1,4 @@
-/*
+/**
 * @license Apache-2.0
 *
 * Copyright (c) 2020 The Stdlib Authors.
@@ -22,6 +22,26 @@
 
 import { NumericArray } from '@stdlib/types/array';
 
+/**
+* Interface describing an accessor array.
+*/
+interface AccessorArray {
+	/**
+	* Returns an array element.
+	*/
+	get( index: number ): number;
+
+	/**
+	* Sets an array element.
+	*/
+	set( index: number, value: number ): void;
+
+	/**
+	* Number of elements.
+	*/
+	length: number;
+}
+
 /**
 * Interface describing `stdevwd`.
 */
@@ -85,7 +105,5 @@ interface Routine {
 */
 declare var stdevwd: Routine;
 
-
 // EXPORTS //
-
-export = stdevwd;
+export = stdevwd;