feat: add stats/incr/nanmcv

lib/node_modules/@stdlib/stats/incr/nanmcv/README.md

@@ -0,0 +1,233 @@
+<!--
+
+@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.
+
+-->
+
+# incrnanmcv
+
+> Compute a moving [coefficient of variation][coefficient-of-variation] (CV) incrementally, ignoring `NaN` values.
+
+<section class="intro">
+
+For a window of size `W`, the [corrected sample standard deviation][standard-deviation] is defined as
+
+<!-- <equation class="equation" label="eq:corrected_sample_standard_deviation" align="center" raw="s = \sqrt{\frac{1}{W-1} \sum_{i=0}^{W-1} ( x_i - \bar{x} )^2}" alt="Equation for the corrected sample standard deviation."> -->
+
+```math
+s = \sqrt{\frac{1}{W-1} \sum_{i=0}^{W-1} ( x_i - \bar{x} )^2}
+```
+
+<!-- <div class="equation" align="center" data-raw-text="s = \sqrt{\frac{1}{W-1} \sum_{i=0}^{W-1} ( x_i - \bar{x} )^2}" data-equation="eq:corrected_sample_standard_deviation">
+    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@eed6b690d7c37249b04544b3f5fd36ad8eb3187f/lib/node_modules/@stdlib/stats/incr/nanmcv/docs/img/equation_corrected_sample_standard_deviation.svg" alt="Equation for the corrected sample standard deviation.">
+    <br>
+</div> -->
+
+<!-- </equation> -->
+
+and the [arithmetic mean][arithmetic-mean] is defined as
+
+<!-- <equation class="equation" label="eq:arithmetic_mean" align="center" raw="\bar{x} = \frac{1}{W} \sum_{i=0}^{W-1} x_i" alt="Equation for the arithmetic mean."> -->
+
+```math
+\bar{x} = \frac{1}{W} \sum_{i=0}^{W-1} x_i
+```
+
+<!-- <div class="equation" align="center" data-raw-text="\bar{x} = \frac{1}{W} \sum_{i=0}^{W-1} x_i" data-equation="eq:arithmetic_mean">
+    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@4cf17e4e25cc2244d5154bd5d251f4bd023748da/lib/node_modules/@stdlib/stats/incr/nanmcv/docs/img/equation_arithmetic_mean.svg" alt="Equation for the arithmetic mean.">
+    <br>
+</div> -->
+
+<!-- </equation> -->
+
+The [coefficient of variation][coefficient-of-variation] (also known as **relative standard deviation**, RSD) is defined as
+
+<!-- <equation class="equation" label="eq:coefficient_of_variation" align="center" raw="c_v = \frac{s}{\bar{x}}" alt="Equation for the coefficient of variation (CV)."> -->
+
+<div class="equation" align="center" data-raw-text="c_v = \frac{s}{\bar{x}}" data-equation="eq:coefficient_of_variation">
+    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@eed6b690d7c37249b04544b3f5fd36ad8eb3187f/lib/node_modules/@stdlib/stats/incr/nanmcv/docs/img/equation_coefficient_of_variation.svg"Equation for the coefficient of variation (CV).">
+    <br>
+</div>
+
+<!-- </equation> -->
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var incrnanmcv = require( '@stdlib/stats/incr/nanmcv' );
+```
+
+#### incrnanmcv( window\[, mean] )
+
+Returns an accumulator `function` which incrementally computes a moving [coefficient of variation][coefficient-of-variation]. The `window` parameter defines the number of values over which to compute the moving [coefficient of variation][coefficient-of-variation].
+
+```javascript
+var accumulator = incrnanmcv( 3 );
+```
+
+If the mean is already known, provide a `mean` argument.
+
+```javascript
+var accumulator = incrnanmcv( 3, 5.0 );
+```
+
+#### accumulator( \[x] )
+
+If provided an input value `x`, the accumulator function returns an updated accumulated value. If not provided an input value `x`, the accumulator function returns the current accumulated value.
+
+```javascript
+var incrnanmcv = require( '@stdlib/stats/incr/nanmcv' );
+
+// Create an accumulator with a window size of 3:
+var accumulator = incrnanmcv( 3 );
+
+var cv = accumulator();
+// returns null
+
+// Fill the window (ignores NaN)...
+cv = accumulator( 2.0 ); // [2.0]
+// returns 0.0
+
+cv = accumulator( NaN ); // still [2.0]
+// returns 0.0 (NaN ignored, window unchanged)
+
+cv = accumulator( 3.0 ); // [2.0, 3.0]
+// returns ~0.28
+
+cv = accumulator( 1.0 ); // [2.0, 3.0, 1.0]
+// returns ~0.50
+
+// Window begins sliding only when valid number is added...
+cv = accumulator( NaN ); // still [2.0, 3.0, 1.0]
+// returns ~0.50 (no change)
+
+cv = accumulator( 7.0 ); // [3.0, 1.0, 7.0]
+// returns ~0.83
+
+cv = accumulator( 5.0 ); // [1.0, 7.0, 5.0]
+// returns ~0.71
+
+cv = accumulator( NaN ); // still [1.0, 7.0, 5.0]
+// returns ~0.71
+
+cv = accumulator();
+// returns ~0.71
+```
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   Input values are not type checked. If provided a `NaN` value, the window remains same and the value is ignored and does not affect the accumulated result. Computations are performed only over valid numeric inputs currently within the moving window. If all window values are `NaN` (or if no valid numeric values have been provided), the accumulated value is `NaN`. If non-numeric inputs are possible, you are advised to type check and handle them accordingly before passing values to the accumulator function.
+-   As `W` values are needed to fill the window buffer, the first `W-1` returned values are calculated from smaller sample sizes. Until the window is full, each returned value is calculated from all provided values.
+-   The [coefficient of variation][coefficient-of-variation] is typically computed on nonnegative values. The measure may lack meaning for data which can assume both positive and negative values.
+-   For small and moderately sized samples, the accumulated value tends to be too low and is thus a **biased** estimator. Provided the generating distribution is known (e.g., a normal distribution), you may want to adjust the accumulated value or use an alternative implementation providing an unbiased estimator.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var randu = require( '@stdlib/random/base/randu' );
+var incrnanmcv = require( '@stdlib/stats/incr/nanmcv' );
+
+var accumulator;
+var v;
+var i;
+
+// Initialize an accumulator with window size 5:
+accumulator = incrnanmcv( 5 );
+
+// For each simulated datum, update the moving coefficient of variation...
+for ( i = 0; i < 100; i++ ) {
+    // Introduce NaN values randomly:
+    if ( randu() < 0.2 ) {
+        v = NaN;
+    } else {
+        v = randu() * 100.0;
+    }
+    accumulator( v );
+}
+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/cv`][@stdlib/stats/incr/cv]</span><span class="delimiter">: </span><span class="description">compute the coefficient of variation (CV) incrementally.</span>
+-   <span class="package-name">[@stdlib/stats/incr/mcv][@stdlib/stats/incr/mcv]</span><span class="delimiter">: </span><span class="description">Compute moving coefficient of variation (CV) incrementally</span>
+-   <span class="package-name">[`@stdlib/stats/incr/mmean`][@stdlib/stats/incr/mmean]</span><span class="delimiter">: </span><span class="description">compute a moving arithmetic mean incrementally.</span>
+-   <span class="package-name">[`@stdlib/stats/incr/mstdev`][@stdlib/stats/incr/mstdev]</span><span class="delimiter">: </span><span class="description">compute a moving corrected sample standard deviation incrementally.</span>
+-   <span class="package-name">[`@stdlib/stats/incr/mvmr`][@stdlib/stats/incr/mvmr]</span><span class="delimiter">: </span><span class="description">compute a moving variance-to-mean ratio (VMR) 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">
+
+[coefficient-of-variation]: https://en.wikipedia.org/wiki/Coefficient_of_variation
+
+[arithmetic-mean]: https://en.wikipedia.org/wiki/Arithmetic_mean
+
+[standard-deviation]: https://en.wikipedia.org/wiki/Standard_deviation
+
+<!-- <related-links> -->
+
+[@stdlib/stats/incr/cv]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/cv
+
+[@stdlib/stats/incr/mmean]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mmean
+
+[@stdlib/stats/incr/mstdev]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mstdev
+
+[@stdlib/stats/incr/mvmr]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mvmr
+
+[@stdlib/stats/incr/mcv]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/stats/incr/mcv
+
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->

lib/node_modules/@stdlib/stats/incr/nanmcv/benchmark/benchmark.js

@@ -0,0 +1,97 @@
+/**
+* @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 isnan = require( '@stdlib/assert/is-nan' );
+var pkg = require( './../package.json' ).name;
+var incrnanmcv = require( './../lib' );
+
+
+// MAIN //
+
+bench( pkg, function benchmark( b ) {
+	var f;
+	var i;
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		f = incrnanmcv( (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 x;
+	var i;
+
+	acc = incrnanmcv( 5 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		// Randomly introduce NaN values:
+		x = ( randu() < 0.1 ) ? NaN : randu();
+		v = acc( x );
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( v ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::accumulator,known_mean', function benchmark( b ) {
+	var acc;
+	var v;
+	var x;
+	var i;
+
+	acc = incrnanmcv( 5, 0.5 );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		x = ( randu() < 0.1 ) ? NaN : randu();
+		v = acc( x );
+		if ( isnan( v ) ) {
+			b.fail( 'should not return NaN' );
+		}
+	}
+	b.toc();
+	if ( isnan( v ) ) {
+		b.fail( 'should not return NaN' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});