Skip to content

Commit db90eb5

Browse files
committed
Add accessor protocol support and refactored @stdlib/stats/base/nanvariancech
1 parent 9e91f81 commit db90eb5

File tree

12 files changed

+597
-369
lines changed

12 files changed

+597
-369
lines changed

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

+14-29
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ The use of the term `n-1` is commonly referred to as Bessel's correction. Note,
9898
var nanvariancech = require( '@stdlib/stats/base/nanvariancech' );
9999
```
100100

101-
#### nanvariancech( N, correction, x, stride )
101+
#### nanvariancech( N, correction, x, strideX )
102102

103103
Computes the [variance][variance] of a strided array `x` ignoring `NaN` values and using a one-pass trial mean algorithm.
104104

@@ -114,17 +114,14 @@ The function has the following parameters:
114114
- **N**: number of indexed elements.
115115
- **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 [variance][variance] according to `n-c` where `c` corresponds to the provided degrees of freedom adjustment and `n` corresponds to the number of non-`NaN` indexed elements. When computing the [variance][variance] 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 unbiased sample [variance][variance], 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).
116116
- **x**: input [`Array`][mdn-array] or [`typed array`][mdn-typed-array].
117-
- **stride**: index increment for `x`.
117+
- **strideX**: stride length for `x`.
118118

119-
The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the [variance][variance] of every other element in `x`,
119+
The `N` and stride parameters determine which elements in the stided array are accessed at runtime. For example, to compute the [variance][variance] of every other element in `x`,
120120

121121
```javascript
122-
var floor = require( '@stdlib/math/base/special/floor' );
123-
124122
var x = [ 1.0, 2.0, 2.0, -7.0, -2.0, 3.0, 4.0, 2.0, NaN ];
125-
var N = floor( x.length / 2 );
126123

127-
var v = nanvariancech( N, 1, x, 2 );
124+
var v = nanvariancech( 4, 1, x, 2 );
128125
// returns 6.25
129126
```
130127

@@ -134,41 +131,35 @@ Note that indexing is relative to the first index. To introduce an offset, use [
134131

135132
```javascript
136133
var Float64Array = require( '@stdlib/array/float64' );
137-
var floor = require( '@stdlib/math/base/special/floor' );
138134

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

142-
var N = floor( x0.length / 2 );
143-
144-
var v = nanvariancech( N, 1, x1, 2 );
138+
var v = nanvariancech( 4, 1, x1, 2 );
145139
// returns 6.25
146140
```
147141

148-
#### nanvariancech.ndarray( N, correction, x, stride, offset )
142+
#### nanvariancech.ndarray( N, correction, x, strideX, offsetX )
149143

150144
Computes the [variance][variance] of a strided array ignoring `NaN` values and using a one-pass trial mean algorithm and alternative indexing semantics.
151145

152146
```javascript
153147
var x = [ 1.0, -2.0, NaN, 2.0 ];
154148

155-
var v = nanvariancech.ndarray( x.length, 1, x, 1, 0 );
149+
var v = nanvariancech.ndarray( 4, 1, x, 1, 0 );
156150
// returns ~4.33333
157151
```
158152

159153
The function has the following additional parameters:
160154

161-
- **offset**: starting index for `x`.
155+
- **offsetX**: starting index for `x`.
162156

163-
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 [variance][variance] for every other value in `x` starting from the second value
157+
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 [variance][variance] for every other element in the strided array starting from the second element
164158

165159
```javascript
166-
var floor = require( '@stdlib/math/base/special/floor' );
167-
168160
var x = [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ];
169-
var N = floor( x.length / 2 );
170161

