Add README

Author: kgryte

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

@@ -0,0 +1,177 @@
+<!--
+
+@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.
+
+-->
+
+# incrgrubbs
+
+> [Grubbs' test][grubbs-test] for outliers.
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var incrgrubbs = require( '@stdlib/stats/incr/grubbs' );
+```
+
+#### incrgrubbs( \[options] )
+
+Returns an accumulator `function` which incrementally performs [Grubbs' test][grubbs-test] for outliers.
+
+```javascript
+var accumulator = incrgrubbs();
+```
+
+The function accepts the following `options`:
+
+-   **alpha**: significance level. Default: `0.05`.
+
+-   **alternative**: alternative hypothesis. The option may be one of the following values:
+
+    -   `'two-sided'`: test whether the minimum or maximum value is an outlier.
+    -   `'min'`: test whether the minimum value is an outlier.
+    -   `'max'`: test whether the maximum value is an outlier.
+
+    Default: `'two-sided'`.
+
+-   **init**: number of data points the accumulator should use to compute initial statistics **before** testing for an outlier. Until the accumulator is provided the number of data points specified by this option, the accumulator returns `null`. Default: `100`.
+
+#### accumulator( \[x] )
+
+If provided an input value `x`, the accumulator function returns updated test results. If not provided an input value `x`, the accumulator function returns the current test results.
+
+```javascript
+var rnorm = require( '@stdlib/random/base/normal' );
+
+var opts = {
+    'init': 0
+};
+var accumulator = incrgrubbs( opts );
+
+var results = accumulator( rnorm( 10.0, 5.0 ) );
+// returns null
+
+results = accumulator( rnorm( 10.0, 5.0 ) );
+// returns null
+
+results = accumulator( rnorm( 10.0, 5.0 ) );
+// returns <Object>
+
+results = accumulator();
+// returns <Object>
+```
+
+The accumulator function returns an `object` having the following fields:
+
+-   **rejected**: boolean indicating whether the null hypothesis should be rejected.
+-   **alpha**: significance level.
+-   **criticalValue**: critical value.
+-   **statistic**: test statistic.
+-   **df**: degrees of freedom.
+-   **mean**: sample mean.
+-   **sd**: corrected sample standard deviation.
+-   **min**: minimum value.
+-   **max**: maximum value.
+-   **alt**: alternative hypothesis.
+-   **method**: method name.
+-   **print**: method for pretty-printing test output.
+
+The `print` method accepts the following options:
+
+-   **digits**: number of digits after the decimal point. Default: `4`.
+-   **decision**: `boolean` indicating whether to print the test decision. Default: `true`.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   [Grubbs' test][grubbs-test] **assumes** that data is normally distributed. Accordingly, one should first **verify** that the data can be _reasonably_ approximated by a normal distribution before applying the [Grubbs' test][grubbs-test].
+-   The accumulator must be provided **at least** three data points before performing [Grubbs' test][grubbs-test]. Until at least three data points are provided, the accumulator returns `null`.
+-   Input values are **not** type checked. If provided `NaN` or a value which, when used in computations, results in `NaN`, the test statistic is `NaN` for **all** 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.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var incrgrubbs = require( '@stdlib/stats/incr/grubbs' );
+
+var data;
+var opts;
+var acc;
+var i;
+
+// Define a data set (8 mass spectrometer measurements of a uranium isotope; see Tietjen and Moore. 1972. "Some Grubbs-Type Statistics for the Detection of Several Outliers".)
+data = [ 199.31, 199.53, 200.19, 200.82, 201.92, 201.95, 202.18, 245.57 ];
+
+// Create a new accumulator:
+opts = {
+    'init': data.length,
+    'alternative': 'two-sided'
+};
+acc = incrgrubbs( opts );
+
+// Update the accumulator:
+for ( i = 0; i < data.length; i++ ) {
+    acc( data[ i ] );
+}
+
+// Print the test results:
+console.log( acc().print() );
+/* e.g., =>
+Grubbs' Test
+
+Alternative hypothesis: The maximum value (245.57) is an outlier
+
+    criticalValue: 2.1266
+    statistic: 2.4688
+    df: 6
+
+Test Decision: Reject null in favor of alternative at 5% significance level
+
+*/
+```
+
+</section>
+
+<!-- /.examples -->
+
+<section class="links">
+
+[grubbs-test]: https://en.wikipedia.org/wiki/Grubbs%27_test_for_outliers
+
+</section>
+
+<!-- /.links -->