com.imsl.stat

Class PooledCovariances

java.lang.Object

com.imsl.stat.PooledCovariances

All Implemented Interfaces:

Serializable, Cloneable

public class PooledCovariances
extends Object
implements Serializable, Cloneable

Computes a pooled variance-covariance matrix from one or more sets of observations.

Class PooledCovariances computes the pooled variance-covariance matrix from one or more matrices of observations. The within-groups means are also computed. Listwise deletion of missing values is assumed so that all observations used are complete; for any row of x, if any element of the observation is missing (with a value of Double.NaN), the row is not used. This class should be used whenever the user suspects that the data has been sampled from populations with different means but identical variance-covariance matrices. If these assumptions cannot be made, a different variance-covariance matrix should be estimated within each group.

Group observation totals, \(T_i\) for i = 1, ..., g, where g is the number of groups, are computed as: $$T_i=\sum\limits_{j}w_{ij}f_{ij}x_{ij}$$

where \(w_{ij}\) is the observation weight, \(x_{ij}\) is the j-th observation in the i-th group, and \(f_{ij}\) is the observation frequency.

Modified Givens rotations are used in computing the Cholesky decomposition of the pooled sums of squares and crossproducts matrix (Golub and Van Loan 1983).

The group means and the pooled sample covariance matrix S are computed from intermediate results. These quantities are defined by

$$ \bar{x}_i=\frac{{T_i}}{{\sum\limits_{j}w_{ij}f_{ij}}} $$ $$ S=\frac{1}{\sum\limits_{ij}f_{ij}-g}\sum\limits_{ij}w_{ij}f_{ij} \big(x_{ij}-\bar{x}_i\big)\big(x_{ij}-\bar{x}_i\big)^T $$

See Also:

Example 1, Example 2, Serialized Form

Constructor Summary

Constructors

Constructor and Description
PooledCovariances(int nGroups) Constructor for PooledCovariances.

Method Summary

Modifier and Type	Method and Description
int[]	getGroupCounts() Returns the number of observations in each group.
double[][]	getMeans() Returns the means of each group.
int	getNumberOfGroups() Returns the number of groups used in the analysis.
int	getNumberOfMissingRows() Returns the total number of observations that contain missing values (Double.NaN or group[i] == 0).
int	getNumberOfVariables() Returns the number of variables used in the analysis.
double[][]	getPooledCovariances() Computes and returns the pooled covariances.
double[]	getSumOfWeights() Returns the sum of the weights times the frequencies in the groups.
int	getTotalNumberOfObservations() Returns the total number of observations used in the analysis.
double[][]	getU() Returns the lower matrix U, the lower triangular for the pooled sample crossproducts matrix.
void	update(double[][] x) Updates the pooled covariances with new observations from one group.
void	update(double[][] x, int[] groups) Updates the pooled covariances with new group observations.
void	update(double[][] x, int[] groups, double[] frequencies, double weight) Updates the pooled covariances with new group observations, frequencies and a scalar weight.
void	update(double[][] x, int[] groups, double[] frequencies, double[] weights) Updates the pooled covariances with new group observations, frequencies and weights.
void	update(double[][] x, int[] groups, double frequency, double weight) Updates the pooled covariances with new group observations and a scalar frequency and weight.
void	update(double[][] x, int[] groups, double frequency, double[] weights) Updates the pooled covariances with new group observations, a scalar frequency and weights.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PooledCovariances

public PooledCovariances(int nGroups)

Constructor for PooledCovariances.

Parameters:

nGroups - an int, the number of groups in the data. The groups are numbered 1, 2,..., nGroups.

Method Detail

update

public void update(double[][] x)

Updates the pooled covariances with new observations from one group.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

This method assumes that all observations belong to group 1 and have frequencies and weights of 1.0.

update

public void update(double[][] x,
                   int[] groups)

Updates the pooled covariances with new group observations.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

This method assumes that all observations have frequencies and weights of 1.0.

groups - an int array containing the group number of the observations in x. Group numbers must be numbered 1, 2,..., nGroups. If groups[i] == 0, the row of observations will be skipped and counted as missing. For groups[i] < 0 or groups[i] > nGroups, a warning will be issued indicating that the row of observations will be skipped (not marked as missing).

update

public void update(double[][] x,
                   int[] groups,
                   double[] frequencies,
                   double[] weights)

Updates the pooled covariances with new group observations, frequencies and weights.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

