time-to-botec/squiggle/node_modules/@stdlib/stats/ztest2/docs/repl.txt

{{alias}}( x, y, sigmax, sigmay[, options] )
    Computes a two-sample z-test.

    By default, the function performs a two-sample z-test for the null
    hypothesis that the data in arrays or typed arrays `x` and `y` is
    independently drawn from normal distributions with equal means and known
    standard deviations `sigmax` and `sigmay`.

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

    Parameters
    ----------
    x: Array<number>
        First data array.

    y: Array<number>
        Second data array.

    sigmax: number
        Known standard deviation of first group.

    sigmay: number
        Known standard deviation of second group.

    options: Object (optional)
        Options.

    options.alpha: number (optional)
        Number in the interval `[0,1]` giving the significance level of the
        hypothesis test. Default: `0.05`.

    options.alternative: string (optional)
        Either `two-sided`, `less` or `greater`. Indicates whether the
        alternative hypothesis is that `x` has a larger mean than `y`
        (`greater`), `x` has a smaller mean than `y` (`less`) or the means are
        the same (`two-sided`). Default: `'two-sided'`.

    options.difference: number (optional)
        Number denoting the difference in means under the null hypothesis.
        Default: `0`.

    Returns
    -------
    out: Object
        Test result object.

    out.alpha: number
        Used significance level.

    out.rejected: boolean
        Test decision.

    out.pValue: number
        p-value of the test.

    out.statistic: number
        Value of test statistic.

    out.ci: Array<number>
        1-alpha confidence interval for the mean.

    out.nullValue: number
        Assumed difference in means under H0.

    out.xmean: number
        Sample mean of `x`.

    out.ymean: number
        Sample mean of `y`.

    out.alternative: string
        Alternative hypothesis (`two-sided`, `less` or `greater`).

    out.method: string
        Name of test.

    out.print: Function
        Function to print formatted output.

    Examples
    --------
    // Drawn from Normal(0,2):
    > var x = [ -0.21, 0.14, 1.65, 2.11, -1.86, -0.29, 1.48, 0.81, 0.86, 1.04 ];

    // Drawn from Normal(1,2):
    > var y = [ -1.53, -2.93, 2.34, -1.15, 2.7, -0.12, 4.22, 1.66, 3.43, 4.66 ];
    > var out = {{alias}}( x, y, 2.0, 2.0 )
    {
        alpha: 0.05,
        rejected: false,
        pValue: ~0.398,
        statistic: ~-0.844
        ci: [ ~-2.508, ~0.988 ],
        alternative: 'two-sided',
        method: 'Two-sample z-test',
        nullValue: 0,
        xmean: ~0.573,
        ymean: ~1.328
    }

    // Print table output:
    > var table = out.print()
    Two-sample z-test

    Alternative hypothesis: True difference in means is not equal to 0

        pValue: 0.3986
        statistic: -0.8441
        95% confidence interval: [-2.508,0.998]

    Test Decision: Fail to reject null in favor of alternative at 5%
    significance level

    // Choose a different significance level than `0.05`:
    > out = {{alias}}( x, y, 2.0, 2.0, { 'alpha': 0.4 });
    > table = out.print()
    Two-sample z-test

    Alternative hypothesis: True difference in means is not equal to 0

        pValue: 0.3986
        statistic: -0.8441
        60% confidence interval: [-1.5078,-0.0022]

    Test Decision: Reject null in favor of alternative at 40% significance level

    // Perform one-sided tests:
    > out = {{alias}}( x, y, 2.0, 2.0, { 'alternative': 'less' });
    > table = out.print()
    Two-sample z-test

    Alternative hypothesis: True difference in means is less than 0

        pValue: 0.1993
        statistic: -0.8441
        95% confidence interval: [-Infinity,0.7162]

    Test Decision: Fail to reject null in favor of alternative at 5%
    significance level


    > out = {{alias}}( x, y, 2.0, 2.0, { 'alternative': 'greater' });
    > table = out.print()
    Two-sample z-test

    Alternative hypothesis: True difference in means is greater than 0

        pValue: 0.8007
        statistic: -0.8441
        95% confidence interval: [-2.2262,Infinity]

    Test Decision: Fail to reject null in favor of alternative at 5%
    significance level

    // Test for a difference in means besides zero:
    > var rnorm = {{alias:@stdlib/random/base/normal}}.factory({ 'seed': 372 });
    > x = new Array( 100 );
    > for ( i = 0; i < x.length; i++ ) {
    ...     x[ i ] = rnorm( 2.0, 1.0 );
    ... }
    > y = new Array( 100 );
    ... for ( i = 0; i < x.length; i++ ) {
    ...     y[ i ] = rnorm( 0.0, 2.0 );
    ... }
    > out = {{alias}}( x, y, 1.0, 2.0, { 'difference': 2.0 })
    {
        rejected: false,
        pValue: ~0.35,
        statistic: ~-0.935
        ci: [ ~1.353, ~2.229 ],
        // ...
    }

    See Also
    --------