# incrmgrubbs
> Moving [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.
For a window of size `W`, 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 `W-2` degrees of freedom and a significance level of `α/(2W)`.
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 `W-2` degrees of freedom and a significance level of `α/W`.
## Usage
```javascript
var incrmgrubbs = require( '@stdlib/stats/incr/mgrubbs' );
```
#### incrmgrubbs( window\[, options] )
Returns an accumulator `function` which incrementally performs [Grubbs' test][grubbs-test] for outliers. The `window` parameter defines the number of values over which to perform [Grubbs' test][grubbs-test].
```javascript
var accumulator = incrmgrubbs( 20 );
```
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'`.
#### 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 accumulator = incrmgrubbs( 3 );
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 minimum `window` size is `3`. In general, the larger the `window`, the more robust outlier detection will be. However, larger windows entail increased memory consumption.
- Until `window` values have been 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 accumulated test statistic 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.
## Examples
```javascript
var sensorData = require( '@stdlib/datasets/suthaharan-single-hop-sensor-network' );
var incrmgrubbs = require( '@stdlib/stats/incr/mgrubbs' );
var data;
var opts;
var acc;
var N;
var r;
var i;
// Get a test dataset:
data = sensorData();
N = 0;
for ( i = 0; i < data.length; i++ ) {
if ( data[ i ].mote_id === 1 ) {
N += 1;
data[ i ] = data[ i ].temperature;
}
}
data.length = N;
// Create a new accumulator which analyzes the last 5 minutes of data:
opts = {
'alternative': 'two-sided'
};
acc = incrmgrubbs( 60, opts );
// Update the accumulator:
for ( i = 0; i < data.length; i++ ) {
r = acc( data[ i ] );
if ( r && r.rejected ) {
console.log( 'Index: %d', i );
console.log( '' );
console.log( r.print() );
}
}
```
* * *
## 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
