org.apache.commons.math3.stat.correlation
Class PearsonsCorrelation

java.lang.Object
  org.apache.commons.math3.stat.correlation.PearsonsCorrelation

public class PearsonsCorrelation
extends Object

Computes Pearson's product-moment correlation coefficients for pairs of arrays or columns of a matrix.

The constructors that take RealMatrix or double[][] arguments generate correlation matrices. The columns of the input matrices are assumed to represent variable values. Correlations are given by the formula

cor(X, Y) = Σ[(xi - E(X))(yi - E(Y))] / [(n - 1)s(X)s(Y)] where E(X) is the mean of X, E(Y) is the mean of the Y values and s(X), s(Y) are standard deviations.

Since:

2.0

Version:

$Id: PearsonsCorrelation.java 3720 2012-03-16 16:34:17Z CardosoP $

Constructor Summary

PearsonsCorrelation()
Create a PearsonsCorrelation instance without data

PearsonsCorrelation(Covariance covariance)
Create a PearsonsCorrelation from a Covariance.

PearsonsCorrelation(double[][] data)
Create a PearsonsCorrelation from a rectangular array whose columns represent values of variables to be correlated.

PearsonsCorrelation(RealMatrix matrix)
Create a PearsonsCorrelation from a RealMatrix whose columns represent variables to be correlated.

PearsonsCorrelation(RealMatrix covarianceMatrix, int numberOfObservations)
Create a PearsonsCorrelation from a covariance matrix.

Method Summary

RealMatrix	computeCorrelationMatrix(double[][] data) Computes the correlation matrix for the columns of the input rectangular array.
RealMatrix	computeCorrelationMatrix(RealMatrix matrix) Computes the correlation matrix for the columns of the input matrix.
double	correlation(double[] xArray, double[] yArray) Computes the Pearson's product-moment correlation coefficient between the two arrays.
RealMatrix	covarianceToCorrelation(RealMatrix covarianceMatrix) Derives a correlation matrix from a covariance matrix.
RealMatrix	getCorrelationMatrix() Returns the correlation matrix
RealMatrix	getCorrelationPValues() Returns a matrix of p-values associated with the (two-sided) null hypothesis that the corresponding correlation coefficient is zero.
RealMatrix	getCorrelationStandardErrors() Returns a matrix of standard errors associated with the estimates in the correlation matrix. getCorrelationStandardErrors().getEntry(i,j) is the standard error associated with getCorrelationMatrix.getEntry(i,j)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PearsonsCorrelation

public PearsonsCorrelation()

Create a PearsonsCorrelation instance without data

PearsonsCorrelation

public PearsonsCorrelation(double[][] data)

Create a PearsonsCorrelation from a rectangular array whose columns represent values of variables to be correlated.

Parameters:

data - rectangular array with columns representing variables

Throws:

IllegalArgumentException - if the input data array is not rectangular with at least two rows and two columns.

PearsonsCorrelation

public PearsonsCorrelation(RealMatrix matrix)

Create a PearsonsCorrelation from a RealMatrix whose columns represent variables to be correlated.

Parameters:

matrix - matrix with columns representing variables to correlate

PearsonsCorrelation

public PearsonsCorrelation(Covariance covariance)

Create a PearsonsCorrelation from a Covariance. The correlation matrix is computed by scaling the Covariance's covariance matrix. The Covariance instance must have been created from a data matrix with columns representing variable values.

Parameters:

covariance - Covariance instance

PearsonsCorrelation

public PearsonsCorrelation(RealMatrix covarianceMatrix,
                           int numberOfObservations)

Create a PearsonsCorrelation from a covariance matrix. The correlation matrix is computed by scaling the covariance matrix.

Parameters:

covarianceMatrix - covariance matrix

numberOfObservations - the number of observations in the dataset used to compute the covariance matrix

Method Detail

getCorrelationMatrix

public RealMatrix getCorrelationMatrix()

Returns the correlation matrix

Returns:

correlation matrix

getCorrelationStandardErrors

public RealMatrix getCorrelationStandardErrors()

Returns a matrix of standard errors associated with the estimates in the correlation matrix.
getCorrelationStandardErrors().getEntry(i,j) is the standard error associated with getCorrelationMatrix.getEntry(i,j)

The formula used to compute the standard error is
SEr = ((1 - r2) / (n - 2))1/2 where r is the estimated correlation coefficient and n is the number of observations in the source dataset.

Returns:

matrix of correlation standard errors

getCorrelationPValues

public RealMatrix getCorrelationPValues()

Returns a matrix of p-values associated with the (two-sided) null hypothesis that the corresponding correlation coefficient is zero.

getCorrelationPValues().getEntry(i,j) is the probability that a random variable distributed as tn-2 takes a value with absolute value greater than or equal to
|r|((n - 2) / (1 - r2))1/2

The values in the matrix are sometimes referred to as the significance of the corresponding correlation coefficients.

Returns:

matrix of p-values

Throws:

MaxCountExceededException - if an error occurs estimating probabilities

computeCorrelationMatrix

public RealMatrix computeCorrelationMatrix(RealMatrix matrix)

Computes the correlation matrix for the columns of the input matrix.

Parameters:

matrix - matrix with columns representing variables to correlate

Returns:

correlation matrix

computeCorrelationMatrix

public RealMatrix computeCorrelationMatrix(double[][] data)

Computes the correlation matrix for the columns of the input rectangular array. The colums of the array represent values of variables to be correlated.

Parameters:

data - matrix with columns representing variables to correlate

Returns:

correlation matrix

correlation

public double correlation(double[] xArray,
                          double[] yArray)

Computes the Pearson's product-moment correlation coefficient between the two arrays.

Throws IllegalArgumentException if the arrays do not have the same length or their common length is less than 2

Parameters:

xArray - first data array

yArray - second data array

Returns:

Returns Pearson's correlation coefficient for the two arrays

Throws:

DimensionMismatchException - if the arrays lengths do not match

MathIllegalArgumentException - if there is insufficient data

covarianceToCorrelation

public RealMatrix covarianceToCorrelation(RealMatrix covarianceMatrix)

Derives a correlation matrix from a covariance matrix.

Uses the formula
r(X,Y) = cov(X,Y)/s(X)s(Y) where r(·,·) is the correlation coefficient and s(·) means standard deviation.

Parameters:

covarianceMatrix - the covariance matrix

Returns:

correlation matrix