groups - an int array containing the group number of the observations in x. Group numbers must be numbered 1, 2,..., nGroups. If groups[i] == 0, the row of observations will be skipped and counted as missing. For groups[i] < 0 or groups[i] > nGroups, a warning will be issued indicating that the row of observations will be skipped (not marked as missing).

frequencies - a double array of size x.length containing the frequency for each observation. Each value must be positive. Any Double.NaN value results in that observation being skipped and marked missing.

weights - a double array of size x.length containing the weight for each observation. Each value must be positive. Any Double.NaN value results in that observation being skipped and marked missing.

update

public void update(double[][] x,
                   int[] groups,
                   double frequency,
                   double[] weights)

Updates the pooled covariances with new group observations, a scalar frequency and weights.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

groups - an int array containing the group number of the observations in x. Group numbers must be numbered 1, 2,..., nGroups. If groups[i] == 0, the row of observations will be skipped and counted as missing. For groups[i] < 0 or groups[i] > nGroups, a warning will be issued indicating that the row of observations will be skipped (not marked as missing).

frequency - a positive double containing the frequency valid for each observation

weights - a double array of size x.length containing the weight for each observation. Each value must be positive. Any Double.NaN value results in that observation being skipped and marked missing.

update

public void update(double[][] x,
                   int[] groups,
                   double[] frequencies,
                   double weight)

Updates the pooled covariances with new group observations, frequencies and a scalar weight.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

groups - an int array containing the group number of the observations in x. Group numbers must be numbered 1, 2,..., nGroups. If groups[i] == 0, the row of observations will be skipped and counted as missing. For groups[i] < 0 or groups[i] > nGroups, a warning will be issued indicating that the row of observations will be skipped (not marked as missing).

frequencies - a double array of size x.length containing the frequency for each observation. Each value must be positive. Any Double.NaN value results in that observation being skipped and marked missing.

weight - a positive double containing the weight valid for each observation

update

public void update(double[][] x,
                   int[] groups,
                   double frequency,
                   double weight)

Updates the pooled covariances with new group observations and a scalar frequency and weight.

Parameters:

x - a double matrix containing the observed data. Each row of x contains one observation consisting of x[0].length variables. If x[i][j] has value Double.NaN, then row i of the observations will be skipped and counted as missing.

The number of observation variables is determined in the first call to any of the update methods. In all subsequent update calls, the number of observation variables must be the same.

groups - an int array containing the group number of the observations in x. Group numbers must be numbered 1, 2,..., nGroups. If groups[i] == 0, the row of observations will be skipped and counted as missing. For groups[i] < 0 or groups[i] > nGroups, a warning will be issued indicating that the row of observations will be skipped (not marked as missing).

frequency - a positive double containing the frequency valid for each observation

weight - a positive double containing the weight valid for each observation

getPooledCovariances

public double[][] getPooledCovariances()

Computes and returns the pooled covariances.

Note that one of the update methods must be invoked first before invoking this method. Otherwise, the method throws an IllegalStateException exception.

Returns:

a square double matrix of order nVar, the number of observation variables, containing the pooled covariances

getGroupCounts

public int[] getGroupCounts()

Returns the number of observations in each group.

Returns:

an int array of length nGroups containing the number of observations in each group

getSumOfWeights

public double[] getSumOfWeights()

Returns the sum of the weights times the frequencies in the groups.

Returns:

a double array of length nGroups containing the sum of the weights times the frequencies in the groups

getMeans

public double[][] getMeans()

Returns the means of each group.

Note that one of the update methods must be invoked first before invoking this method. Otherwise, the method throws an IllegalStateException exception.

Returns:

a double matrix with nGroups rows. The i-th row contains the group i variable means.

getU

public double[][] getU()

Returns the lower matrix U, the lower triangular for the pooled sample crossproducts matrix. U is computed from the pooled sample covariance matrix, S, as \(S=U^TU\).

Note that one of the update methods must be invoked first before invoking this method. Otherwise, the method throws an IllegalStateException exception.

Returns:

a square double matrix of order nVar, the number of observation variables, containing U

getNumberOfMissingRows

public int getNumberOfMissingRows()

Returns the total number of observations that contain missing values (Double.NaN or group[i] == 0).

Returns:

an int containing the total number of observations with missing values

getTotalNumberOfObservations

public int getTotalNumberOfObservations()

Returns the total number of observations used in the analysis.

Returns:

an int, the total number of observations from all update invocations

getNumberOfVariables

public int getNumberOfVariables()

Returns the number of variables used in the analysis.

Returns:

an int, the number of variables

getNumberOfGroups

public int getNumberOfGroups()

Returns the number of groups used in the analysis.

Returns:

an int, the number of groups