Covariances (JMSL Numerical Library)

Overview

Package

Class

Tree

Index

Help

JMSL^TM Numerical Library 5.0.1

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.imsl.stat
Class Covariances

java.lang.Object
  com.imsl.stat.Covariances

All Implemented Interfaces:: Serializable, Cloneable

public class Covariances
extends Object
implements Serializable, Cloneable
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, denote the frequency of the i-th observation, 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 and contains the number of valid observations; otherwise, incidence matrix is 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.