-
-
Notifications
You must be signed in to change notification settings - Fork 403
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add pkg to incrementally compute a moving correlation coefficient
- Loading branch information
Showing
8 changed files
with
1,769 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,130 @@ | ||
<!-- | ||
@license Apache-2.0 | ||
Copyright (c) 2018 The Stdlib Authors. | ||
Licensed under the Apache License, Version 2.0 (the "License"); | ||
you may not use this file except in compliance with the License. | ||
You may obtain a copy of the License at | ||
http://www.apache.org/licenses/LICENSE-2.0 | ||
Unless required by applicable law or agreed to in writing, software | ||
distributed under the License is distributed on an "AS IS" BASIS, | ||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
See the License for the specific language governing permissions and | ||
limitations under the License. | ||
--> | ||
|
||
# incrmpcorr | ||
|
||
> Compute a moving [sample Pearson product-moment correlation coefficient][pearson-correlation] incrementally. | ||
<section class="usage"> | ||
|
||
## Usage | ||
|
||
```javascript | ||
var incrmpcorr = require( '@stdlib/stats/incr/mpcorr' ); | ||
``` | ||
|
||
#### incrmpcorr( window\[, mx, my] ) | ||
|
||
Returns an accumulator `function` which incrementally computes a moving [sample Pearson product-moment correlation coefficient][pearson-correlation]. The `window` parameter defines the number of values over which to compute the moving [sample Pearson product-moment correlation coefficient][pearson-correlation]. | ||
|
||
```javascript | ||
var accumulator = incrmpcorr( 3 ); | ||
``` | ||
|
||
If means are already known, provide `mx` and `my` arguments. | ||
|
||
```javascript | ||
var accumulator = incrmpcorr( 3, 5.0, -3.14 ); | ||
``` | ||
|
||
#### accumulator( \[x, y] ) | ||
|
||
If provided input values `x` and `y`, the accumulator function returns an updated [sample Pearson product-moment correlation coefficient][pearson-correlation]. If not provided input values `x` and `y`, the accumulator function returns the current [sample Pearson product-moment correlation coefficient][pearson-correlation]. | ||
|
||
```javascript | ||
var accumulator = incrmpcorr( 3 ); | ||
|
||
var r = accumulator(); | ||
// returns null | ||
|
||
// Fill the window... | ||
r = accumulator( 2.0, 1.0 ); // [(2.0, 1.0)] | ||
// returns 0.0 | ||
|
||
r = accumulator( -5.0, 3.14 ); // [(2.0, 1.0), (-5.0, 3.14)] | ||
// returns ~-1.0 | ||
|
||
r = accumulator( 3.0, -1.0 ); // [(2.0, 1.0), (-5.0, 3.14), (3.0, -1.0)] | ||
// returns ~-0.925 | ||
|
||
// Window begins sliding... | ||
r = accumulator( 5.0, -9.5 ); // [(-5.0, 3.14), (3.0, -1.0), (5.0, -9.5)] | ||
// returns ~-0.863 | ||
|
||
r = accumulator( -5.0, 1.5 ); // [(3.0, -1.0), (5.0, -9.5), (-5.0, 1.5)] | ||
// returns ~-0.803 | ||
|
||
r = accumulator(); | ||
// returns ~-0.803 | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.usage --> | ||
|
||
<section class="notes"> | ||
|
||
## Notes | ||
|
||
- Input values are **not** type checked. If provided `NaN` or a value which, when used in computations, results in `NaN`, the accumulated value is `NaN` for **at least** `W-1` future invocations. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function. | ||
- The first `W-1` returned [sample correlation coefficients][pearson-correlation] will have less statistical support than subsequent [sample correlation coefficients][pearson-correlation], as `W` (x,y) pairs are needed to fill the window buffer. Until the window is full, the returned [sample correlation coefficient][pearson-correlation] equals the [sample correlation coefficient][pearson-correlation] of all provided values. | ||
|
||
</section> | ||
|
||
<!-- /.notes --> | ||
|
||
<section class="examples"> | ||
|
||
## Examples | ||
|
||
<!-- eslint no-undef: "error" --> | ||
|
||
```javascript | ||
var randu = require( '@stdlib/random/base/randu' ); | ||
var incrmpcorr = require( '@stdlib/stats/incr/mpcorr' ); | ||
|
||
var accumulator; | ||
var x; | ||
var y; | ||
var i; | ||
|
||
// Initialize an accumulator: | ||
accumulator = incrmpcorr( 5 ); | ||
|
||
// For each simulated datum, update the moving sample correlation coefficient... | ||
for ( i = 0; i < 100; i++ ) { | ||
x = randu() * 100.0; | ||
y = randu() * 100.0; | ||
accumulator( x, y ); | ||
} | ||
console.log( accumulator() ); | ||
``` | ||
|
||
</section> | ||
|
||
<!-- /.examples --> | ||
|
||
<section class="links"> | ||
|
||
[pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient | ||
|
||
</section> | ||
|
||
<!-- /.links --> |
91 changes: 91 additions & 0 deletions
91
lib/node_modules/@stdlib/stats/incr/mpcorr/benchmark/benchmark.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2018 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
// MODULES // | ||
|
||
var bench = require( '@stdlib/bench' ); | ||
var randu = require( '@stdlib/random/base/randu' ); | ||
var pkg = require( './../package.json' ).name; | ||
var incrmpcorr = require( './../lib' ); | ||
|
||
|
||
// MAIN // | ||
|
||
bench( pkg, function benchmark( b ) { | ||
var f; | ||
var i; | ||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
f = incrmpcorr( (i%5)+1 ); | ||
if ( typeof f !== 'function' ) { | ||
b.fail( 'should return a function' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( typeof f !== 'function' ) { | ||
b.fail( 'should return a function' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); | ||
|
||
bench( pkg+'::accumulator', function benchmark( b ) { | ||
var acc; | ||
var v; | ||
var i; | ||
|
||
acc = incrmpcorr( 5 ); | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
v = acc( randu(), randu() ); | ||
if ( v !== v ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( v !== v ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); | ||
|
||
bench( pkg+'::accumulator,known_means', function benchmark( b ) { | ||
var acc; | ||
var v; | ||
var i; | ||
|
||
acc = incrmpcorr( 5, 3.0, -1.0 ); | ||
|
||
b.tic(); | ||
for ( i = 0; i < b.iterations; i++ ) { | ||
v = acc( randu(), randu() ); | ||
if ( v !== v ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
} | ||
b.toc(); | ||
if ( v !== v ) { | ||
b.fail( 'should not return NaN' ); | ||
} | ||
b.pass( 'benchmark finished' ); | ||
b.end(); | ||
}); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
|
||
{{alias}}( window[, mx, my] ) | ||
Returns an accumulator function which incrementally computes a moving | ||
sample Pearson product-moment correlation coefficient. | ||
|
||
The `window` parameter defines the number of values over which to compute | ||
the moving sample correlation coefficient. | ||
|
||
If provided values, the accumulator function returns an updated moving | ||
sample correlation coefficient. If not provided values, the accumulator | ||
function returns the current moving sample correlation coefficient. | ||
|
||
The first `W-1` returned sample correlation coefficients will have less | ||
statistical support than subsequent sample correlation coefficients, as `W` | ||
values are needed to fill the window buffer. Until the window is full, the | ||
returned sample correlation coefficient equals the sample correlation | ||
coefficient of all provided values. | ||
|
||
Parameters | ||
---------- | ||
window: integer | ||
Window size. | ||
|
||
mx: number (optional) | ||
Known mean. | ||
|
||
my: number (optional) | ||
Known mean. | ||
|
||
Returns | ||
------- | ||
acc: Function | ||
Accumulator function. | ||
|
||
Examples | ||
-------- | ||
> var accumulator = {{alias}}( 3 ); | ||
> var r = accumulator() | ||
null | ||
> r = accumulator( 2.0, 1.0 ) | ||
0.0 | ||
> r = accumulator( -5.0, 3.14 ) | ||
~-1.0 | ||
> r = accumulator( 3.0, -1.0 ) | ||
~-0.925 | ||
> r = accumulator( 5.0, -9.5 ) | ||
~-0.863 | ||
> r = accumulator() | ||
~-0.863 | ||
|
||
See Also | ||
-------- | ||
|
40 changes: 40 additions & 0 deletions
40
lib/node_modules/@stdlib/stats/incr/mpcorr/examples/index.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2018 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
var randu = require( '@stdlib/random/base/randu' ); | ||
var incrmpcorr = require( './../lib' ); | ||
|
||
var accumulator; | ||
var r; | ||
var x; | ||
var y; | ||
var i; | ||
|
||
// Initialize an accumulator: | ||
accumulator = incrmpcorr( 5 ); | ||
|
||
// For each simulated datum, update the moving sample correlation coefficient... | ||
console.log( '\nx\ty\tCorrelation Coefficient\n' ); | ||
for ( i = 0; i < 100; i++ ) { | ||
x = randu() * 100.0; | ||
y = randu() * 100.0; | ||
r = accumulator( x, y ); | ||
console.log( '%d\t%d\t%d', x.toFixed( 4 ), y.toFixed( 4 ), r.toFixed( 4 ) ); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
/** | ||
* @license Apache-2.0 | ||
* | ||
* Copyright (c) 2018 The Stdlib Authors. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"); | ||
* you may not use this file except in compliance with the License. | ||
* You may obtain a copy of the License at | ||
* | ||
* http://www.apache.org/licenses/LICENSE-2.0 | ||
* | ||
* Unless required by applicable law or agreed to in writing, software | ||
* distributed under the License is distributed on an "AS IS" BASIS, | ||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
* See the License for the specific language governing permissions and | ||
* limitations under the License. | ||
*/ | ||
|
||
'use strict'; | ||
|
||
/** | ||
* Compute a moving sample Pearson product-moment correlation coefficient incrementally. | ||
* | ||
* @module @stdlib/stats/incr/mpcorr | ||
* | ||
* @example | ||
* var incrmpcorr = require( '@stdlib/stats/incr/mpcorr' ); | ||
* | ||
* var accumulator = incrmpcorr( 3 ); | ||
* | ||
* var r = accumulator(); | ||
* // returns null | ||
* | ||
* r = accumulator( 2.0, 1.0 ); | ||
* // returns 0.0 | ||
* | ||
* r = accumulator( -5.0, 3.14 ); | ||
* // returns ~-1.0 | ||
* | ||
* r = accumulator( 3.0, -1.0 ); | ||
* // returns ~-0.925 | ||
* | ||
* r = accumulator( 5.0, -9.5 ); | ||
* // returns ~-0.863 | ||
* | ||
* r = accumulator(); | ||
* // returns ~-0.863 | ||
*/ | ||
|
||
// MODULES // | ||
|
||
var incrmpcorr = require( './main.js' ); | ||
|
||
|
||
// EXPORTS // | ||
|
||
module.exports = incrmpcorr; |
Oops, something went wrong.