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