171-
var v = nanvariancech.ndarray( N, 1, x, 2, 1 );
162+
var v = nanvariancech.ndarray( 4, 1, x, 2, 1 );
172163
// returns 6.25
173164
```
174165

@@ -183,6 +174,7 @@ var v = nanvariancech.ndarray( N, 1, x, 2, 1 );
183174
- If `N <= 0`, both functions return `NaN`.
184175
- If `n - c` is less than or equal to `0` (where `c` corresponds to the provided degrees of freedom adjustment and `n` corresponds to the number of non-`NaN` indexed elements), both functions return `NaN`.
185176
- The underlying algorithm is a specialized case of Neely's two-pass algorithm. As the variance is invariant with respect to changes in the location parameter, the underlying algorithm uses the first non-`NaN` strided array element as a trial mean to shift subsequent data values and thus mitigate catastrophic cancellation. Accordingly, the algorithm's accuracy is best when data is **unordered** (i.e., the data is **not** sorted in either ascending or descending order such that the first value is an "extreme" value).
177+
- 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]).
186178
- Depending on the environment, the typed versions ([`dnanvariancech`][@stdlib/stats/base/dnanvariancech], [`snanvariancech`][@stdlib/stats/base/snanvariancech], etc.) are likely to be significantly more performant.
187179

188180
</section>
@@ -196,18 +188,11 @@ var v = nanvariancech.ndarray( N, 1, x, 2, 1 );
196188
<!-- eslint no-undef: "error" -->
197189

198190
```javascript
199-
var randu = require( '@stdlib/random/base/randu' );
200-
var round = require( '@stdlib/math/base/special/round' );
201-
var Float64Array = require( '@stdlib/array/float64' );
191+
var normal = require( '@stdlib/random/array/normal' );
202192
var nanvariancech = require( '@stdlib/stats/base/nanvariancech' );
203193

204-
var x;
205-
var i;
206-
207-
x = new Float64Array( 10 );
208-
for ( i = 0; i < x.length; i++ ) {
209-
x[ i ] = round( (randu()*100.0) - 50.0 );
210-
}
194+
var x = normal( 10, 0, 1 );
195+
x[4] = NaN;
211196
console.log( x );
212197

213198
var v = nanvariancech( x.length, 1, x, 1 );

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

