README.md (5941B)
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 # smskrange 22 23 > Calculate the [range][range] of a single-precision floating-point strided array according to a mask. 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 smskrange = require( '@stdlib/stats/base/smskrange' ); 39 ``` 40 41 #### smskrange( N, x, strideX, mask, strideMask ) 42 43 Computes the [range][range] of a single-precision floating-point strided array `x` according to a `mask`. 44 45 ```javascript 46 var Float32Array = require( '@stdlib/array/float32' ); 47 var Uint8Array = require( '@stdlib/array/uint8' ); 48 49 var x = new Float32Array( [ 1.0, -2.0, 4.0, 2.0 ] ); 50 var mask = new Uint8Array( [ 0, 0, 1, 0 ] ); 51 52 var v = smskrange( 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 [`Float32Array`][@stdlib/array/float32]. 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 Float32Array = require( '@stdlib/array/float32' ); 68 var Uint8Array = require( '@stdlib/array/uint8' ); 69 var floor = require( '@stdlib/math/base/special/floor' ); 70 71 var x = new Float32Array( [ 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 = smskrange( 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 Float32Array = require( '@stdlib/array/float32' ); 85 var Uint8Array = require( '@stdlib/array/uint8' ); 86 var floor = require( '@stdlib/math/base/special/floor' ); 87 88 var x0 = new Float32Array( [ 2.0, 1.0, -2.0, -2.0, 3.0, 4.0, 5.0, 6.0 ] ); 89 var x1 = new Float32Array( 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 = smskrange( N, x1, 2, mask1, 2 ); 97 // returns 6.0 98 ``` 99 100 #### smskrange.ndarray( N, x, strideX, offsetX, mask, strideMask, offsetMask ) 101 102 Computes the [range][range] of a single-precision floating-point strided array according to a `mask` and using alternative indexing semantics. 103 104 ```javascript 105 var Float32Array = require( '@stdlib/array/float32' ); 106 var Uint8Array = require( '@stdlib/array/uint8' ); 107 108 var x = new Float32Array( [ 1.0, -2.0, 4.0, 2.0 ] ); 109 var mask = new Uint8Array( [ 0, 0, 1, 0 ] ); 110 111 var v = smskrange.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 Float32Array = require( '@stdlib/array/float32' ); 124 var Uint8Array = require( '@stdlib/array/uint8' ); 125 var floor = require( '@stdlib/math/base/special/floor' ); 126 127 var x = new Float32Array( [ 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 = smskrange.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 Float32Array = require( '@stdlib/array/float32' ); 159 var Uint8Array = require( '@stdlib/array/uint8' ); 160 var smskrange = require( '@stdlib/stats/base/smskrange' ); 161 162 var mask; 163 var x; 164 var i; 165 166 x = new Float32Array( 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 x[ i ] = round( (randu()*100.0) - 50.0 ); 175 } 176 console.log( x ); 177 console.log( mask ); 178 179 var v = smskrange( x.length, x, 1, mask, 1 ); 180 console.log( v ); 181 ``` 182 183 </section> 184 185 <!-- /.examples --> 186 187 <section class="links"> 188 189 [range]: https://en.wikipedia.org/wiki/Range_%28statistics%29 190 191 [@stdlib/array/float32]: https://www.npmjs.com/package/@stdlib/array-float32 192 193 [@stdlib/array/uint8]: https://www.npmjs.com/package/@stdlib/array-uint8 194 195 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray 196 197 </section> 198 199 <!-- /.links -->