README.md (6749B)
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 # kde2d 22 23 > Two-dimensional kernel density estimation. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var kde2d = require( '@stdlib/stats/kde2d' ); 31 ``` 32 33 #### kde2d( x, y\[, opts] ) 34 35 By default, the function computes two-dimensional normal kernel density estimation for data provided in [arrays][mdn-array] or [typed-arrays][mdn-typed-array] `x` and `y`. When these arguments are supplied, the arrays are coerced into a Matrix-like object. 36 37 <!-- eslint-disable array-element-newline --> 38 39 ```javascript 40 var x = [ 0.6333, 0.8643, 1.0952, 1.3262, 1.5571, 41 1.7881, 2.019, 2.25, 2.481, 2.7119 ]; 42 var y = [ -0.0468, 0.8012, 1.6492, 2.4973, 3.3454, 43 4.1934, 5.0415, 5.8896, 6.7376, 7.5857 ]; 44 45 var out = kde2d( x, y ); 46 /* e.g., returns 47 { 48 'x': [ ~0.633, ~0.72, ... ], 49 'y': [ ~-0.047, ~0.271 ... ], 50 'z': ndarray{ <Float64Array>[ ~0.0455, ... ]} 51 } 52 */ 53 ``` 54 55 #### kde2d( arr\[, opts] ) 56 57 The function has the ability to handle [ndarrays][nd-array]. Specifically the `ndarray` must be constructed so that there are two columns present, the first column containing the `x` values and the second column containing the `y` values. 58 59 Note that for the output the `x` and `y` properties refer to the equally spaced gridpoints of `X` and `Y` used to calculate `z`. 60 61 <!-- eslint-disable array-element-newline --> 62 63 ```javascript 64 var ndarray = require( '@stdlib/ndarray/ctor' ); 65 66 var x = [ 0.6333, 0.8643, 1.0952, 1.3262, 1.5571, 67 1.7881, 2.019, 2.25, 2.481, 2.7119 ]; 68 var y = [ -0.0468, 0.8012, 1.6492, 2.4973, 3.3454, 69 4.1934, 5.0415, 5.8896, 6.7376, 7.5857 ]; 70 71 var buffer = x.concat( y ); 72 var n = x.length; 73 var shape = [ n, 2 ]; 74 var strides = [ 1, n ]; 75 var offset = 0; 76 var order = 'column-major'; 77 78 var arr = ndarray( 'generic', buffer, shape, strides, offset, order ); 79 80 var out = kde2d( arr ); 81 /* e.g., returns 82 { 83 'x': [ ~0.633, ~0.72, ... ], 84 'y': [ ~-0.047,~ 0.271, ... ], 85 'z': ndarray{ <Float64Array>[0.04547178438418015, ... ]} 86 } 87 */ 88 ``` 89 90 The function accepts the following `options`: 91 92 - **h**: `NumberArray` of length 2 indicating the X and Y bandwidth values, respectively. 93 - **n**: A positive `integer` indicating the number of partitions to create in the grid. Default: `25`. 94 - **xMin**: A `number` indicating the lower bound of X. Must be strictly less than `xMax`. Will default to the minimum value of `X`. 95 - **xMax**: A `number` indicating the lower bound of X. Must be strictly greater than `xMin`. Will default to the maximum value of `X`. 96 - **yMin**: A `number` indicating the lower bound of X. Must be strictly less than `yMax`. Will default to the minimum value of `Y`. 97 - **yMax**: A `number` indicating the lower bound of X. Must be strictly greater than `yMin`. Will default to the maximum value of `Y`. 98 - **kernel**: A `string` or `function` indicating the kernel to be used when calculating the estimation. If a `string` is supplied then it will be matched to a pre-defined kernel function. Otherwise you may supply a function to support custom kernels. Will default to the `gaussian` kernel. 99 100 By default, the bandwidth argument is set by a builtin function. To choose different bandwidth values, set the `h` option. Note that if you use a custom bandwidth for one axis, you must also use a custom bandwidth for the other axis. 101 102 <!-- eslint-disable array-element-newline --> 103 104 ```javascript 105 var x = [ 0.6333, 0.8643, 1.0952, 1.3262, 1.5571, 106 1.7881, 2.019, 2.25, 2.481, 2.7119 ]; 107 var y = [ -0.0468, 0.8012, 1.6492, 2.4973, 3.3454, 108 4.1934, 5.0415, 5.8896, 6.7376, 7.5857 ]; 109 110 var out = kde2d( x, y, { 111 'h': [ 0.05, 0.1 ] 112 }); 113 /* e.g., returns 114 { 115 'x': [ 0.148, 0.3772, ... ], 116 'y': [ -1.1511, -0.253, ... ], 117 'z': ndarray{ <Float64Array>[ 6.344e-154, 1.93e-171, ... ]} 118 } 119 */ 120 ``` 121 122 By default, we use `25` partitions. To change the number of partitions, set the `n` option. 123 124 <!-- eslint-disable array-element-newline --> 125 126 ```javascript 127 var x = [ 0.6333, 0.8643, 1.0952, 1.3262, 1.5571, 128 1.7881, 2.019, 2.25, 2.481, 2.7119 ]; 129 var y = [ -0.0468, 0.8012, 1.6492, 2.4973, 3.3454, 130 4.1934, 5.0415, 5.8896, 6.7376, 7.5857 ]; 131 132 var out = kde2d( x, y, { 133 'n': 15 134 }); 135 /* e.g., returns 136 { 137 'x': [ 0.0623, 0.452, ... ], 138 'y': [ 0.1378, 1.6266, ... ], 139 'z': ndarray{ <Float64Array>[1.211e-7, 5.76e-7, ... ]} 140 } 141 */ 142 ``` 143 144 As a default choice, the `kde2d` function sets the `xMin`, `xMax`, `yMin` and `yMax` values to be the minimum and maximum of the `X` and `Y` arrays or columns of the supplied arguments. We may change the options as follows: 145 146 <!-- eslint-disable array-element-newline --> 147 148 ```javascript 149 var x = [ 0.6333, 0.8643, 1.0952, 1.3262, 1.5571, 150 1.7881, 2.019, 2.25, 2.481, 2.7119 ]; 151 var y = [ -0.0468, 0.8012, 1.6492, 2.4973, 3.3454, 152 4.1934, 5.0415, 5.8896, 6.7376, 7.5857 ]; 153 154 var out = kde2d( x, y, { 155 'xMin': 0.0, 156 'xMax': 2.5, 157 'yMin': 0.0, 158 'yMax': 6.0 159 }); 160 /* e.g., returns 161 { 162 'x': [ 0, 0.1041, ... ], 163 'y': [ 0, 0.25, ... ], 164 'z': ndarray{ <Float64Array>[ 1.762e-8, 2.94e-8, ... ]} 165 } 166 */ 167 ``` 168 169 </section> 170 171 <!-- /.usage --> 172 173 <section class="examples"> 174 175 ## Examples 176 177 <!-- eslint no-undef: "error" --> 178 179 ```javascript 180 var normal = require( '@stdlib/random/base/normal' ); 181 var kde2d = require( '@stdlib/stats/kde2d' ); 182 183 var randX; 184 var randY; 185 var out; 186 var i; 187 var x; 188 var y; 189 var n; 190 191 n = 100; 192 193 x = new Array( n ); 194 y = new Array( n ); 195 196 randX = normal.factory( 3.0, 1.2 ); 197 randY = normal.factory( 10.0, 4.5 ); 198 199 for ( i = 0; i < n; i++ ) { 200 x[ i ] = randX(); 201 y[ i ] = randY(); 202 } 203 204 out = kde2d( x, y ); 205 /* e.g., returns 206 { 207 'x': [0.022, 0.2614, ...], 208 'y': [-4.533, 3.602, ...], 209 'z': ndarray { Float64Array [9.8266e-11, 6.45e-9, ...]} 210 } 211 */ 212 ``` 213 214 </section> 215 216 <!-- /.examples --> 217 218 <section class="links"> 219 220 [mdn-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 221 222 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Typed_arrays 223 224 [nd-array]: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/@stdlib/ndarray/ctor/README.md 225 226 </section> 227 228 <!-- /.links -->