time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (5985B)

      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 # nanminBy
     22 
     23 > Calculate the minimum value of a strided array via a callback function, ignoring `NaN` values.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var nanminBy = require( '@stdlib/stats/base/nanmin-by' );
     31 ```
     32 
     33 #### nanminBy( N, x, stride, clbk\[, thisArg] )
     34 
     35 Calculates the minimum value of strided array `x` via a callback function, ignoring `NaN` values.
     36 
     37 ```javascript
     38 function accessor( v ) {
     39     return v * 2.0;
     40 }
     41 
     42 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, NaN, 0.0, -1.0, -3.0, NaN ];
     43 
     44 var v = nanminBy( x.length, x, 1, accessor );
     45 // returns -10.0
     46 ```
     47 
     48 The function has the following parameters:
     49 
     50 -   **N**: number of indexed elements.
     51 -   **x**: input [`Array`][mdn-array], [`typed array`][mdn-typed-array], or an array-like object (excluding strings and functions). 
     52 -   **stride**: index increment.
     53 -   **clbk**: callback function.
     54 -   **thisArg**: execution context (_optional_).
     55 
     56 The invoked callback is provided four arguments:
     57 
     58 -   **value**: array element.
     59 -   **aidx**: array index.
     60 -   **sidx**: strided index (`offset + aidx*stride`).
     61 -   **array**: input array/collection.
     62 
     63 To set the callback execution context, provide a `thisArg`.
     64 
     65 ```javascript
     66 function accessor( v ) {
     67     this.count += 1;
     68     return v * 2.0;
     69 }
     70 
     71 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, NaN, 0.0, -1.0, -3.0, NaN ];
     72 
     73 var context = {
     74     'count': 0
     75 };
     76 
     77 var v = nanminBy( x.length, x, 1, accessor, context );
     78 // returns -10.0
     79 
     80 var cnt = context.count;
     81 // returns 10
     82 ```
     83 
     84 The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to access every other element
     85 
     86 ```javascript
     87 var floor = require( '@stdlib/math/base/special/floor' );
     88 
     89 function accessor( v ) {
     90     return v * 2.0;
     91 }
     92 
     93 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, 0.0, -1.0, -3.0, NaN, NaN ];
     94 var N = floor( x.length / 2 );
     95 
     96 var v = nanminBy( N, x, 2, accessor );
     97 // returns -4.0
     98 ```
     99 
    100 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
    101 
    102 ```javascript
    103 var Float64Array = require( '@stdlib/array/float64' );
    104 var floor = require( '@stdlib/math/base/special/floor' );
    105 
    106 function accessor( v ) {
    107     return v * 2.0;
    108 }
    109 
    110 // Initial array...
    111 var x0 = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] );
    112 
    113 // Create an offset view...
    114 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
    115 var N = floor( x0.length/2 );
    116 
    117 // Access every other element...
    118 var v = nanminBy( N, x1, 2, accessor );
    119 // returns -12.0
    120 ```
    121 
    122 #### nanminBy.ndarray( N, x, stride, offset, clbk\[, thisArg] )
    123 
    124 Calculates the minimum value of strided array `x` via a callback function, ignoring `NaN` values and using alternative indexing semantics.
    125 
    126 ```javascript
    127 function accessor( v ) {
    128     return v * 2.0;
    129 }
    130 
    131 var x = [ -2.0, 1.0, 3.0, -5.0, 4.0, NaN, 0.0, -1.0, -3.0, NaN ];
    132 
    133 var v = nanminBy.ndarray( x.length, x, 1, 0, accessor );
    134 // returns -10.0
    135 ```
    136 
    137 The function has the following additional parameters:
    138 
    139 -   **offset**: starting index.
    140 
    141 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 access only the last three elements of `x`
    142 
    143 ```javascript
    144 function accessor( v ) {
    145     return v * 2.0;
    146 }
    147 
    148 var x = [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ];
    149 
    150 var v = nanminBy.ndarray( 3, x, 1, x.length-3, accessor );
    151 // returns -12.0
    152 ```
    153 
    154 </section>
    155 
    156 <!-- /.usage -->
    157 
    158 <section class="notes">
    159 
    160 ## Notes
    161 
    162 -   If `N <= 0`, both functions return `NaN`.
    163 -   A provided callback function should return a numeric value.
    164 -   If a provided callback function returns `NaN`, the value is ignored.
    165 -   If a provided callback function does not return any value (or equivalently, explicitly returns `undefined`), the value is ignored.
    166 -   When possible, prefer using [`dnanmin`][@stdlib/stats/base/dnanmin], [`snanmin`][@stdlib/stats/base/snanmin], and/or [`nanmin`][@stdlib/stats/base/nanmin], as, depending on the environment, these interfaces are likely to be significantly more performant.
    167 
    168 </section>
    169 
    170 <!-- /.notes -->
    171 
    172 <section class="examples">
    173 
    174 ## Examples
    175 
    176 <!-- eslint no-undef: "error" -->
    177 
    178 ```javascript
    179 var round = require( '@stdlib/math/base/special/round' );
    180 var randu = require( '@stdlib/random/base/randu' );
    181 var Float64Array = require( '@stdlib/array/float64' );
    182 var gfillBy = require( '@stdlib/blas/ext/base/gfill-by' );
    183 var nanminBy = require( '@stdlib/stats/base/nanmin-by' );
    184 
    185 function fill() {
    186     if ( randu() < 0.2 ) {
    187         return NaN;
    188     }
    189     return round( ( randu()*100.0 ) - 50.0 );
    190 }
    191 
    192 function accessor( v ) {
    193     return v * 2.0;
    194 }
    195 
    196 var x = new Float64Array( 10 );
    197 
    198 gfillBy( x.length, x, 1, fill );
    199 console.log( x );
    200 
    201 var v = nanminBy( x.length, x, 1, accessor );
    202 console.log( v );
    203 ```
    204 
    205 </section>
    206 
    207 <!-- /.examples -->
    208 
    209 <section class="links">
    210 
    211 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
    212 
    213 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    214 
    215 [@stdlib/stats/base/dnanmin]: https://www.npmjs.com/package/@stdlib/stats/tree/main/base/dnanmin
    216 
    217 [@stdlib/stats/base/nanmin]: https://www.npmjs.com/package/@stdlib/stats/tree/main/base/nanmin
    218 
    219 [@stdlib/stats/base/snanmin]: https://www.npmjs.com/package/@stdlib/stats/tree/main/base/snanmin
    220 
    221 </section>
    222 
    223 <!-- /.links -->