JMSLTM Numerical Library 5.0.1

com.imsl.stat
Class Covariances

java.lang.Object
  extended by com.imsl.stat.Covariances
All Implemented Interfaces:
Serializable, Cloneable

public class Covariances
extends Object
implements Serializable, Cloneable

Computes the sample variance-covariance or correlation matrix.

Class covariances computes estimates of correlations, covariances, or sums of squares and crossproducts for a data matrix x. Weights and frequencies are allowed but not required.

The means, (corrected) sums of squares, and (corrected) sums of crossproducts are computed using the method of provisional means. Let x_{ki} denote the mean based on i observations for the k-th variable, f_i denote the frequency of the i-th observation, w_i denote the weight of the i-th observations, and c_{jki} denote the sum of crossproducts (or sum of squares if j = k) based on i observations. Then the method of provisional means finds new means and sums of crossproducts as shown in the example below.

The means and crossproducts are initialized as follows:

x_{k0}  = 0.0,,,,,for,,k = 1,, 
  ldots ,,p

c_{jk0}  = 0.0,,,for,,j,,k = 1,, 
  ldots ,,p

where p denotes the number of variables. Letting x_{k,i+1} denote the k-th variable of observation i + 1, each new observation leads to the following updates for x_{ki} and c_{jki} using the update constant r_{i+1}:

r_{i + 1}  = frac{{f_{i + 1} w_{i + 1} 
  }}{{sumlimits_{l = 1}^{i + 1} {f_l w_l } }}

bar x_{k,;i + 1}  = bar x_{ki}  + left( 
  {x_{k,;i + 1}  - bar x_{ki} } right)r_{i + 1}

c_{jk,;i + 1}  = c_{jki}  + f_{i + 1} 
  w_{i + 1} left( {x_{j,;i + 1}  - bar x_{ji} } right)left( 
  {x_{k,;i + 1}  - bar x_{ki} } right)left( {1 - r_{i + 1} } 
  right)

The default value for weights and frequencies is 1. Means and variances are computed based on the valid data for each variable or, if required, based on all the valid data for each pair of variables.

See Also:
Example, Serialized Form

Nested Class Summary
static class Covariances.DiffObsDeletedException
          Different observations are being deleted from return matrix than were originally entered.
static class Covariances.MoreObsDelThanEnteredException
          More observations are being deleted from the output covariance matrix than were originally entered (the corresponding row, column of the incidence matrix is less than zero).
static class Covariances.NonnegativeFreqException
          Frequencies must be nonnegative.
static class Covariances.NonnegativeWeightException
          Weights must be nonnegative.
static class Covariances.TooManyObsDeletedException
          More observations have been deleted than were originally entered (the sum of frequencies has become negative).
 
Field Summary
static int CORRECTED_SSCP_MATRIX
          Indicates corrected sums of squares and crossproducts matrix.
static int CORRELATION_MATRIX
          Indicates correlation matrix.
static int STDEV_CORRELATION_MATRIX
          Indicates correlation matrix except for the diagonal elements which are the standard deviations
static int VARIANCE_COVARIANCE_MATRIX
          Indicates variance-covariance matrix.
 
Constructor Summary
Covariances(double[][] x)
          Constructor for Covariances.
 
Method Summary
 double[][] compute(int matrixType)
          Computes the matrix.
 int[][] getIncidenceMatrix()
          Returns the incidence matrix.
 double[] getMeans()
          Returns the means of the variables in x.
 int getNumRowMissing()
          Returns the total number of observations that contain any missing values (Double.NaN).
 int getObservations()
          Returns the sum of the frequencies.
 double getSumOfWeights()
          Returns the sum of the weights of all observations.
 void setFrequencies(double[] frequencies)
          Sets the frequency for each observation.
 void setMissingValueMethod(int missingValueMethod)
          Sets the method used to exclude missing values in x from the computations, where Double.NaN is interpreted as the missing value code.
 void setWeights(double[] weights)
          Sets the weight for each observation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CORRECTED_SSCP_MATRIX

public static final int CORRECTED_SSCP_MATRIX
Indicates corrected sums of squares and crossproducts matrix.

See Also:
Constant Field Values

CORRELATION_MATRIX

public static final int CORRELATION_MATRIX
Indicates correlation matrix.

See Also:
Constant Field Values

STDEV_CORRELATION_MATRIX

public static final int STDEV_CORRELATION_MATRIX
Indicates correlation matrix except for the diagonal elements which are the standard deviations

See Also:
Constant Field Values

VARIANCE_COVARIANCE_MATRIX

public static final int VARIANCE_COVARIANCE_MATRIX
Indicates variance-covariance matrix.

See Also:
Constant Field Values
Constructor Detail

