## org.apache.commons.math.stat.correlation
Class PearsonsCorrelation

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

    public class PearsonsCorrelation

extends java.lang.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: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $

Field Summary
`private RealMatrix` `correlationMatrix` correlation matrix
`private int` `nObs` number of observations

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
`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:
    `java.lang.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 java.lang.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:
    `java.lang.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

Copyright (c) 2003-2011 Apache Software Foundation