README.md (3404B)
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 # incrsummary 22 23 > Compute a statistical summary incrementally. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var incrsummary = require( '@stdlib/stats/incr/summary' ); 31 ``` 32 33 #### incrsummary() 34 35 Returns an accumulator `function` which incrementally computes a statistical summary. 36 37 ```javascript 38 var accumulator = incrsummary(); 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 = incrsummary(); 47 48 var summary = accumulator(); 49 // returns {} 50 51 summary = accumulator( 2.0 ); 52 /* returns 53 { 54 'count': 1, 55 'max': 2.0, 56 'min': 2.0, 57 'range': 0.0, 58 'midrange': 2.0, 59 'sum': 2.0, 60 'mean': 2.0, 61 'variance': 0.0, 62 'stdev': 0.0, 63 'skewness': null, 64 'kurtosis': null 65 } 66 */ 67 68 summary = accumulator( 1.0 ); 69 /* returns 70 { 71 'count': 2, 72 'max': 2.0, 73 'min': 1.0, 74 'range': 1.0, 75 'midrange': 1.5, 76 'sum': 3.0, 77 'mean': 1.5, 78 'variance': 0.5, 79 'stdev': 0.7071067811865476, 80 'skewness': null, 81 'kurtosis': null 82 } 83 */ 84 85 summary = accumulator( -3.0 ); 86 /* returns 87 { 88 'count': 3, 89 'max': 2.0, 90 'min': -3.0, 91 'range': 5.0, 92 'midrange': -0.5, 93 'sum': 0.0, 94 'mean': 0.0, 95 'variance': 7, 96 'stdev': ~2.65, 97 'skewness': ~-1.46, 98 'kurtosis': null 99 } 100 */ 101 102 summary = accumulator(); 103 /* returns 104 { 105 'count': 3, 106 'max': 2.0, 107 'min': -3.0, 108 'range': 5.0, 109 'midrange': -0.5, 110 'sum': 0.0, 111 'mean': 0.0, 112 'variance': 7, 113 'stdev': ~2.65, 114 'skewness': ~-1.46, 115 'kurtosis': null 116 } 117 */ 118 ``` 119 120 </section> 121 122 <!-- /.usage --> 123 124 <section class="notes"> 125 126 ## Notes 127 128 - 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. 129 - For long running accumulations or accumulations of large numbers, care should be taken to prevent overflow. 130 131 </section> 132 133 <!-- /.notes --> 134 135 <section class="examples"> 136 137 ## Examples 138 139 <!-- eslint no-undef: "error" --> 140 141 ```javascript 142 var randu = require( '@stdlib/random/base/randu' ); 143 var incrsummary = require( '@stdlib/stats/incr/summary' ); 144 145 var accumulator; 146 var v; 147 var i; 148 149 // Initialize an accumulator: 150 accumulator = incrsummary(); 151 152 // For each simulated datum, update the summary... 153 for ( i = 0; i < 100; i++ ) { 154 v = randu() * 100.0; 155 accumulator( v ); 156 } 157 console.log( accumulator() ); 158 ``` 159 160 </section> 161 162 <!-- /.examples --> 163 164 <section class="links"> 165 166 </section> 167 168 <!-- /.links -->