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