<commit_before># Chi-square goodness-of-fit test

> Perform a chi-square goodness-of-fit test.

<section class="usage">

## Usage

```javascript
var chi2gof = require( '@stdlib/math/stats/chi2gof' );
```

### chi2gof( x, y\[, ...params]\[, opts] )

For an [array][mdn-array] or [typed array][mdn-typed-array] of integers `x`, a chi-square goodness-of-fit is computed for the null hypothesis that the values of `x` come from the discrete distribution specified by `y`. `y` can be an `array` of expected frequencies, an `array` of population probabilities that sum to one, or a string with the name of the discrete distribution to test against. In the latter case, the parameters of the distribution must be supplied as additional arguments after `y`. The function returns an object holding the calculated test statistic, the p-value of the test, as well as the test decision.

```javascript
var out;
var x;
var y;

x = [ 89, 37, 30, 28, 2 ];
y = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];

// Supplying probabilities...
out = chi2gof( x, y );
/* returns
    {
        rejected: true,
        alpha: 0.05,
        pValue: 0.018650106520189613,
        df: 3,
        statistic: 9.990143369175627,
        ...
    }
*/

// Supplying expected counts...
x = [ 30, 20, 23, 27 ];
y = [ 25, 25, 25, 25 ];

out = chi2gof( x, y );
/* returns
    {
        rejected: false,
        alpha: 0.05,
        pValue: 0.5087002695252655,
        df: 3,
        statistic: 2.3200000000000003,
        ...
    }
*/
```

The returned object comes with a `.print()` method which when invoked will print a formatted output of the results of the hypothesis test.

```javascript
console.log( out.print() );
/* =>
    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Reject null in favor of alternative at 5% significance level
*/
```

The function accepts the following `options`:

-   **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`.
-   **ddof**: "delta degrees of freedom" adjustment. Has to be a nonnegative integer. Default: `0`.
-   **simulate**: `boolean` indicating whether to compute p-values by Monte Carlo simulation. Default: `false`.
-   **iterations**: positive integer specifying the number of Monte Carlo iterations. Default: `500`.

By default, the test is carried out at a significance level of `0.05`. To choose a custom significance level, set the `alpha` option.

```javascript
var table = out.print();
/*
    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Reject null in favor of alternative at 5% significance level
*/

out = chi2gof( x, p, {
    'alpha': 0.01
});
table = out.print();
/*
    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Fail to reject null in favor of alternative at 1% significance level
*/
```

By default, the p-value is computed using a chi-square distribution with `k - 1` degrees of freedom, where `k` is the number of levels of `x`. In case distribution parameters were estimated for the calculation of `y`, the degrees of freedom have to be corrected. Set the `ddof` option to use `n - ddof - 1` degrees of freedom.

```javascript
var x = [ 89, 37, 30, 28, 2 ];
var p = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];

var out = chi2gof( x, p, {
    'ddof': 1
});
// returns { 'pValue': ~0.0186, 'statistic': ~9.9901, 'df': 3, ... }
```

Instead of relying on the chi-square approximation when calculating the p-value, Monte Carlo simulation can be used. To do so, set the `simulate` option. The simulation is carried out by resampling from the discrete distribution given by `y`. By default, `500` iterations are used for the simulation. To set a custom number of iterations, use the `iterations` option.

```javascript
var x = [ 89, 37, 30, 28, 2 ];<commit_msg>Fix lint errors<commit_after># Chi-square goodness-of-fit test

> Perform a chi-square goodness-of-fit test.

<section class="usage">

## Usage

```javascript
var chi2gof = require( '@stdlib/math/stats/chi2gof' );
```

### chi2gof( x, y\[, ...params]\[, opts] )

For an [array][mdn-array] or [typed array][mdn-typed-array] of integers `x`, a chi-square goodness-of-fit is computed for the null hypothesis that the values of `x` come from the discrete distribution specified by `y`. `y` can be an `array` of expected frequencies, an `array` of population probabilities that sum to one, or a string with the name of the discrete distribution to test against. In the latter case, the parameters of the distribution must be supplied as additional arguments after `y`. The function returns an object holding the calculated test statistic, the p-value of the test, as well as the test decision.

```javascript
var out;
var x;
var y;

x = [ 89, 37, 30, 28, 2 ];
y = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];

// Supplying probabilities...
out = chi2gof( x, y );
/* returns
    {
        rejected: true,
        alpha: 0.05,
        pValue: 0.018650106520189613,
        df: 3,
        statistic: 9.990143369175627,
        ...
    }
*/

// Supplying expected counts...
x = [ 30, 20, 23, 27 ];
y = [ 25, 25, 25, 25 ];

out = chi2gof( x, y );
/* returns
    {
        rejected: false,
        alpha: 0.05,
        pValue: 0.5087002695252655,
        df: 3,
        statistic: 2.3200000000000003,
        ...
    }
*/
```

The returned object comes with a `.print()` method which when invoked will print a formatted output of the results of the hypothesis test.

```javascript
console.log( out.print() );
/* =>
    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Reject null in favor of alternative at 5% significance level
*/
```

The function accepts the following `options`:

-   **alpha**: `number` in the interval `[0,1]` giving the significance level of the hypothesis test. Default: `0.05`.
-   **ddof**: "delta degrees of freedom" adjustment. Has to be a nonnegative integer. Default: `0`.
-   **simulate**: `boolean` indicating whether to compute p-values by Monte Carlo simulation. Default: `false`.
-   **iterations**: positive integer specifying the number of Monte Carlo iterations. Default: `500`.

By default, the test is carried out at a significance level of `0.05`. To choose a custom significance level, set the `alpha` option.

```javascript
var table = out.print();
/* e.g., returns

    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Reject null in favor of alternative at 5% significance level
*/

out = chi2gof( x, p, {
    'alpha': 0.01
});
table = out.print();
/* e.g., returns

    Chi-square goodness-of-fit test

    Null hypothesis: population probabilities are equal to those in p

        pValue: 0.0406
        statistic: 9.9901
        degrees of freedom: 4

    Test Decision: Fail to reject null in favor of alternative at 1% significance level
*/
```

By default, the p-value is computed using a chi-square distribution with `k - 1` degrees of freedom, where `k` is the number of levels of `x`. In case distribution parameters were estimated for the calculation of `y`, the degrees of freedom have to be corrected. Set the `ddof` option to use `n - ddof - 1` degrees of freedom.

```javascript
var x = [ 89, 37, 30, 28, 2 ];
var p = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];

var out = chi2gof( x, p, {
    'ddof': 1
});
// returns { 'pValue': ~0.0186, 'statistic': ~9.9901, 'df': 3, ... }
```

Instead of relying on the chi-square approximation when calculating the p-value, Monte Carlo simulation can be used. To do so, set the `simulate` option. The simulation is carried out by resampling from the discrete distribution given by `y`. By default, `500` iterations are used for the simulation. To set a custom number of iterations, use the `iterations` option.

```javascript
var x = [ 89, 37, 30, 28, 2 ];
{'fraction_non_alphanumeric': 0.11390602752728998, 'fraction_numerical': 0.053393450403417184, 'mean_word_length': 3.0621686746987953, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 2, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4622506', 'n_tokens_mistral': 2880, 'n_tokens_neox': 2493, 'n_words': 1124}