Covariances

public Covariances(double[][] x)
Constructor for Covariances.

Parameters:
x - A double matrix containing the data.
Throws:
IllegalArgumentException - is thrown if x.length, and x[0].length are equal to 0.
Method Detail

compute

public final double[][] compute(int matrixType)
                         throws Covariances.NonnegativeFreqException,
                                Covariances.NonnegativeWeightException,
                                Covariances.TooManyObsDeletedException,
                                Covariances.MoreObsDelThanEnteredException,
                                Covariances.DiffObsDeletedException
Computes the matrix.

Parameters:
matrixType - An int scalar indicating the type of matrix to compute. Uses class member VARIANCE_COVARIANCE_MATRIX, CORRECTED_SSCP_MATRIX, CORRELATION_MATRIX, STDEV_CORRELATION_MATRIX for matrixType.
Returns:
A double matrix containing computed result.
Throws:
Covariances.NonnegativeFreqException - is thrown if the frequencies are negative.
Covariances.NonnegativeWeightException - is thrown if the weights sre negative.
Covariances.TooManyObsDeletedException - is thrown if more observations have been deleted than were originally entered, i.e. the sum of frequencies has become negative.
Covariances.MoreObsDelThanEnteredException - is thrown if more observations are being deleted from "variance-covariance" matrix than were originally entered. The corresponding row,column of the incidence matrix is less than zero.
Covariances.DiffObsDeletedException - is thrown if different observations are being deleted than were originally entered.

getIncidenceMatrix

public int[][] getIncidenceMatrix()
Returns the incidence matrix. Note that the compute method must be invoked first before invoking this method. Otherwise, the method throws a NullPointerException exception.

Returns:
An int matrix containing the incidence matrix. If method is 0, incidence matrix is 1 times 1 and contains the number of valid observations; otherwise, incidence matrix is xleft[ 0 right]{rm{.length }} times xleft[ 0 right]{rm{.length}} and contains the number of pairs of valid observations used in calculating the crossproducts for covariance.

getMeans

public double[] getMeans()
Returns the means of the variables in x. Note that the compute method must be invoked first before invoking this method. Otherwise, the method throws a NullPointerException exception.

Returns:
A double array containing the means of the variables in x. The components of the array correspond to the columns of x.

getNumRowMissing

public int getNumRowMissing()
Returns the total number of observations that contain any missing values (Double.NaN). Note that the compute method must be invoked first before invoking this method. Otherwise, the return value is 0.

Returns:
An int scalar containing the total number of observations that contain any missing values (Double.NaN).

getObservations

public int getObservations()
Returns the sum of the frequencies. Note that the compute method must be invoked first before invoking this method. Otherwise, the return value is 0.

Returns:
An int scalar containing the sum of the frequencies. If missingValueMethod = 0, observations with missing values are not included; otherwise, all observations are included except for observations with missing values for the weight or the frequency.

getSumOfWeights

public double getSumOfWeights()
Returns the sum of the weights of all observations. Note that the compute method must be invoked first before invoking this method. Otherwise, the return value is 0.

Returns:
A double scalar containing the sum of the weights of all observations. If missingValueMethod = 0, observations with missing values are not included. Otherwise, all observations are included except for observations with missing values for the weight or the frequency.

setFrequencies

public void setFrequencies(double[] frequencies)
Sets the frequency for each observation.

Parameters:
frequencies - A double array of size x.length containing the frequency for each observation. Default: frequencies[] = 1.

setMissingValueMethod

public void setMissingValueMethod(int missingValueMethod)
Sets the method used to exclude missing values in x from the computations, where Double.NaN is interpreted as the missing value code.

Parameters:
missingValueMethod - An int scalar indicating the method to use. The methods are as follows:
missingValueMethod Action
0 The exclusion is listwise, default. (The entire row of x is excluded if any of the values of the row is equal to the missing value code.)
1 Raw crossproducts are computed from all valid pairs and means, and variances are computed from all valid data on the individual variables.  Corrected crossproducts, covariances, and correlations are computed using these quantities.
2 Raw crossproducts, means, and variances are computed as in the case of method = 1. However, corrected crossproducts and covariances are computed only from the valid pairs of data.  Correlations are computed using these covariances and the variances from all valid data.
3 Raw crossproducts, means, variances, and covariances are computed as in the case of method = 2. Correlations are computed using these covariances, but the variances used are computed from the valid pairs of data.


setWeights

public void setWeights(double[] weights)
Sets the weight for each observation.

Parameters:
weights - A double array of size x.length containing the weight for each observation. Default: weights[] = 1.

JMSLTM Numerical Library 5.0.1

Copyright © 1970-2008 Visual Numerics, Inc.
Built July 8 2008.