# 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 );
``````