Correlation Test

Compute a Pearson product-moment correlation test between paired samples.

Usage

var pcorrtest = require( '@stdlib/stats/pcorrtest' );

pcorrtest( x, y[, opts] )

By default, the function performs a t-test for the null hypothesis that the paired data in arrays or typed arrays x and y have a Pearson correlation coefficient of zero.

var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ];
var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ];

var out = pcorrtest( x, y );
/* e.g., returns
    {
        'alpha': 0.05,
        'rejected': true,
        'pValue': ~0.006,
        'statistic': ~3.709,
        'ci': [ ~0.332, ~0.95 ],
        'nullValue': 0,
        'pcorr': ~0.795,
        // ...
    }
*/

The returned object comes with a .print() method which when invoked will print a formatted output of the results of the hypothesis test. print accepts a digits option that controls the number of decimal digits displayed for the outputs and a decision option, which when set to false will hide the test decision.

console.log( out.print() );
/* e.g., =>
    t-test for Pearson correlation coefficient

    Alternative hypothesis: True correlation coefficient is not equal to 0

        pValue: 0.006
        statistic: 3.709
        95% confidence interval: [0.3315,0.9494]

    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.
alternative: 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.
rho: number denoting the correlation between the x and y variables under the null hypothesis. Default: 0.

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

var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ];
var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ];

var out = pcorrtest( x, y, {
    'alpha': 0.1
});
var table = out.print();
/* e.g., returns
    t-test for Pearson correlation coefficient

    Alternative hypothesis: True correlation coefficient is not equal to 0

        pValue: 0.006
        statistic: 3.709
        90% confidence interval: [0.433,0.9363]

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

By default, a two-sided test is performed. To perform either of the one-sided tests, set the alternative option to less or greater.

var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ];
var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ];

var out = pcorrtest( x, y, {
    'alternative': 'less'
});
var table = out.print();
/* e.g., returns
    t-test for Pearson correlation coefficient

    Alternative hypothesis: True correlation coefficient is less than 0

        pValue: 0.997
        statistic: 3.709
        95% confidence interval: [-1,0.9363]

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

out = pcorrtest( x, y, {
    'alternative': 'greater'
});
table = out.print();
/* e.g., returns
    t-test for Pearson correlation coefficient

    Alternative hypothesis: True correlation coefficient is greater than 0

        pValue: 0.003
        statistic: 3.709
        95% confidence interval: [0.433,1]

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

To test whether the correlation coefficient is equal to some other value than 0, set the rho option. Hypotheses tests for correlation coefficients besides zero are carried out using the Fisher z-transformation.

var x = [ 0.7, -1.6, -0.2, -1.2, -0.1, 3.4, 3.7, 0.8, 0.0, 2.0 ];
var y = [ 1.9, 0.8, 1.1, 0.1, -0.1, 4.4, 5.5, 1.6, 4.6, 3.4 ];

var out = pcorrtest( x, y, {
    'rho': 0.8
});
/* e.g., returns
    {
        'alpha': 0.05,
        'rejected': false,
        'pValue': ~0.972,
        'statistic': ~-0.035,
        'ci': [ ~0.332, ~0.949 ],
        'nullValue': 0.8,
        'pcorr': ~0.795,
        // ...
    }
*/

var table = out.print();
/* e.g., returns
    Fisher's z transform test for Pearson correlation coefficient

    Alternative hypothesis: True correlation coefficient is not equal to 0.8

        pValue: 0.972
        statistic: -0.0351
        95% confidence interval: [0.3315,0.9494]

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

Examples

var rnorm = require( '@stdlib/random/base/normal' );
var sqrt = require( '@stdlib/math/base/special/sqrt' );
var pcorrtest = require( '@stdlib/stats/pcorrtest' );

var table;
var out;
var rho;
var x;
var y;
var i;

rho = 0.5;
x = new Array( 300 );
y = new Array( 300 );
for ( i = 0; i < 300; i++ ) {
    x[ i ] = rnorm( 0.0, 1.0 );
    y[ i ] = ( rho * x[ i ] ) + rnorm( 0.0, sqrt( 1.0 - (rho*rho) ) );
}

out = pcorrtest( x, y );
table = out.print();
console.log( table );

out = pcorrtest( x, y, {
    'rho': 0.5
});
table = out.print();
console.log( table );