PearsonsCorrelation (Commons MATH 3.6)

java.lang.Object
- org.apache.commons.math3.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) = Σ[(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.

Since:

2.0

Field Summary

Fields
Modifier and Type Field and Description

private RealMatrix correlationMatrix
correlation matrix

private int nObs
number of observations

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 MathIllegalArgumentException if 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, using `correlation(double[], double[])`.
`double`	`correlation(double[] xArray, double[] yArray)` Computes the Pearson's product-moment correlation coefficient between 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. 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 - rectangular array with columns representing variables
    
    Throws:
    
    MathIllegalArgumentException - if the input data array is not rectangular with at least two rows and two columns.
    See Also:
    correlation(double[], double[])
  - PearsonsCorrelation
```
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 - matrix with columns representing variables to correlate
    
    Throws:
    
    MathIllegalArgumentException - if the matrix does not contain sufficient data
    See Also:
    correlation(double[], double[])
  - 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.
    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:
    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
    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:
    matrix of correlation standard errors
    
    Throws:
    
    java.lang.NullPointerException - if this instance was created with no data
  - 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 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:
    matrix of p-values
    
    Throws:
    
    MaxCountExceededException - if an error occurs estimating probabilities
    
    java.lang.NullPointerException - if this instance was created with no data
  - computeCorrelationMatrix
```
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 - matrix with columns representing variables to correlate
    
    Returns:
    correlation matrix
    
    Throws:
    
    MathIllegalArgumentException - if the matrix does not contain sufficient data
    See Also:
    correlation(double[], double[])
  - computeCorrelationMatrix
```
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 - matrix with columns representing variables to correlate
    
    Returns:
    correlation matrix
    
    Throws:
    
    MathIllegalArgumentException - if the array does not contain sufficient data
    See Also:
    correlation(double[], double[])
  - correlation
```
public double correlation(double[] xArray,
                 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 - 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 MathIllegalArgumentException if 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

Class PearsonsCorrelation

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

correlationMatrix

nObs

Constructor Detail

PearsonsCorrelation

PearsonsCorrelation

PearsonsCorrelation

PearsonsCorrelation

PearsonsCorrelation

Method Detail

getCorrelationMatrix

getCorrelationStandardErrors

getCorrelationPValues

computeCorrelationMatrix

computeCorrelationMatrix

correlation

covarianceToCorrelation

checkSufficientData