Computes a pooled variance-covariance matrix from the observations.
NROW The
absolute value of NROW
is the number of rows of X
that contain an observation. (Input)
NROW
may be positive, zero, or negative. Negative NROW
means that the −NROW
rows of data are to be deleted from (most aspects of) the analysis. This should
be done only if IDO
is 2 or 3 and the wrap-up computations for COV have not been
performed. When a negative value is input for NROW;
it is assumed that each of the −NROW
rows of X has
been input (with positive NROW
) in previous invocations of CORVC.
Use of negative values of NROW
should be made with care since it is possible that a constant variable in the
remaining data will not be recognized as such.
NVAR Number of
variables to be used in computing the covariance matrix. (Input)
The weight, frequency or group variables, if used, are not counted in NVAR.
X |NROW|
by NVAR
+ m matrix containing the data. (Input)
The number of
columns of X
that are used is NVAR
+ m, where m is 0, 1, 2, or 3 depending upon whether any columns
in X contain
frequencies, weights or group numbers.
NGROUP Number of groups in the data. (Input)
COV NVAR
by NVAR
matrix of covariances. (Output, if IDO
= 0 or 1; input/ output, if
IDO
= 2 or 3)
IDO Processing
option. (Input)
Default: IDO
= 0.
IDO Action
0 This is the only invocation of COVPL and all the data are input at once.
1 This is the first invocation of COVPL with this data, and additional calls will be made. Initialization of program variables and updating for the NROW observations are performed.
2 This is an intermediate invocation of COVPL, and updating for the NROW observations is performed.
3 All statistics are updated for the NROW observations. The covariance matrix is computed.
NCOL Number of
columns in matrix X.
Default:
NCOL
= size (X,2).
LDX Leading
dimension of X
exactly as specified in the dimension statement in the calling
program. (Input)
Default: LDX
= size (X,1).
IND Vector of
length NVAR
containing the column numbers in X
to be used in computing the covariance matrices. (Input)
By
default: IND(I)
= I.
IFRQ Frequency
option. (Input)
IFRQ
= 0 means that all frequencies are 1.0. Positive IFRQ
indicates that column number IFRQ
of X contains
the frequencies. All frequencies should be integer values. The NINT (nearest integer)
function is used to obtain integer frequencies if this is not the
case.
Default: IFRQ
= 0.
IWT Weighting
option. (Input)
IWT = 0 means that all
weights are 1.0. Positive IWT means that column
IWT of X contains the
weights. Negative weights are not allowed.
Default: IWT
= 0.
IGRP Column of
X giving the
group numbers. (Input)
If IGRP = 0, one group is
assumed. If IGRP
> 0, then column number IGRP of X contains the group
number for the observation. Group numbers must be numbered
1, 2,
, NGROUP. The NINT function is used
to get integer values for the group numbers.
Default: IGRP
= NVAR
+ 1.
NI Vector of
length NGROUP
containing the numbers of observations in the groups. (Output, if
IDO
= 0 or 1; input/output, if IDO
= 2 or 3)
The i-th element of NI contains the number
of observations in group i.
SWT Vector of length NGROUP containing the sum of the weights times the frequencies in the groups. (Output, if IDO = 0 or 1; input/output, if IDO = 2 or 3)
XMEAN NGROUP by NVAR
matrix. (Output, if IDO
= 0 or 1; input/output, if IDO =
2 or 3)
The i-th row of XMEAN contains the
group i variable means.
LDXMEA Leading
dimension of XMEAN exactly as
specified in the dimension statement in the calling program.
(Input)
Default: LDXMEAN = size (XMEAN ,1).
LDCOV Leading
dimension of COV
exactly as specified in the dimension statement of the calling
program. (Input)
Default: LDCOV
= size (COV,1).
NRMISS Number
of rows of data encountered in calls to COVPL
containing missing values (NaN) for any of the variables used.
(Output, if IDO
= 0 or 1; input/ output, if
IDO
= 2 or 3)
Generic: CALL COVPL (NROW, NVAR, X, NGROUP, COV [, ])
Specific: The specific interface names are S_COVPL and D_COVPL.
Single: CALL COVPL (IDO, NROW, NVAR, NCOL, X, LDX, IND, IFRQ, IWT, NGROUP, IGRP, NI, SWT, XMEAN, LDXMEA, COV, LDCOV, NRMISS)
Double: The double precision name is DCOVPL.
Routine COVPL computes the pooled variance-covariance matrix from a matrix of observations. The within-groups means are also computed. Listwise deletion of missing values is assumed so that all observations used are complete; in any row of X, if an element in the list IND, IGRP, IFRQ or IWT is missing, then the row is not used. Routine COVPL should be used whenever one 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.
When IDO = 0, the same computations occur as if COVPL were consecutively called with IDO equal to 1, 2, and 3. For brevity, the following discusses the computations with IDO > 0.
When IDO = 1 variables are initialized, workspace is allocated, and input variables are checked for errors.
If NROW ≠ 0 (for any value of IDO), the group observation totals, Ti, for i = 1, , g, where g is the number of groups, are updated for the |NROW| observations in X. The group totals are computed as: X
where ωij is the observation weight, xij is the j-th observation in the i-th group, and fij is the observation frequency.
Modified Givens rotations (see routines SROTM and SROTMG in the IMSL MATH/LIBRARY) are used in computing the Cholesky decomposition of the pooled sums of squares and crossproducts matrix. The interested reader is referred to Golub and Van Loan (1983) for details.
The group means and the pooled sample covariance matrix S are computed from the intermediate results when IDO = 3. These quantities are defined by
Occasionally, the Cholesky factorization, such that S = UTU where U is lower triangular of the pooled sample cross-products matrix, may be desired. U may be computed from the output array COV, and the workspace array D returned in calls to C2VPL. The Cholesky factor U can be computed prior to calling C2VPL with IDO = 3 by multiplying the elements in the i-th row of COV by
If subsequent calls to C2VPL are to be made, COV must not be modified in computing U.
1. Workspace may be explicitly provided, if desired, by use of C2VPL/DC2VPL. The reference is:
CALL C2VPL (IDO, NROW, NVAR, NCOL, X, LDX, IND, IFRQ, IWT, NGROUP, IGRP, NI, SWT, XMEAN, LDXMEA, COV, LDCOV, NRMISS, D, OB, XVAL, DIF)
The additional arguments are as follows:
D Real work vector of length NVAR.
OB Real work vector of length NVAR.
XVAL Real work vector of length NVAR * NGROUP.
DIF Real work vector of length NVAR.
2. Informational error
Type Code
3 1 The group number is not between 1 and NGROUP. The observation is ignored.
The following example computes a pooled variance-covariance matrix for the Fisher iris data (see routine GDATA, Chapter 19, Utilities;). The first column in this data set is the group indicator. To illustrate the use of the IDO argument, multiple calls to COVPL are made.
! Specifications
! Specifications
USE GDATA_INT
USE COVPL_INT
USE UMACH_INT
USE WRRRN_INT
IMPLICIT NONE
INTEGER IFRQ,
IGRP, IWT, LDCOV, LDX, LDXMEA, NCOL, NGROUP,
&
NROW, NVAR
PARAMETER (IFRQ=0,
IGRP=1, IWT=0, LDX=150, NCOL=5, NGROUP=3,
&
NROW=1, NVAR=4, LDCOV=NVAR,
LDXMEA=NGROUP)
!
INTEGER I, IDO, IND(4), NI(NGROUP), NOBS, NOUT, NRMISS, NV
REAL COV(LDCOV,LDCOV), SWT(NGROUP), X(LDX,5), XMEAN(LDXMEA,NVAR)
!
DATA IND/2, 3, 4, 5/
!
CALL GDATA (3, X, NOBS, NV)
!
IDO = 1
CALL COVPL (0, NVAR, X, NGROUP,
COV, IDO=IDO, IND=IND, IGRP=IGRP, &
NI=NI,
SWT=SWT, XMEAN=XMEAN, NRMISS=NRMISS)
! Add the observations
IDO = 2
DO 10 I=1, NOBS
CALL COVPL (NROW, NVAR, X(I:,
1:NCOL), NGROUP, COV, IDO=IDO, &
IND=IND,
IGRP=IGRP, NI=NI,SWT=SWT, XMEAN=XMEAN, NRMISS=NRMISS)
10 CONTINUE
! Summarize the statistics
IDO = 3
CALL COVPL (0, NVAR, X, NGROUP,
COV, IDO=IDO, IND=IND, IGRP=IGRP, &
NI=NI,SWT=SWT, XMEAN=XMEAN, NRMISS=NRMISS)
!
CALL UMACH (2, NOUT)
WRITE (NOUT,*) ' NRMISS = ', NRMISS
CALL WRRRN ('XMEAN', XMEAN)
CALL WRRRN ('COV', COV)
END
NRMISS = 0
XMEAN
1 2
3 4
1 5.006
3.428 1.462 0.246
2 5.936
2.770 4.260 1.326
3 6.588
2.974 5.552 2.026
COV
1 2 3 4
1 0.2650 0.0927 0.1675 0.0384
2 0.0927 0.1154 0.0552 0.0327
3 0.1675 0.0552 0.1852 0.0427
4 0.0384 0.0327 0.0427 0.0419
PHONE: 713.784.3131 FAX:713.781.9260 |