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 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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()

      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

    - #### 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
      Throws:
        `MathIllegalArgumentException` - if there is insufficient data

Copyright (c) 2003-2013 Apache Software Foundation