+6-12
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var normal = require( '@stdlib/random/array/normal' );
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;
@@ -37,18 +37,12 @@ var nanvariancech = require( './../lib/nanvariancech.js' );
3737
* @param {PositiveInteger} len - array length
3838
* @returns {Function} benchmark function
3939
*/
40-
function createBenchmark( len ) {
41-
var x;
42-
var i;
40+
function createBenchmark() {
41+
var x = normal( 10, 0, 1, {
42+
'dtype': 'float64'
43+
});
44+
x[4] = NaN;
4345

44-
x = [];
45-
for ( i = 0; i < len; i++ ) {
46-
if ( randu() < 0.2 ) {
47-
x.push( NaN );
48-
} else {
49-
x.push( ( randu()*20.0 ) - 10.0 );
50-
}
51-
}
5246
return benchmark;
5347

5448
function benchmark( b ) {

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

+6-12
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var normal = require( '@stdlib/random/array/normal' );
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;
@@ -37,18 +37,12 @@ var nanvariancech = require( './../lib/ndarray.js' );
3737
* @param {PositiveInteger} len - array length
3838
* @returns {Function} benchmark function
3939
*/
40-
function createBenchmark( len ) {
41-
var x;
42-
var i;
40+
function createBenchmark() {
41+
var x = normal( 10, 0, 1, {
42+
'dtype': 'float64'
43+
});
44+
x[4] = NaN;
4345

44-
x = [];
45-
for ( i = 0; i < len; i++ ) {
46-
if ( randu() < 0.2 ) {
47-
x.push( NaN );
48-
} else {
49-
x.push( ( randu()*20.0 ) - 10.0 );
50-
}
51-
}
5246
return benchmark;
5347

5448
function benchmark( b ) {

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

+13-16
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11

2-
{{alias}}( N, correction, x, stride )
2+
{{alias}}( N, correction, x, strideX )
33
Computes the variance of a strided array ignoring `NaN` values and using a
44
one-pass trial mean algorithm.
55

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

99
Indexing is relative to the first index. To introduce an offset, use a typed
@@ -34,8 +34,8 @@
3434
x: Array<number>|TypedArray
3535
Input array.
3636

37-
stride: integer
38-
Index increment.
37+
strideX: integer
38+
stride length.
3939

4040
Returns
4141
-------
@@ -46,25 +46,23 @@
4646
--------
4747
// Standard Usage:
4848
> var x = [ 1.0, -2.0, NaN, 2.0 ];
49-
> {{alias}}( x.length, 1, x, 1 )
49+
> {{alias}}( 4, 1, x, 1 )
5050
~4.3333
5151

5252
// Using `N` and `stride` parameters:
5353
> x = [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0 ];
54-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
5554
> var stride = 2;
56-
> {{alias}}( N, 1, x, stride )
55+
> {{alias}}( 3, 1, x, stride )
5756
~4.3333
5857

5958
// Using view offsets:
6059
> var x0 = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ] );
6160
> var x1 = new {{alias:@stdlib/array/float64}}( x0.buffer, x0.BYTES_PER_ELEMENT*1 );
62-
> N = {{alias:@stdlib/math/base/special/floor}}( x0.length / 2 );
6361
> stride = 2;
64-
> {{alias}}( N, 1, x1, stride )
62+
> {{alias}}( 3, 1, x1, stride )
6563
~4.3333
6664

67-
{{alias}}.ndarray( N, correction, x, stride, offset )
65+
{{alias}}.ndarray( N, correction, x, strideX, offsetX )
6866
Computes the variance of a strided array ignoring `NaN` values and using a
6967
one-pass trial mean algorithm and alternative indexing semantics.
7068

@@ -93,10 +91,10 @@
9391
x: Array<number>|TypedArray
9492
Input array.
9593

96-
stride: integer
97-
Index increment.
94+
strideX: integer
95+
stride length.
9896

99-
offset: integer
97+
offsetX: integer
10098
Starting index.
10199

102100
Returns
@@ -108,13 +106,12 @@
108106
--------
109107
// Standard Usage:
110108
> var x = [ 1.0, -2.0, NaN, 2.0 ];
111-
> {{alias}}.ndarray( x.length, 1, x, 1, 0 )
109+
> {{alias}}.ndarray( 4, 1, x, 1, 0 )
112110
~4.3333
113111

114112
// Using offset parameter:
115113
> var x = [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ];
116-
> var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 );
117-
> {{alias}}.ndarray( N, 1, x, 2, 1 )
114+
> {{alias}}.ndarray( 3, 1, x, 2, 1 )
118115
~4.3333
119116

120117
See Also

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

+12-7
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 `nanvariancech`.
@@ -32,7 +37,7 @@ interface Routine {
3237
* @param N - number of indexed elements
3338
* @param correction - degrees of freedom adjustment
3439
* @param x - input array
35-
* @param stride - stride length
40+
* @param strideX - stride length
3641
* @returns variance
3742
*
3843
* @example
@@ -41,16 +46,16 @@ interface Routine {
4146
* var v = nanvariancech( x.length, 1, x, 1 );
4247
* // returns ~4.3333
4348
*/
44-
( N: number, correction: number, x: NumericArray, stride: number ): number;
49+
( N: number, correction: number, x: InputArray, strideX: number ): number;
4550

4651
/**
4752
* Computes the variance of a strided array ignoring `NaN` values and using a one-pass trial mean algorithm and alternative indexing semantics.
4853
*
4954
* @param N - number of indexed elements
5055
* @param correction - degrees of freedom adjustment
5156
* @param x - input array
52-
* @param stride - stride length
53-
* @param offset - starting index
57+
* @param strideX - stride length
58+
* @param offsetX - starting index
5459
* @returns variance
5560
*
5661
* @example
@@ -59,7 +64,7 @@ interface Routine {
5964
* var v = nanvariancech.ndarray( x.length, 1, x, 1, 0 );
6065
* // returns ~4.3333
6166
*/
62-
ndarray( N: number, correction: number, x: NumericArray, stride: number, offset: number ): number;
67+
ndarray( N: number, correction: number, x: InputArray, strideX: number, offset: number ): number;
6368
}
6469

6570
/**
@@ -68,7 +73,7 @@ interface Routine {
6873
* @param N - number of indexed elements
6974
* @param correction - degrees of freedom adjustment
7075
* @param x - input array
71-
* @param stride - stride length
76+
* @param strideX - stride length
7277
* @returns variance
7378
*
7479
* @example

0 commit comments

Comments
 (0)