README.md (8267B)
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 # LOWESS 22 23 > Locally-weighted polynomial regression via the LOWESS algorithm. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var lowess = require( '@stdlib/stats/lowess' ); 31 ``` 32 33 #### lowess( x, y\[, opts] ) 34 35 For [input arrays][mdn-array] and/or [typed arrays][mdn-typed-array] `x` and `y`, the function returns an object holding the ordered input values `x` and smoothed values for `y`. 36 37 <!-- eslint-disable array-element-newline --> 38 39 ```javascript 40 var x = [ 41 4, 4, 7, 7, 8, 9, 10, 10, 10, 11, 11, 12, 12, 12, 12, 13, 13, 13, 13, 14, 42 14, 14, 14, 15, 15, 15, 16, 16, 17, 17, 17, 18, 18, 18, 18, 19, 19, 19, 20, 43 20, 20, 20, 20, 22, 23, 24, 24, 24, 24, 25 44 ]; 45 var y = [ 46 2, 10, 4, 22, 16, 10, 18, 26, 34, 17, 28, 14, 20, 24, 28, 26, 34, 34, 46, 47 26, 36, 60, 80, 20, 26, 54, 32, 40, 32, 40, 50, 42, 56, 76, 84, 36, 46, 68, 48 32, 48, 52, 56, 64, 66, 54, 70, 92, 93, 120, 85 49 ]; 50 51 var out = lowess( x, y ); 52 /* returns 53 { 54 'x': [ 55 4, 56 4, 57 7, 58 7, 59 ..., 60 24, 61 24, 62 24, 63 25 64 ], 65 'y': [ 66 ~4.857, 67 ~4.857, 68 ~13.1037, 69 ~13.1037, 70 ..., 71 ~79.102, 72 ~79.102, 73 ~79.102, 74 ~84.825 75 ] 76 } 77 */ 78 ``` 79 80 The function accepts the following `options`: 81 82 - **f**: positive `number` specifying the smoothing span, i.e., the proportion of points which influence smoothing at each value. Larger values correspond to more smoothing. Default: `2/3`. 83 - **nsteps**: `number` of iterations in the robust fit (fewer iterations translates to faster function execution). If set to zero, the nonrobust fit is returned. Default: `3`. 84 - **delta**: nonnegative `number` which may be used to reduce the number of computations. Default: 1/100th of the range of `x`. 85 - **sorted**: `boolean` indicating if the input array `x` is sorted. Default: `false`. 86 87 By default, smoothing at each value is determined by `2/3` of all other points. To choose a different smoothing span, set the `f` option. 88 89 <!-- eslint-disable array-element-newline --> 90 91 ```javascript 92 var x = [ 93 4, 4, 7, 7, 8, 9, 10, 10, 10, 11, 11, 12, 12, 12, 12, 13, 13, 13, 13, 14, 94 14, 14, 14, 15, 15, 15, 16, 16, 17, 17, 17, 18, 18, 18, 18, 19, 19, 19, 20, 95 20, 20, 20, 20, 22, 23, 24, 24, 24, 24, 25 96 ]; 97 var y = [ 98 2, 10, 4, 22, 16, 10, 18, 26, 34, 17, 28, 14, 20, 24, 28, 26, 34, 34, 46, 99 26, 36, 60, 80, 20, 26, 54, 32, 40, 32, 40, 50, 42, 56, 76, 84, 36, 46, 68, 100 32, 48, 52, 56, 64, 66, 54, 70, 92, 93, 120, 85 101 ]; 102 103 var out = lowess( x, y, { 104 'f': 0.2 105 }); 106 /* returns 107 { 108 'x': [ 109 4, 110 4, 111 7, 112 ..., 113 24, 114 24, 115 25 116 ], 117 'y': [ 118 ~6.03, 119 ~6.03, 120 ~12.68, 121 ..., 122 ~82.575, 123 ~82.575, 124 ~93.028 125 ] 126 } 127 */ 128 ``` 129 130 By default, three iterations of locally weighted regression fits are calculated after the initial fit. To set a different number of iterations for the robust fit, set the `nsteps` option. 131 132 <!-- eslint-disable array-element-newline --> 133 134 ```javascript 135 var x = [ 136 4, 4, 7, 7, 8, 9, 10, 10, 10, 11, 11, 12, 12, 12, 12, 13, 13, 13, 13, 14, 137 14, 14, 14, 15, 15, 15, 16, 16, 17, 17, 17, 18, 18, 18, 18, 19, 19, 19, 20, 138 20, 20, 20, 20, 22, 23, 24, 24, 24, 24, 25 139 ]; 140 var y = [ 141 2, 10, 4, 22, 16, 10, 18, 26, 34, 17, 28, 14, 20, 24, 28, 26, 34, 34, 46, 142 26, 36, 60, 80, 20, 26, 54, 32, 40, 32, 40, 50, 42, 56, 76, 84, 36, 46, 68, 143 32, 48, 52, 56, 64, 66, 54, 70, 92, 93, 120, 85 144 ]; 145 146 var out = lowess( x, y, { 147 'nsteps': 20 148 }); 149 /* returns 150 { 151 'x': [ 152 4, 153 ..., 154 25 155 ], 156 'y': [ 157 ~4.857, 158 ..., 159 ~84.825 160 ] 161 } 162 */ 163 ``` 164 165 To save computations, set the `delta` option. For cases where one has a large number of (x,y)-pairs, carrying out regression calculations for all points is not likely to be necessary. By default, `delta` is set to 1/100th of the range of the values in `x`. In this case, if the values in `x` were uniformly scattered over the entire range, the locally weighted regression would be calculated at approximately 100 points. On the other hand, for small data sets with less than 100 observations, one can safely set the option to zero so calculations are made for each data point. 166 167 <!-- eslint-disable array-element-newline --> 168 169 ```javascript 170 var x = [ 171 4, 4, 7, 7, 8, 9, 10, 10, 10, 11, 11, 12, 12, 12, 12, 13, 13, 13, 13, 14, 172 14, 14, 14, 15, 15, 15, 16, 16, 17, 17, 17, 18, 18, 18, 18, 19, 19, 19, 20, 173 20, 20, 20, 20, 22, 23, 24, 24, 24, 24, 25 174 ]; 175 var y = [ 176 2, 10, 4, 22, 16, 10, 18, 26, 34, 17, 28, 14, 20, 24, 28, 26, 34, 34, 46, 177 26, 36, 60, 80, 20, 26, 54, 32, 40, 32, 40, 50, 42, 56, 76, 84, 36, 46, 68, 178 32, 48, 52, 56, 64, 66, 54, 70, 92, 93, 120, 85 179 ]; 180 181 var out = lowess( x, y, { 182 'delta': 0.0 183 }); 184 /* returns 185 { 186 'x': [ 187 4, 188 ..., 189 25 190 ], 191 'y': [ 192 ~4.857, 193 ..., 194 ~84.825 195 ] 196 } 197 */ 198 ``` 199 200 If the elements of `x` are sorted in ascending order, set the `sorted` option to `true`. 201 202 <!-- eslint-disable array-element-newline --> 203 204 ```javascript 205 var x = [ 206 4, 4, 7, 7, 8, 9, 10, 10, 10, 11, 11, 12, 12, 12, 12, 13, 13, 13, 13, 14, 207 14, 14, 14, 15, 15, 15, 16, 16, 17, 17, 17, 18, 18, 18, 18, 19, 19, 19, 20, 208 20, 20, 20, 20, 22, 23, 24, 24, 24, 24, 25 209 ]; 210 var y = [ 211 2, 10, 4, 22, 16, 10, 18, 26, 34, 17, 28, 14, 20, 24, 28, 26, 34, 34, 46, 212 26, 36, 60, 80, 20, 26, 54, 32, 40, 32, 40, 50, 42, 56, 76, 84, 36, 46, 68, 213 32, 48, 52, 56, 64, 66, 54, 70, 92, 93, 120, 85 214 ]; 215 216 var out = lowess( x, y, { 217 'sorted': true 218 }); 219 /* returns 220 { 221 'x': [ 222 4, 223 ..., 224 25 225 ], 226 'y': [ 227 ~4.857, 228 ..., 229 ~84.825 230 ] 231 } 232 */ 233 ``` 234 235 </section> 236 237 <!-- /.usage --> 238 239 <section class="examples"> 240 241 ## Examples 242 243 <!-- eslint no-undef: "error" --> 244 245 ```javascript 246 var randn = require( '@stdlib/random/base/randn' ); 247 var Float64Array = require( '@stdlib/array/float64' ); 248 var plot = require( '@stdlib/plot/ctor' ); 249 var lowess = require( '@stdlib/stats/lowess' ); 250 251 var x; 252 var y; 253 var i; 254 255 // Create some data... 256 x = new Float64Array( 100 ); 257 y = new Float64Array( x.length ); 258 for ( i = 0; i < x.length; i++ ) { 259 x[ i ] = i; 260 y[ i ] = ( 0.5*i ) + ( 10.0*randn() ); 261 } 262 263 var opts = { 264 'delta': 0 265 }; 266 267 var out = lowess( x, y, opts ); 268 var h = plot( [ x, out.x ], [ y, out.y ] ); 269 270 h.lineStyle = [ 'none', '-' ]; 271 h.symbols = [ 'closed-circle', 'none' ]; 272 273 h.view( 'stdout' ); 274 ``` 275 276 </section> 277 278 <!-- /.examples --> 279 280 <section class="references"> 281 282 ## References 283 284 - Cleveland, William S. 1979. "Robust Locally and Smoothing Weighted Regression Scatterplots." _Journal of the American Statistical Association_ 74 (368): 829–36. doi:[10.1080/01621459.1979.10481038][@cleveland:1979]. 285 - Cleveland, William S. 1981. "Lowess: A program for smoothing scatterplots by robust locally weighted regression." _American Statistician_ 35 (1): 54–55. doi:[10.2307/2683591][@cleveland:1981]. 286 287 </section> 288 289 <!-- /.references --> 290 291 <section class="links"> 292 293 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 294 295 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 296 297 [@cleveland:1979]: https://doi.org/10.1080/01621459.1979.10481038 298 299 [@cleveland:1981]: https://doi.org/10.2307/2683591 300 301 </section> 302 303 <!-- /.links -->