/**
* Build a simple converter for correlated residuals with the specific weights.
*
* <p>The scalar objective function value is computed as:
*
* <pre>
* objective = y<sup>T</sup>y with y = scale×(observation-objective)
* </pre>
*
* <p>The array computed by the objective function, the observations array and the the scaling
* matrix must have consistent sizes or a {@link FunctionEvaluationException} will be triggered
* while computing the scalar objective.
*
* @param function vectorial residuals function to wrap
* @param observations observations to be compared to objective function to compute residuals
* @param scale scaling matrix
* @exception IllegalArgumentException if the observations vector and the scale matrix dimensions
* don't match (objective function dimension is checked only when the {@link #value(double[])}
* method is called)
*/
public LeastSquaresConverter(
final MultivariateVectorialFunction function,
final double[] observations,
final RealMatrix scale)
throws IllegalArgumentException {
if (observations.length != scale.getColumnDimension()) {
throw MathRuntimeException.createIllegalArgumentException(
"dimension mismatch {0} != {1}", observations.length, scale.getColumnDimension());
}
this.function = function;
this.observations = observations.clone();
this.weights = null;
this.scale = scale.copy();
}
/**
* Throws IllegalArgumentException of the matrix does not have at least two columns and two rows
*
* @param matrix matrix to check for sufficiency
*/
private void checkSufficientData(final RealMatrix matrix) {
int nRows = matrix.getRowDimension();
int nCols = matrix.getColumnDimension();
if (nRows < 2 || nCols < 2) {
throw MathRuntimeException.createIllegalArgumentException(
"insufficient data: only {0} rows and {1} columns.", nRows, nCols);
}
}
/**
* Returns a matrix of standard errors associated with the estimates in the correlation matrix.
* <br>
* <code>getCorrelationStandardErrors().getEntry(i,j)</code> is the standard error associated with
* <code>getCorrelationMatrix.getEntry(i,j)</code>
*
* <p>The formula used to compute the standard error is <br>
* <code>SE<sub>r</sub> = ((1 - r<sup>2</sup>) / (n - 2))<sup>1/2</sup></code> where <code>r
* </code> is the estimated correlation coefficient and <code>n</code> is the number of
* observations in the source dataset.
*
* @return matrix of correlation standard errors
*/
public RealMatrix getCorrelationStandardErrors() {
int nVars = correlationMatrix.getColumnDimension();
double[][] out = new double[nVars][nVars];
for (int i = 0; i < nVars; i++) {
for (int j = 0; j < nVars; j++) {
double r = correlationMatrix.getEntry(i, j);
out[i][j] = Math.sqrt((1 - r * r) / (nObs - 2));
}
}
return new BlockRealMatrix(out);
}
public void print(RealMatrix matrix, PrintWriter output, NumberFormat format, int width) {
for (int row = 0; row < matrix.getRowDimension(); row++) {
for (int column = 0; column < matrix.getColumnDimension(); column++) {
String number = format.format(matrix.getEntry(row, column));
int padding = Math.max(1, width - number.length());
for (int p = 0; p < padding; p++) output.print(' ');
output.print(number);
}
output.println();
}
}
/**
* Computes the correlation matrix for the columns of the input matrix.
*
* @param matrix matrix with columns representing variables to correlate
* @return correlation matrix
*/
public RealMatrix computeCorrelationMatrix(RealMatrix matrix) {
int nVars = matrix.getColumnDimension();
RealMatrix outMatrix = new BlockRealMatrix(nVars, nVars);
for (int i = 0; i < nVars; i++) {
for (int j = 0; j < i; j++) {
double corr = correlation(matrix.getColumn(i), matrix.getColumn(j));
outMatrix.setEntry(i, j, corr);
outMatrix.setEntry(j, i, corr);
}
outMatrix.setEntry(i, i, 1d);
}
return outMatrix;
}
public static String realMatToString(RealMatrix r) {
String res =
"RealMatrix("
+ r.getRowDimension()
+ "x"
+ r.getColumnDimension()
+ ") of type '"
+ r.getClass().getName()
+ "'\n";
for (int i = 0; i < r.getRowDimension(); i++) {
res += Arrays.toString(r.getRow(i)) + "\n";
}
return res;
}
/**
* Derives a correlation matrix from a covariance matrix.
*
* <p>Uses the formula <br>
* <code>r(X,Y) = cov(X,Y)/s(X)s(Y)</code> where <code>r(·,·)</code> is the
* correlation coefficient and <code>s(·)</code> means standard deviation.
*
* @param covarianceMatrix the covariance matrix
* @return correlation matrix
*/
public RealMatrix covarianceToCorrelation(RealMatrix covarianceMatrix) {
int nVars = covarianceMatrix.getColumnDimension();
RealMatrix outMatrix = new BlockRealMatrix(nVars, nVars);
for (int i = 0; i < nVars; i++) {
double sigma = Math.sqrt(covarianceMatrix.getEntry(i, i));
outMatrix.setEntry(i, i, 1d);
for (int j = 0; j < i; j++) {
double entry =
covarianceMatrix.getEntry(i, j) / (sigma * Math.sqrt(covarianceMatrix.getEntry(j, j)));
outMatrix.setEntry(i, j, entry);
outMatrix.setEntry(j, i, entry);
}
}
return outMatrix;
}
/**
* Returns a matrix of p-values associated with the (two-sided) null hypothesis that the
* corresponding correlation coefficient is zero.
*
* <p><code>getCorrelationPValues().getEntry(i,j)</code> is the probability that a random variable
* distributed as <code>t<sub>n-2</sub></code> takes a value with absolute value greater than or
* equal to <br>
* <code>|r|((n - 2) / (1 - r<sup>2</sup>))<sup>1/2</sup></code>
*
* <p>The values in the matrix are sometimes referred to as the <i>significance</i> of the
* corresponding correlation coefficients.
*
* @return matrix of p-values
* @throws MathException if an error occurs estimating probabilities
*/
public RealMatrix getCorrelationPValues() throws MathException {
TDistribution tDistribution = new TDistributionImpl(nObs - 2);
int nVars = correlationMatrix.getColumnDimension();
double[][] out = new double[nVars][nVars];
for (int i = 0; i < nVars; i++) {
for (int j = 0; j < nVars; j++) {
if (i == j) {
out[i][j] = 0d;
} else {
double r = correlationMatrix.getEntry(i, j);
double t = Math.abs(r * Math.sqrt((nObs - 2) / (1 - r * r)));
out[i][j] = 2 * (1 - tDistribution.cumulativeProbability(t));
}
}
}
return new BlockRealMatrix(out);
}
/**
* Compute the "hat" matrix.
*
* <p>The hat matrix is defined in terms of the design matrix X by
* X(X<sup>T</sup>X)<sup>-1</sup>X<sup>T</sup>
*
* <p>The implementation here uses the QR decomposition to compute the hat matrix as Q
* I<sub>p</sub>Q<sup>T</sup> where I<sub>p</sub> is the p-dimensional identity matrix augmented
* by 0's. This computational formula is from "The Hat Matrix in Regression and ANOVA", David C.
* Hoaglin and Roy E. Welsch, <i>The American Statistician</i>, Vol. 32, No. 1 (Feb., 1978), pp.
* 17-22.
*
* @return the hat matrix
*/
public RealMatrix calculateHat() {
// Create augmented identity matrix
RealMatrix Q = qr.getQ();
final int p = qr.getR().getColumnDimension();
final int n = Q.getColumnDimension();
Array2DRowRealMatrix augI = new Array2DRowRealMatrix(n, n);
double[][] augIData = augI.getDataRef();
for (int i = 0; i < n; i++) {
for (int j = 0; j < n; j++) {
if (i == j && i < p) {
augIData[i][j] = 1d;
} else {
augIData[i][j] = 0d;
}
}
}
// Compute and return Hat matrix
return Q.multiply(augI).multiply(Q.transpose());
}
