Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 183 additions & 0 deletions lib/node_modules/@stdlib/stats/incr/nanpcorrdist/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
<!--

@license Apache-2.0

Copyright (c) 2025 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.

-->

# incrnanpcorrdist

> Compute a [sample Pearson product-moment correlation distance][pearson-correlation] incrementally, ignoring `NaN` value.

<section class="intro">

The [sample Pearson product-moment correlation distance][pearson-correlation] is defined as

<!-- <equation class="equation" label="eq:pearson_distance" align="center" raw="d_{x,y} = 1 - r_{x,y} = 1 - \frac{\operatorname{cov_n(x,y)}}{\sigma_x \sigma_y}" alt="Equation for the Pearson product-moment correlation distance."> -->

```math
d_{x,y} = 1 - r_{x,y} = 1 - \frac{\mathop{\mathrm{cov_n(x,y)}}}{\sigma_x \sigma_y}
```

<!-- <div class="equation" align="center" data-raw-text="d_{x,y} = 1 - r_{x,y} = 1 - \frac{\operatorname{cov_n(x,y)}}{\sigma_x \sigma_y}" data-equation="eq:pearson_distance">
<img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@7e0a95722efd9c771b129597380c63dc6715508b/lib/node_modules/@stdlib/stats/incr/pcorrdist/docs/img/equation_pearson_distance.svg" alt="Equation for the Pearson product-moment correlation distance.">
<br>
</div> -->

<!-- </equation> -->

where `r` is the [sample Pearson product-moment correlation coefficient][pearson-correlation], `cov(x,y)` is the sample covariance, and `σ` corresponds to the sample standard deviation. As `r` resides on the interval `[-1,1]`, `d` resides on the interval `[0,2]`.

</section>

<!-- /.intro -->

<section class="usage">

## Usage

```javascript
var incrnanpcorrdist = require( '@stdlib/stats/incr/nanpcorrdist' );
```

#### incrnanpcorrdist( \[mx, my] )

Returns an accumulator `function` which incrementally computes a [sample Pearson product-moment correlation distance][pearson-correlation], ignoring `NaN` value.

```javascript
var accumulator = incrnanpcorrdist();
```

If the means are already known, provide `mx` and `my` arguments.

```javascript
var accumulator = incrnanpcorrdist( 3.0, -5.5 );
```

#### accumulator( \[x, y] )

If provided input value `x` and `y`, the accumulator function returns an updated [sample correlation coefficient][pearson-correlation]. If not provided input values `x` and `y`, the accumulator function returns the current [sample correlation coefficient][pearson-correlation].

```javascript
var accumulator = incrnanpcorrdist();

var d = accumulator( 2.0, 1.0 );
// returns 1.0

d = accumulator( NaN, 1.0 );
// returns 1.0

d = accumulator( 1.0, -5.0 );
// returns 0.0

d = accumulator( 1.0, NaN );
// returns 0.0

d = accumulator( 3.0, 3.14 );
// returns ~0.035

d = accumulator();
// returns ~0.035
```

</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 accumulator function skips updating its state and continues to return the most recent valid accumulated value. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function.

</section>

<!-- /.notes -->

<section class="examples">

## Examples

<!-- eslint no-undef: "error" -->

```javascript
var randu = require( '@stdlib/random/base/randu' );
var incrnanpcorrdist = require( '@stdlib/stats/incr/nanpcorrdist' );

var accumulator;
var x;
var y;
var i;

// Initialize an accumulator:
accumulator = incrnanpcorrdist();

// For each simulated datum, update the sample correlation distance...
for ( i = 0; i < 100; i++ ) {
if ( randu() < 0.2 ) {
x = NaN;
} else {
x = randu() * 100.0;
}
if ( randu() < 0.2 ) {
y = NaN;
} else {
y = randu() * 100.0;
}
accumulator( x, y );
}
console.log( accumulator() );
```

</section>

<!-- /.examples -->

<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->

<section class="related">

* * *

## See Also

- <span class="package-name">[`@stdlib/stats/incr/covariance`][@stdlib/stats/incr/covariance]</span><span class="delimiter">: </span><span class="description">compute an unbiased sample covariance incrementally.</span>
- <span class="package-name">[`@stdlib/stats/incr/pcorr`][@stdlib/stats/incr/pcorr]</span><span class="delimiter">: </span><span class="description">compute a sample Pearson product-moment correlation coefficient.</span>
- <span class="package-name">[`@stdlib/stats/incr/summary`][@stdlib/stats/incr/summary]</span><span class="delimiter">: </span><span class="description">compute a statistical summary incrementally.</span>

</section>

<!-- /.related -->

<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->

<section class="links">

[pearson-correlation]: https://en.wikipedia.org/wiki/Pearson_correlation_coefficient

<!-- <related-links> -->

[@stdlib/stats/incr/covariance]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/covariance

[@stdlib/stats/incr/pcorr]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/pcorr

[@stdlib/stats/incr/summary]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/summary

<!-- </related-links> -->

</section>

<!-- /.links -->
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
/**
* @license Apache-2.0
*
* Copyright (c) 2025 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 incrnanpcorrdist = require( './../lib' );


// MAIN //

bench( pkg, function benchmark( b ) {
var f;
var i;
b.tic();
for ( i = 0; i < b.iterations; i++ ) {
f = incrnanpcorrdist();
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 = incrnanpcorrdist();

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 = incrnanpcorrdist( 3.0, -2.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();
});
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
47 changes: 47 additions & 0 deletions lib/node_modules/@stdlib/stats/incr/nanpcorrdist/docs/repl.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@

{{alias}}( [mx, my] )
Returns an accumulator function which incrementally computes a sample
Pearson product-moment correlation distance, ignoring `NaN` value.

The correlation distance is defined as one minus the Pearson product-moment
correlation coefficient and, thus, resides on the interval [0,2].

If provided values, the accumulator function returns an updated sample
correlation distance. If not provided values, the accumulator function
returns the current sample correlation distance.

If provided `NaN` or a value which, when used in computations, results in
`NaN`, the accumulated value is `NaN` for all future invocations.

Parameters
----------
mx: number (optional)
Known mean.

my: number (optional)
Known mean.

Returns
-------
acc: Function
Accumulator function.

Examples
--------
> var accumulator = {{alias}}();
> var d = accumulator()
null
> d = accumulator( 2.0, 1.0 )
~1.0
> d = accumulator( NaN, 1.0 )
~1.0
> d = accumulator( -5.0, 3.14 )
~2.0
> d = accumulator( -5.0, NaN )
~2.0
> d = accumulator()
~2.0

See Also
--------

Loading