org.apache.commons.math.stat.correlation

## Class PearsonsCorrelation

- java.lang.Object
- - org.apache.commons.math.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:
  $Revision: 990655 $ $Date: 2010-08-29 23:49:40 +0200 (dim. 29 août 2010) $

### Field Summary

Fields
`private RealMatrix` `correlationMatrix` correlation matrix
`private int` `nObs` number of observations

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`private void` `checkSufficientData(RealMatrix matrix)` Throws IllegalArgumentException of the matrix does not have at least two columns and two rows
`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`

### Field Detail

#### correlationMatrix

    private final RealMatrix correlationMatrix

correlation matrix

#### nObs

    private final int nObs

number of observations

### 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()
                                     throws MathException

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:
  `MathException` - 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)
                       throws IllegalArgumentException

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:
  `IllegalArgumentException` - if the arrays lengths do not match or 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

#### checkSufficientData

    private void checkSufficientData(RealMatrix matrix)

Throws IllegalArgumentException of the matrix does not have at least two columns and two rows

Parameters:
  `matrix` - matrix to check for sufficiency