core.md (11369B)
1 ## Core Functionality 2 3 Core functionality include methods that generate and analyse vectors or matrices. 4 5 ### jStat() 6 7 The jStat object can function in several capacities, as demonstrated below. 8 In all cases, jStat will always return an instance of itself. 9 10 **jStat( array[, fn] )** 11 12 Creates a new jStat object from either an existing array or jStat object. 13 For example, create a new jStat matrix by doing the following: 14 15 var matrix = jStat([[ 1, 2, 3 ],[ 4, 5, 6 ],[ 7, 8, 9 ]]); 16 17 If an existing jStat object is passed as an argument then it will be cloned into a new object: 18 19 var stat1 = jStat([[ 1, 2 ],[ 3, 4 ]]), 20 stat2 = jStat( stat1 ); 21 22 23 To transform the data on creation, pass a function as the final argument: 24 25 jStat([[ 1, 2 ],[ 3, 4 ]], function( x ) { 26 return x * 2; 27 }); 28 29 **jStat( start, stop, count[, fn ])** 30 31 To create a sequence then pass numeric values in the same form `jStat.seq()` would be used: 32 33 var vector = jStat( 0, 1, 5 ); 34 // vector === [[ 0, 0.25, 0.5, 0.75, 1 ]] 35 36 By passing a function the sequence value can be manipulated: 37 38 var vector = jStat( 0, 1, 5, function( x ) { 39 return x * 2; 40 }); 41 // vector === [[ 0, 0.5, 1, 1.5, 2 ]]; 42 43 The second argument passed to the function is the count (starting from 0). 44 Using this we can create a multidimensional array (useful for plotting data): 45 46 var betaGraph = jStat( 0, 1, 11, function( x, cnt ) { 47 return [ jStat.beta.pdf( x, alpha, beta ), cnt ]; 48 }); 49 50 **jStat()** 51 52 A chainable shortcut in the API exists to allow for filling in the data after object creation. 53 So creating `jStat` objects from methods like `rand()` can be accomplished in one of the following ways: 54 55 // pass the generated random 3x3 matrix to jStat 56 jStat( jStat.rand( 3 )); 57 // or create an empty instance that is filled in afterwards 58 jStat().rand( 3 ); 59 60 61 ### rows() 62 63 Returns the count of rows in a matrix. 64 65 **rows( array )** 66 67 var matrix = [[1,2,3],[4,5,6]]; 68 jStat.rows( matrix ) === 2; 69 70 **fn.rows( [callback] )** 71 72 jStat( matrix ).rows() === 2; 73 74 Or pass a callback to run the calculation asynchronously and pass on the calculation. 75 This allows for continued chaining of methods to the jStat object. 76 Also note `this` within the callback refers to the calling jStat object. 77 78 jStat( matrix ).rows(function( d ) { 79 // d === 2 80 }); 81 82 ### rowa() 83 84 Returns a array from matrix row. 85 86 rowa([[1,2],[3,4]]) === [1,2]; 87 88 ### cols() 89 90 Returns the number of columns in a matrix. 91 92 **cols( array )** 93 94 var matrix = [[1,2,3],[4,5,6]]; 95 jStat.cols( matrix ) === 3; 96 97 **fn.cols( [callback] )** 98 99 jStat( matrix ).cols() === 3; 100 101 Or pass a callback to run the calculation asynchronously and pass on the calculation. 102 This allows for continued chaining of methods to the jStat object. 103 Also note `this` within the callback refers to the calling jStat object. 104 105 jStat( matrix ).cols(function( d ) { 106 // d === 3 107 }); 108 109 ### cola() 110 111 Returns an array from matrix column (`col()` will return a matrix form instead of an array form). 112 113 cola([[1,2],[3,4]]) === [1,3]; 114 115 ### slice() 116 117 Slices matrix as numpy style. 118 119 A=[[1,2,3],[4,5,6],[7,8,9]]; 120 slice(A,{row:{end:2},col:{start:1}}) === [[2,3],[5,6]]; 121 slice(A,1,{start:1}) === [5,6]; 122 123 ### sliceAssign() 124 125 Do slice assign as numpy style. 126 127 A = [[1,2,3],[4,5,6],[7,8,9]]; 128 sliceAssign(A,{row : {start : 1}, col : {start : 1}},[[0,0],[0,0]]); 129 A = [[1,2,3],[4,0,0],[7,0,0]]; 130 131 132 ### dimensions() 133 134 Returns an object with the dimensions of a matrix. 135 136 **dimensions( array )** 137 138 var matrix = [[1,2,3],[4,5,6]]; 139 jStat.dimensions( matrix ) === { cols: 3, rows: 2 }; 140 141 **fn.dimensions( [callback] )** 142 143 jStat( matrix ).dimensions() === { cols: 3, rows: 2 }; 144 145 Or pass a callback to run the calculation asynchronously and pass on the calculation. 146 This allows for continued chaining of methods to the jStat object. 147 Also note `this` within the callback refers to the calling jStat object. 148 149 jStat( matrix ).dimensions(function( d ) { 150 // d === { cols: 3, rows: 2 } 151 }); 152 153 ### row() 154 155 Returns a specified row of a matrix. 156 157 **row( array, index )** 158 159 var matrix = [[1,2,3],[4,5,6],[7,8,9]]; 160 jStat.row( matrix, 0 ) === [1,2,3]; 161 jStat.row( matrix, [0,1] ) === [[1,2,3],[4,5,6]] 162 163 **fn.row( index[, callback] )** 164 165 jStat( matrix ).row( 0 ) === jStat([1,2,3]); 166 167 Or pass a callback to run the calculation asynchronously and pass on the calculation. 168 This allows for continued chaining of methods to the jStat object. 169 Also note `this` within the callback refers to the calling jStat object. 170 171 jStat( matrix ).row( 0, function( d ) { 172 // d === jStat([1,2,3]) 173 }); 174 175 ### col() 176 177 Returns the specified column as a column vector. 178 179 **col( index )** 180 181 var matrix = [[1,2,3],[4,5,6],[7,8,9]]; 182 jStat.col( matrix, 0 ) === [[1],[4],[7]]; 183 jStat.col( matrix,[0,1] ) === [[1,2],[4,5],[7,8]] 184 185 **fn.col( index[, callback] )** 186 187 jStat( matrix ).col( 0 ) === jStat([[1],[4],[7]]); 188 189 Or pass a callback to run the calculation asynchronously and pass on the calculation. 190 This allows for continued chaining of methods to the jStat object. 191 Also note `this` within the callback refers to the calling jStat object. 192 193 jStat( matrix ).col( 0, function( d ) { 194 // d === jStat([[1],[3]]) 195 }) 196 197 ### diag() 198 199 Returns the diagonal of a matrix. 200 201 **diag( array )** 202 203 var matrix = [[1,2,3],[4,5,6],[7,8,9]]; 204 jStat.diag( matrix ) === [[1],[5],[9]]; 205 206 **fn.diag( [callback] )** 207 208 jStat( matrix ).diag() === jStat([[1],[5],[9]]); 209 210 Or pass a callback to run the calculation asynchronously and pass on the calculation. 211 This allows for continued chaining of methods to the jStat object. 212 Also note `this` within the callback refers to the calling jStat object. 213 214 jStat( matrix ).diag(function( d ) { 215 // d === jStat([[1],[5],[9]]) 216 }); 217 218 ### antidiag() 219 220 Returns the anti-diagonal of the matrix. 221 222 **antidiag( array )** 223 224 var matrix = [[1,2,3],[4,5,6],[7,8,9]]; 225 jStat.antidiag( matrix ) === [[3],[5],[7]]; 226 227 **fn.antidiag( [callback] )** 228 229 jStat( matrix ).antidiag() === jStat([[3],[5],[7]]); 230 231 Or pass a callback to run the calculation asynchronously and pass on the calculation. 232 This allows for continued chaining of methods to the jStat object. 233 Also note `this` within the callback refers to the calling jStat object. 234 235 jStat( matrix ).antidiag(function( d ) { 236 // d === jStat([[3],[5],[7]]) 237 }); 238 239 ### diagonal() 240 241 Creates a new diagonal matrix by given 1d diag array. 242 243 jStat.diagonal([1,2,3]) === [[1,0,0],[0,2,0],[0,0,3]]; 244 245 ### transpose() 246 247 Transposes a matrix. 248 249 **transpose( array )** 250 251 var matrix = [[1,2],[3,4]]; 252 jStat.transpose( matrix ) === [[1,3],[2,4]]; 253 254 **fn.transpose( [callback] )** 255 256 jStat( matrix ).transpose() === [[1,3],[2,4]]; 257 258 Or pass a callback to run the calculation asynchronously and pass on the calculation. 259 This allows for continued chaining of methods to the jStat object. 260 Also note `this` within the callback refers to the calling jStat object. 261 262 jStat( matrix ).transpose(function( d ) { 263 // d === jStat([[1,3],[2,4]]) 264 }) 265 266 ### map( func ) 267 268 Maps a function to all values and return a new object. 269 270 **map( array, fn )** 271 272 var matrix = [[1,2],[3,4]]; 273 jStat.map( matrix, function( x ) { 274 return x * 2; 275 }); 276 // returns [[2,4],[6,8]] 277 278 **fn.map( fn )** 279 280 jStat( matrix ).map(function( x ) { 281 return x * 2; 282 }); 283 284 ### cumreduce( func ) 285 286 Cumulatively reduces values using a function and return a new object. 287 288 **cumreduce( array, fn )** 289 290 var matrix = [[1,2],[3,4]]; 291 jStat.cumreduce( matrix, function( a, b ) { 292 return a + b; 293 }); 294 // returns [[1,3],[3,7]] 295 296 **fn.cumreduce( fn )** 297 298 jStat( matrix ).cumreduce(function( a, b ) { 299 return a + b; 300 }); 301 302 ### alter( func ) 303 304 Destructively maps to an array. 305 306 **alter( array, fn )** 307 308 var matrix = [[1,2],[3,4]]; 309 jStat.alter( matrix, function( x ) { 310 return x * 2; 311 }); 312 // matrix === [[2,4],[6,8]] 313 314 **fn.alter( fn )** 315 316 var matrix = [[1,2],[3,4]]; 317 jStat( matrix ).alter( function( x ) { 318 return x * 2; 319 }); 320 321 ### create() 322 323 Creates a row by col matrix using the supplied function. 324 If `col` is omitted then it will default to value `row`. 325 326 **create( row[, col], fn )** 327 328 jStat.create( 2, function( row, col ) { 329 return row + col; 330 }); 331 // returns [[0,1],[1,2]] 332 333 **fn.create( row[, col], fn )** 334 335 Use this technique to create matrices in jStat instances. 336 337 jStat().create( 2, function( row, col ) { 338 return row + col; 339 }); 340 // returns jStat([[0,1],[1,2]]) 341 342 ### zeros() 343 344 Creates a row by col matrix of all zeros. 345 If `col` is omitted then it will default to value `row`. 346 347 **zeros( row[, col] )** 348 349 jStat.zeros( 2 ); 350 // returns [[0,0],[0,0]] 351 352 **fn.zeros( row[, col] )** 353 354 Use this technique to create matrices in jStat instances. 355 356 jStat().zeros( 2 ); 357 // returns jStat([[0,0],[0,0]]) 358 359 ### ones() 360 361 Creates a row by col matrix of all ones. 362 If `col` is omitted then it will default to value `row`. 363 364 **ones( row[, col] )** 365 366 jStat.zeros( 2 ); 367 // returns [[0,0],[0,0]] 368 369 **fn.ones( row[, col] )** 370 371 Use this technique to create matrices in jStat instances. 372 373 jStat().ones( 2 ); 374 // returns jStat([[0,0],[0,0]]) 375 376 ### rand() 377 378 Creates a matrix of normally distributed random numbers. 379 If `col` is omitted then it will default to value `row`. 380 381 **rand( row[, col] )** 382 383 jStat.rand( 3 ); 384 385 **fn.rand( row[, col] )** 386 387 Use this technique to create matrices in jStat instances. 388 389 jStat().rand( 3 ); 390 391 ### copy() 392 393 Returns a copy of given matrix. 394 395 ### identity() 396 397 Creates an identity matrix of row by col. 398 If `col` is omitted then it will default to value `row`. 399 400 **identity( row[, col] )** 401 402 jStat.identity( 2 ); 403 // returns [[1,0],[0,1]] 404 405 **fn.identity( row[, col] )** 406 407 Use this technique to create matrices in jStat instances. 408 409 jStat().identity( 2 ); 410 411 ### seq() 412 413 Creates an arithmetic sequence by given length. 414 415 jStat.seq(1,5,9) === [1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5]; 416 417 ### arange() 418 419 Creates an arithmetic sequence by given step. 420 421 arange(5) === [0,1,2,3,4] 422 arange(1,5) === [1,2,3,4] 423 arange(5,1,-1) === [5,4,3,2] 424 425 426 427 ### clear() 428 429 Sets all values in the vector or matrix to zero. 430 431 **clear( array )** 432 433 var tmp = [1,2,3]; 434 jStat.clear( tmp ); 435 // tmp === [0,0,0] 436 437 **fn.clear( [callback] )** 438 439 jStat( 0, 1, 3 ).clear(); 440 // returns [[0,0,0]] 441 442 If a callback is passed then the original object is not altered. 443 444 var obj = jStat( 0, 1, 3 ); 445 obj.clear(function() { 446 // this === [ 0, 0, 0 ] 447 }); 448 // obj === [ 0, 0.5, 1 ] 449 450 ### symmetric() 451 452 Tests if a matrix is symmetric. 453 454 **symmetric( array )** 455 456 jStat.symmetric([[1,2],[2,1]]) === true 457 458 **fn.symmetric( [callback] )** 459 460 jStat([[1,2],[2,1]]).symmetric() === true 461 462 Can pass a callback to maintain chainability. 463 464 jStat([[1,2],[2,1]]).symmetric(function( result ) { 465 // result === true 466 }); 467 468 ## jStat Utility Methods 469 470 Utilities that are used throughout the jStat library. 471 472 ### utils.calcRdx( num0, num1 ) 473 474 Calculates the decimal shift for the IEEE 754 floating point calculation correction. 475 476 ### utils.isArray( arg ) 477 478 Tests if `arg` is an array. 479 480 ### utils.isFunction( arg ) 481 482 Tests if `arg` is a function. 483 484 ### utils.isNumber( arg ) 485 486 Tests if `arg` is a number and not `NaN`.