Apache Commons Math 3.6.1 · org.apache.commons.math3.stat.correlation.PearsonsCorrelation

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) = Σ[(x_i - E(X))(y_i - 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.

To compute the correlation coefficient for a single pair of arrays, use PearsonsCorrelation() to construct an instance with no data and then correlation(double[], double[]). Correlation matrices can also be computed directly from an instance with no data using computeCorrelationMatrix(double[][]). In order to use getCorrelationMatrix(), getCorrelationPValues(), or getCorrelationStandardErrors(); however, one of the constructors supplying data or a covariance matrix must be used to create the instance.

Field Summary

Modifier and Type	Field and Description
private final RealMatrix	correlationMatrix correlation matrix
private final int	nObs number of observations

Constructor Summary

Access	Constructor and Description
public	PearsonsCorrelation() Create a PearsonsCorrelation instance without data.
public	PearsonsCorrelation(double[][] rectangular array with columns representing variables data) Create a PearsonsCorrelation from a rectangular array whose columns represent values of variables to be correlated.
public	PearsonsCorrelation(RealMatrix matrix with columns representing variables to correlate matrix) Create a PearsonsCorrelation from a RealMatrix whose columns represent variables to be correlated.
public	PearsonsCorrelation(Covariance Covariance instance covariance) Create a PearsonsCorrelation from a `Covariance`.
public	PearsonsCorrelation(RealMatrix covariance matrix covarianceMatrix, int the number of observations in the dataset used to compute the covariance matrix numberOfObservations) Create a PearsonsCorrelation from a covariance matrix.

Method Summary

Modifier and Type	Method and Description
private void	checkSufficientData(final RealMatrix matrix to check for sufficiency matrix) Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows.
public RealMatrix	Returns: correlation matrix computeCorrelationMatrix(RealMatrix matrix with columns representing variables to correlate matrix) Computes the correlation matrix for the columns of the input matrix, using `correlation(double[], double[])`.
public RealMatrix	Returns: correlation matrix computeCorrelationMatrix(double[][] matrix with columns representing variables to correlate data) Computes the correlation matrix for the columns of the input rectangular array.
public double	Returns: Returns Pearson's correlation coefficient for the two arrays correlation(final double[] first data array xArray, final double[] second data array yArray) Computes the Pearson's product-moment correlation coefficient between two arrays.
public RealMatrix	Returns: correlation matrix covarianceToCorrelation(RealMatrix the covariance matrix covarianceMatrix) Derives a correlation matrix from a covariance matrix.
public RealMatrix	Returns: correlation matrix getCorrelationMatrix() Returns the correlation matrix.
public RealMatrix	Returns: matrix of p-values getCorrelationPValues() Returns a matrix of p-values associated with the (two-sided) null hypothesis that the corresponding correlation coefficient is zero.
public RealMatrix	Returns: matrix of correlation standard errors getCorrelationStandardErrors() Returns a matrix of standard errors associated with the estimates in the correlation matrix.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

correlationMatrix	back to summary
private final RealMatrix correlationMatrix correlation matrix

nObs	back to summary
private final int nObs number of observations

Constructor Detail

PearsonsCorrelation	back to summary
public PearsonsCorrelation() Create a PearsonsCorrelation instance without data.

PearsonsCorrelation back to summary

PearsonsCorrelation	back to summary
public PearsonsCorrelation(double[][] data) Create a PearsonsCorrelation from a rectangular array whose columns represent values of variables to be correlated. Throws MathIllegalArgumentException if the input array does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance. Parameters data:double[][] rectangular array with columns representing variables Exceptions MathIllegalArgumentException: if the input data array is not rectangular with at least two rows and two columns. See Also `correlation(double[], double[])`

public PearsonsCorrelation(double[][] data)

Create a PearsonsCorrelation from a rectangular array whose columns represent values of variables to be correlated. Throws MathIllegalArgumentException if the input array does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance.

Parameters

data:double[][]: rectangular array with columns representing variables

Exceptions

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

See Also

correlation(double[], double[])

PearsonsCorrelation back to summary

PearsonsCorrelation	back to summary
public PearsonsCorrelation(RealMatrix matrix) Create a PearsonsCorrelation from a RealMatrix whose columns represent variables to be correlated. Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance. Parameters matrix:RealMatrix matrix with columns representing variables to correlate Exceptions MathIllegalArgumentException: if the matrix does not contain sufficient data See Also `correlation(double[], double[])`

public PearsonsCorrelation(RealMatrix matrix)

Create a PearsonsCorrelation from a RealMatrix whose columns represent variables to be correlated. Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance.

Parameters

matrix:RealMatrix: matrix with columns representing variables to correlate

Exceptions

MathIllegalArgumentException:: if the matrix does not contain sufficient data

See Also

correlation(double[], double[])

PearsonsCorrelation back to summary

PearsonsCorrelation	back to summary
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 Covariance instance

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: Covariance instance

PearsonsCorrelation	back to summary
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:RealMatrix covariance matrix numberOfObservations:int the number of observations in the dataset used to compute the covariance matrix

PearsonsCorrelation

back to summary

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:RealMatrix: covariance matrix
numberOfObservations:int: the number of observations in the dataset used to compute the covariance matrix

Method Detail

checkSufficientData	back to summary
private void checkSufficientData(final RealMatrix matrix) Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows. Parameters matrix:RealMatrix matrix to check for sufficiency Exceptions MathIllegalArgumentException: if there is insufficient data

checkSufficientData

back to summary

private void checkSufficientData(final RealMatrix matrix)

Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows.

Parameters

matrix:RealMatrix: matrix to check for sufficiency

Exceptions

MathIllegalArgumentException:: if there is insufficient data

computeCorrelationMatrix back to summary

computeCorrelationMatrix	back to summary
public RealMatrix computeCorrelationMatrix(RealMatrix matrix) Computes the correlation matrix for the columns of the input matrix, using `correlation(double[], double[])`. Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance. Parameters matrix:RealMatrix matrix with columns representing variables to correlate Returns:RealMatrix correlation matrix Exceptions MathIllegalArgumentException: if the matrix does not contain sufficient data See Also `correlation(double[], double[])`

public RealMatrix computeCorrelationMatrix(RealMatrix matrix)

Computes the correlation matrix for the columns of the input matrix, using correlation(double[], double[]). Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows. Pairwise correlations are set to NaN if one of the correlates has zero variance.

Parameters

matrix:RealMatrix: matrix with columns representing variables to correlate

Returns:RealMatrix

correlation matrix

Exceptions

MathIllegalArgumentException:: if the matrix does not contain sufficient data

See Also

correlation(double[], double[])

computeCorrelationMatrix back to summary

computeCorrelationMatrix	back to summary
public RealMatrix computeCorrelationMatrix(double[][] data) Computes the correlation matrix for the columns of the input rectangular array. The columns of the array represent values of variables to be correlated. Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows or if the array is not rectangular. Pairwise correlations are set to NaN if one of the correlates has zero variance. Parameters data:double[][] matrix with columns representing variables to correlate Returns:RealMatrix correlation matrix Exceptions MathIllegalArgumentException: if the array does not contain sufficient data See Also `correlation(double[], double[])`

public RealMatrix computeCorrelationMatrix(double[][] data)

Computes the correlation matrix for the columns of the input rectangular array. The columns of the array represent values of variables to be correlated. Throws MathIllegalArgumentException if the matrix does not have at least two columns and two rows or if the array is not rectangular. Pairwise correlations are set to NaN if one of the correlates has zero variance.

Parameters

data:double[][]: matrix with columns representing variables to correlate

Returns:RealMatrix

correlation matrix

Exceptions

MathIllegalArgumentException:: if the array does not contain sufficient data

See Also

correlation(double[], double[])

correlation back to summary

correlation	back to summary
public double correlation(final double[] xArray, final double[] yArray) Computes the Pearson's product-moment correlation coefficient between two arrays. Throws MathIllegalArgumentException if the arrays do not have the same length or their common length is less than 2. Returns `NaN` if either of the arrays has zero variance (i.e., if one of the arrays does not contain at least two distinct values). Parameters xArray:double[] first data array yArray:double[] second data array Returns:double Returns Pearson's correlation coefficient for the two arrays Exceptions DimensionMismatchException: if the arrays lengths do not match MathIllegalArgumentException: if there is insufficient data

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

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

Throws MathIllegalArgumentException if the arrays do not have the same length or their common length is less than 2. Returns NaN if either of the arrays has zero variance (i.e., if one of the arrays does not contain at least two distinct values).

Parameters

xArray:double[]: first data array
yArray:double[]: second data array

Returns:double

Returns Pearson's correlation coefficient for the two arrays

Exceptions

DimensionMismatchException:: if the arrays lengths do not match
MathIllegalArgumentException:: if there is insufficient data

covarianceToCorrelation back to summary

covarianceToCorrelation	back to summary
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:RealMatrix the covariance matrix Returns:RealMatrix correlation matrix

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:RealMatrix: the covariance matrix

Returns:RealMatrix

correlation matrix

getCorrelationMatrix back to summary

getCorrelationMatrix	back to summary
public RealMatrix getCorrelationMatrix() Returns the correlation matrix. This method will return null if the argumentless constructor was used to create this instance, even if `computeCorrelationMatrix(double[][])` has been called before it is activated. Returns:RealMatrix correlation matrix

public RealMatrix getCorrelationMatrix()

Returns the correlation matrix.

This method will return null if the argumentless constructor was used to create this instance, even if computeCorrelationMatrix(double[][]) has been called before it is activated.

Returns:RealMatrix: correlation matrix

getCorrelationPValues back to summary

getCorrelationPValues	back to summary
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 `t_n-2` takes a value with absolute value greater than or equal to `\|r\|((n - 2) / (1 - r²))^1/2` The values in the matrix are sometimes referred to as the significance of the corresponding correlation coefficients. To use this method, one of the constructors that supply an input matrix must have been used to create this instance. Returns:RealMatrix matrix of p-values Exceptions MaxCountExceededException: if an error occurs estimating probabilities NullPointerException: if this instance was created with no data

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 t_n-2 takes a value with absolute value greater than or equal to
|r|((n - 2) / (1 - r²))^1/2

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

To use this method, one of the constructors that supply an input matrix must have been used to create this instance.

Returns:RealMatrix

matrix of p-values

Exceptions

MaxCountExceededException:: if an error occurs estimating probabilities
NullPointerException:: if this instance was created with no data

getCorrelationStandardErrors back to summary

getCorrelationStandardErrors	back to summary
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 `SE_r = ((1 - r²) / (n - 2))^1/2` where `r` is the estimated correlation coefficient and `n` is the number of observations in the source dataset. To use this method, one of the constructors that supply an input matrix must have been used to create this instance. Returns:RealMatrix matrix of correlation standard errors Exceptions NullPointerException: if this instance was created with no data

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
SE_r = ((1 - r²) / (n - 2))^1/2 where r is the estimated correlation coefficient and n is the number of observations in the source dataset.

To use this method, one of the constructors that supply an input matrix must have been used to create this instance.

Returns:RealMatrix

matrix of correlation standard errors

Exceptions

NullPointerException:: if this instance was created with no data

public Class PearsonsCorrelation

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail