time-to-botec

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

README.md (3489B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 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 # incrmsummary
     22 
     23 > Compute a moving statistical summary incrementally.
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var incrmsummary = require( '@stdlib/stats/incr/msummary' );
     31 ```
     32 
     33 #### incrmsummary( window )
     34 
     35 Returns an accumulator `function` which incrementally computes a moving statistical summary. The `window` parameter defines the number of values over which to compute the moving summary.
     36 
     37 ```javascript
     38 var accumulator = incrmsummary( 3 );
     39 ```
     40 
     41 #### accumulator( \[x] )
     42 
     43 If provided an input value `x`, the accumulator function returns an updated summary. If not provided an input value `x`, the accumulator function returns the current summary.
     44 
     45 ```javascript
     46 var accumulator = incrmsummary( 3 );
     47 
     48 var summary = accumulator();
     49 // returns {}
     50 
     51 // Fill the window...
     52 summary = accumulator( 2.0 ); // [2.0]
     53 /* returns
     54     {
     55         'window': 3,
     56         'sum': 2.0,
     57         'mean': 2.0,
     58         'variance': 0.0,
     59         'stdev': 0.0,
     60         'min': 2.0,
     61         'max': 2.0,
     62         'range': 0.0,
     63         'midrange': 2.0
     64     }
     65 */
     66 
     67 summary = accumulator( 1.0 ); // [2.0, 1.0]
     68 /* returns
     69     {
     70         'window': 3,
     71         'sum': 3.0,
     72         'mean': 1.5,
     73         'variance': 0.5,
     74         'stdev': 0.7071067811865476,
     75         'min': 1.0,
     76         'max': 2.0,
     77         'range': 1.0,
     78         'midrange': 1.5
     79     }
     80 */
     81 
     82 summary = accumulator( -3.0 ); // [2.0, 1.0, -3.0]
     83 /* returns
     84     {
     85         'window': 3,
     86         'sum': 0.0,
     87         'mean': 0.0,
     88         'variance': 7.0,
     89         'stdev': 2.6457513110645907,
     90         'min': -3.0,
     91         'max': 2.0,
     92         'range': 5.0,
     93         'midrange': -0.5
     94     }
     95 */
     96 
     97 // Window begins sliding...
     98 summary = accumulator( -7.0 ); // [1.0, -3.0, -7.0]
     99 // returns {...}
    100 
    101 summary = accumulator( -5.0 ); // [-3.0, -7.0, -5.0]
    102 // returns {...}
    103 
    104 summary = accumulator();
    105 // returns {...}
    106 ```
    107 
    108 </section>
    109 
    110 <!-- /.usage -->
    111 
    112 <section class="notes">
    113 
    114 ## Notes
    115 
    116 -   Input values are **not** type checked. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function.
    117 -   As `W` values are needed to fill the window buffer, the first `W-1` returned summaries are calculated from smaller sample sizes. Until the window is full, each returned summary is calculated from all provided values.
    118 
    119 </section>
    120 
    121 <!-- /.notes -->
    122 
    123 <section class="examples">
    124 
    125 ## Examples
    126 
    127 <!-- eslint no-undef: "error" -->
    128 
    129 ```javascript
    130 var randu = require( '@stdlib/random/base/randu' );
    131 var incrmsummary = require( '@stdlib/stats/incr/msummary' );
    132 
    133 var accumulator;
    134 var v;
    135 var i;
    136 
    137 // Initialize an accumulator:
    138 accumulator = incrmsummary( 5 );
    139 
    140 // For each simulated datum, update the moving summary...
    141 for ( i = 0; i < 100; i++ ) {
    142     v = randu() * 100.0;
    143     accumulator( v );
    144 }
    145 console.log( accumulator() );
    146 ```
    147 
    148 </section>
    149 
    150 <!-- /.examples -->
    151 
    152 <section class="links">
    153 
    154 </section>
    155 
    156 <!-- /.links -->