Package org.apache.commons.math.stat.correlation

Class 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

    • 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