README.md (6137B)
1 <!-- 2 3 @license Apache-2.0 4 5 Copyright (c) 2020 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 # dnanmskrange 22 23 > Calculate the [range][range] of a double-precision floating-point strided array according to a mask, ignoring `NaN` values. 24 25 <section class="intro"> 26 27 The [**range**][range] is defined as the difference between the maximum and minimum values. 28 29 </section> 30 31 <!-- /.intro --> 32 33 <section class="usage"> 34 35 ## Usage 36 37 ```javascript 38 var dnanmskrange = require( '@stdlib/stats/base/dnanmskrange' ); 39 ``` 40 41 #### dnanmskrange( N, x, strideX, mask, strideMask ) 42 43 Computes the [range][range] of a double-precision floating-point strided array `x` according to a `mask`, ignoring `NaN` values. 44 45 ```javascript 46 var Float64Array = require( '@stdlib/array/float64' ); 47 var Uint8Array = require( '@stdlib/array/uint8' ); 48 49 var x = new Float64Array( [ 1.0, -2.0, 4.0, 2.0, NaN ] ); 50 var mask = new Uint8Array( [ 0, 0, 1, 0, 0 ] ); 51 52 var v = dnanmskrange( x.length, x, 1, mask, 1 ); 53 // returns 4.0 54 ``` 55 56 The function has the following parameters: 57 58 - **N**: number of indexed elements. 59 - **x**: input [`Float64Array`][@stdlib/array/float64]. 60 - **strideX**: index increment for `x`. 61 - **mask**: mask [`Uint8Array`][@stdlib/array/uint8]. If a `mask` array element is `0`, the corresponding element in `x` is considered valid and **included** in computation. If a `mask` array element is `1`, the corresponding element in `x` is considered invalid/missing and **excluded** from computation. 62 - **strideMask**: index increment for `mask`. 63 64 The `N` and `stride` parameters determine which elements are accessed at runtime. For example, to compute the [range][range] of every other element in `x`, 65 66 ```javascript 67 var Float64Array = require( '@stdlib/array/float64' ); 68 var Uint8Array = require( '@stdlib/array/uint8' ); 69 var floor = require( '@stdlib/math/base/special/floor' ); 70 71 var x = new Float64Array( [ 1.0, 2.0, -7.0, -2.0, 4.0, 3.0, 5.0, 6.0 ] ); 72 var mask = new Uint8Array( [ 0, 0, 0, 0, 0, 0, 1, 1 ] ); 73 var N = floor( x.length / 2 ); 74 75 var v = dnanmskrange( N, x, 2, mask, 2 ); 76 // returns 11.0 77 ``` 78 79 Note that indexing is relative to the first index. To introduce offsets, use [`typed array`][mdn-typed-array] views. 80 81 <!-- eslint-disable stdlib/capitalized-comments --> 82 83 ```javascript 84 var Float64Array = require( '@stdlib/array/float64' ); 85 var Uint8Array = require( '@stdlib/array/uint8' ); 86 var floor = require( '@stdlib/math/base/special/floor' ); 87 88 var x0 = new Float64Array( [ 2.0, 1.0, -2.0, -2.0, 3.0, 4.0, 5.0, 6.0 ] ); 89 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 90 91 var mask0 = new Uint8Array( [ 0, 0, 0, 0, 0, 0, 1, 1 ] ); 92 var mask1 = new Uint8Array( mask0.buffer, mask0.BYTES_PER_ELEMENT*1 ); // start at 2nd element 93 94 var N = floor( x0.length / 2 ); 95 96 var v = dnanmskrange( N, x1, 2, mask1, 2 ); 97 // returns 6.0 98 ``` 99 100 #### dnanmskrange.ndarray( N, x, strideX, offsetX, mask, strideMask, offsetMask ) 101 102 Computes the [range][range] of a double-precision floating-point strided array according to a `mask`, ignoring `NaN` values and using alternative indexing semantics. 103 104 ```javascript 105 var Float64Array = require( '@stdlib/array/float64' ); 106 var Uint8Array = require( '@stdlib/array/uint8' ); 107 108 var x = new Float64Array( [ 1.0, -2.0, 4.0, 2.0, NaN ] ); 109 var mask = new Uint8Array( [ 0, 0, 1, 0, 0 ] ); 110 111 var v = dnanmskrange.ndarray( x.length, x, 1, 0, mask, 1, 0 ); 112 // returns 4.0 113 ``` 114 115 The function has the following additional parameters: 116 117 - **offsetX**: starting index for `x`. 118 - **offsetMask**: starting index for `mask`. 119 120 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 [range][range] for every other value in `x` starting from the second value 121 122 ```javascript 123 var Float64Array = require( '@stdlib/array/float64' ); 124 var Uint8Array = require( '@stdlib/array/uint8' ); 125 var floor = require( '@stdlib/math/base/special/floor' ); 126 127 var x = new Float64Array( [ 2.0, 1.0, -2.0, -2.0, 3.0, 4.0, 5.0, 6.0 ] ); 128 var mask = new Uint8Array( [ 0, 0, 0, 0, 0, 0, 1, 1 ] ); 129 var N = floor( x.length / 2 ); 130 131 var v = dnanmskrange.ndarray( N, x, 2, 1, mask, 2, 1 ); 132 // returns 6.0 133 ``` 134 135 </section> 136 137 <!-- /.usage --> 138 139 <section class="notes"> 140 141 ## Notes 142 143 - If `N <= 0`, both functions return `NaN`. 144 145 </section> 146 147 <!-- /.notes --> 148 149 <section class="examples"> 150 151 ## Examples 152 153 <!-- eslint no-undef: "error" --> 154 155 ```javascript 156 var randu = require( '@stdlib/random/base/randu' ); 157 var round = require( '@stdlib/math/base/special/round' ); 158 var Float64Array = require( '@stdlib/array/float64' ); 159 var Uint8Array = require( '@stdlib/array/uint8' ); 160 var dnanmskrange = require( '@stdlib/stats/base/dnanmskrange' ); 161 162 var mask; 163 var x; 164 var i; 165 166 x = new Float64Array( 10 ); 167 mask = new Uint8Array( x.length ); 168 for ( i = 0; i < x.length; i++ ) { 169 if ( randu() < 0.2 ) { 170 mask[ i ] = 1; 171 } else { 172 mask[ i ] = 0; 173 } 174 if ( randu() < 0.1 ) { 175 x[ i ] = NaN; 176 } else { 177 x[ i ] = round( (randu()*100.0) - 50.0 ); 178 } 179 } 180 console.log( x ); 181 console.log( mask ); 182 183 var v = dnanmskrange( x.length, x, 1, mask, 1 ); 184 console.log( v ); 185 ``` 186 187 </section> 188 189 <!-- /.examples --> 190 191 <section class="links"> 192 193 [range]: https://en.wikipedia.org/wiki/Range_%28statistics%29 194 195 [@stdlib/array/float64]: https://www.npmjs.com/package/@stdlib/array-float64 196 197 [@stdlib/array/uint8]: https://www.npmjs.com/package/@stdlib/array-uint8 198 199 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 200 201 </section> 202 203 <!-- /.links -->