# incrgrubbs
> [Grubbs' test][grubbs-test] for outliers.
[Grubbs' test][grubbs-test] (also known as the **maximum normalized residual test** or **extreme studentized deviate test**) is a statistical test used to detect outliers in a univariate dataset assumed to come from a normally distributed population. [Grubbs' test][grubbs-test] is defined for the hypothesis:
- **H_0**: the dataset does **not** contain outliers.
- **H_1**: the dataset contains **exactly** one outlier.
The [Grubbs' test][grubbs-test] statistic for a two-sided alternative hypothesis is defined as
where `s` is the sample standard deviation. The [Grubbs test][grubbs-test] statistic is thus the largest absolute deviation from the sample mean in units of the sample standard deviation.
The [Grubbs' test][grubbs-test] statistic for the alternative hypothesis that the minimum value is an outlier is defined as
The [Grubbs' test][grubbs-test] statistic for the alternative hypothesis that the maximum value is an outlier is defined as
For a two-sided test, the hypothesis that a dataset does **not** contain an outlier is rejected at significance level α if
where `t` denotes the upper critical value of the _t_-distribution with `N-2` degrees of freedom and a significance level of `α/(2N)`.
For a one-sided test, the hypothesis that a dataset does **not** contain an outlier is rejected at significance level α if
where `t` denotes the upper critical value of the _t_-distribution with `N-2` degrees of freedom and a significance level of `α/N`.
## 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
## 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.
## Examples
```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
*/
```
* * *
## References
- Grubbs, Frank E. 1950. "Sample Criteria for Testing Outlying Observations." _The Annals of Mathematical Statistics_ 21 (1). The Institute of Mathematical Statistics: 27–58. doi:[10.1214/aoms/1177729885][@grubbs:1950a].
- Grubbs, Frank E. 1969. "Procedures for Detecting Outlying Observations in Samples." _Technometrics_ 11 (1). Taylor & Francis: 1–21. doi:[10.1080/00401706.1969.10490657][@grubbs:1969a].
[grubbs-test]: https://en.wikipedia.org/wiki/Grubbs%27_test_for_outliers
[@grubbs:1950a]: https://doi.org/10.1214/aoms/1177729885
[@grubbs:1969a]: https://doi.org/10.1080/00401706.1969.10490657
