time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

repl.txt (4251B)

      1 
      2 {{alias}}( x, y[, ...args][, options] )
      3     Performs a chi-square goodness-of-fit test.
      4 
      5     A chi-square goodness-of-fit test is computed for the null hypothesis that
      6     the values of `x` come from the discrete probability distribution specified
      7     by `y`.
      8 
      9     The second argument can either be expected frequencies, population
     10     probabilities summing to one, or a discrete probability distribution name to
     11     test against.
     12 
     13     When providing a discrete probability distribution name, distribution
     14     parameters *must* be supplied as additional arguments.
     15 
     16     The function returns an object containing the test statistic, p-value, and
     17     decision.
     18 
     19     By default, the p-value is computed using a chi-square distribution with
     20     `k-1` degrees of freedom, where `k` is the length of `x`.
     21 
     22     If provided distribution arguments are estimated (e.g., via maximum
     23     likelihood estimation), the degrees of freedom should be corrected. Set the
     24     `ddof` option to use `k-1-n` degrees of freedom, where `n` is the degrees of
     25     freedom adjustment.
     26 
     27     The chi-square approximation may be incorrect if the observed or expected
     28     frequencies in each category are too small. Common practice is to require
     29     frequencies greater than five.
     30 
     31     Instead of relying on chi-square approximation to calculate the p-value, one
     32     can use Monte Carlo simulation. When the `simulate` option is `true`, the
     33     simulation is performed by re-sampling from the discrete probability
     34     distribution specified by `y`.
     35 
     36     Parameters
     37     ----------
     38     x: ndarray|Array<number>|TypedArray
     39         Observation frequencies.
     40 
     41     y: ndarray|Array<number>|TypedArray|string
     42         Expected frequencies, population probabilities, or a discrete
     43         probability distribution name.
     44 
     45     args: ...number (optional)
     46         Distribution parameters. Distribution parameters will be passed to a
     47         probability mass function (PMF) as arguments.
     48 
     49     options: Object (optional)
     50         Options.
     51 
     52     options.alpha: number (optional)
     53         Significance level of the hypothesis test. Must be on the interval
     54         [0,1]. Default: 0.05.
     55 
     56     options.ddof: number (optional)
     57         Delta degrees of freedom adjustment. Default: 0.
     58 
     59     options.simulate: boolean (optional)
     60         Boolean indicating whether to calculate p-values by Monte Carlo
     61         simulation. The simulation is performed by re-sampling from the discrete
     62         distribution specified by `y`. Default: false.
     63 
     64     options.iterations: number (optional)
     65         Number of Monte Carlo iterations. Default: 500.
     66 
     67     Returns
     68     -------
     69     out: Object
     70         Test results object.
     71 
     72     out.alpha: number
     73         Significance level.
     74 
     75     out.rejected: boolean
     76         Test decision.
     77 
     78     out.pValue: number
     79         Test p-value.
     80 
     81     out.statistic: number
     82         Test statistic.
     83 
     84     out.df: number|null
     85         Degrees of freedom.
     86 
     87     out.method: string
     88         Test name.
     89 
     90     out.toString: Function
     91         Prints formatted output.
     92 
     93     out.toJSON: Function
     94         Serializes results as JSON.
     95 
     96     Examples
     97     --------
     98     // Provide expected probabilities...
     99     > var x = [ 89, 37, 30, 28, 2 ];
    100     > var p = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];
    101     > var out = {{alias}}( x, p );
    102     > var o = out.toJSON()
    103     { 'pValue': ~0.0406, 'statistic': ~9.9901, ... }
    104     > out.toString()
    105 
    106     // Set significance level...
    107     > var opts = { 'alpha': 0.01 };
    108     > out = {{alias}}( x, p, opts );
    109     > out.toString()
    110 
    111     // Calculate the test p-value via Monte Carlo simulation...
    112     > x = [ 89, 37, 30, 28, 2 ];
    113     > p = [ 0.40, 0.20, 0.20, 0.15, 0.05 ];
    114     > opts = { 'simulate': true, 'iterations': 1000 };
    115     > out = {{alias}}( x, p, opts );
    116     > out.toString()
    117 
    118     // Verify that data comes from Poisson distribution...
    119     > var lambda = 3.0;
    120     > var rpois = {{alias:@stdlib/random/base/poisson}}.factory( lambda );
    121     > var len = 400;
    122     > x = [];
    123     > for ( var i = 0; i < len; i++ ) { x.push( rpois() ); };
    124 
    125     // Generate a frequency table...
    126     > var freqs = new {{alias:@stdlib/array/int32}}( len );
    127     > for ( i = 0; i < len; i++ ) { freqs[ x[ i ] ] += 1; };
    128     > out = {{alias}}( freqs, 'poisson', lambda );
    129     > out.toString()
    130 
    131     See Also
    132     --------
    133