VKEEP directive

Copies information from a REML analysis into GenStat data structures.

Options

RESIDUALS = variate

Residuals from the analysis

FITTEDVALUES = variate

Fitted values from the analysis

SIGMA2 = scalar

Variance component for the lowest stratum

VCOVARIANCE = symmetric matrix

Variance-covariance matrix for the estimates of the variance components

VESTIMATES = variate

Saves a vector of all parameters in the variance model

VARESTIMATES = symmetric matrix

Variance-covariance matrix for the parameters in the variance model (as saved by VESTIMATES)

VLABELS = text

Vector of text labels for the VESTIMATES and VARESTIMATES structures

MVESTIMATES = variate

Estimates of missing values

MVSE = variate

Standard errors of missing-value estimates

MVUNITS = variate

Unit numbers of missing values

ALLEFFECTS = variate

Full set of estimated fixed and random effects

ALLVCOVARIANCE = symmetric matrix

Variance-covariance matrix for the full set of fixed and random effects not associated with the absorbing factor

DEVIANCE = scalar

Residual deviance from fitting the full fixed model

DF = scalar

Residual degrees of freedom after fitting the full fixed model

SUBDEVIANCE = scalar

Residual deviance after fitting the submodel of the fixed model

SUBDF = scalar

Residual degrees of freedom after fitting the submodel of the fixed model

RSS = scalar

Residual sum of squares from fitting the FIXED model by general least squares with a covariance matrix derived from the estimated variance components

INDEX = variate

Index of units included in the analysis

MODELS = pointer

Pointer to formulae giving the fixed, random, spline and residual terms fitted

RMATRIX = pointer

Saves details of the covariance model fitted to the residual

RMETHOD = string

Which random terms to use when calculating RESIDUALS (final, all, notspline); default uses the setting from the REML statement

CFORMAT = string

Whether the covariance matrices or the parameters are saved for a COVARIANCEMODEL (variancematrices, parameters); default vari

UVCOVARIANCE = symmetric matrix

Unit-by-unit variance-covariance matrix

DFFIXED = scalar

Number of degrees of freedom in the fixed model

DFRANDOM = scalar

Number of degrees of freedom in the random model

FMETHOD = string

Controls how to calculate F-statistics for fixed terms (automatic, algebraic, numerical); default auto

WMETHOD = string

Controls which Wald statistics are saved (add, drop); default drop

WORKSPACE = scalar

Saves the workspace setting that was used in the REML command

EXIT = scalar

Exit status of the fit (0 if successful)

SAVE = REML save structure

Save structure from the required analysis; default * takes the save structure from the latest REML statement

Parameters

TERMS = formula

Terms for which information is to be saved

COMPONENTS = scalars

Estimated variance components

COVARIANCEMODEL = pointers

Saves details of the covariance model fitted to a random term

MEANS = tables

Table of predicted means for each term

SEDMEANS = symmetric matrices

Standard errors of differences between the predicted means

VARMEANS = symmetric matrices

Variance-covariance matrix of the means

EFFECTS = tables

Table of estimated regression coefficients for each term

SEDEFFECTS = symmetric matrices

Standard errors of differences between the estimated parameters of each term

VAREFFECTS = symmetric matrices

Variance-covariance matrix of the effects of a term

DESIGNMATRIX = matrices

Saves the design matrix for the term

SPLBLUP = pointers

Best linear unbiased predictors for spline terms, saved in a pointer with a variate for each combination of the levels of the factors in the term

SPLDESIGN = pointers

Design matrices (Z) for spline terms, saved in a pointer with a matrix for each combination of the levels of the factors in the term

SPLX = pointers

Knot points for spline terms, saved in a pointer with a variate for each combination of the levels of the factors in the term

SPLSMOOTH = pointers

Smoothing parameters estimated for spline terms, saved in a pointer with a scalar for each combination of the levels of the factors in the term

CADJUSTMENT = scalars

For a term involving covariates, saves the adjustment made to its values during the analysis

WALD = scalars

Wald statistic (fixed terms only)

FSTATISTIC = scalars

F statistics (fixed terms only)

NDF = scalars

Numerator d.f. (fixed terms only)

DDF = scalars

Denonimator d.f. (fixed terms only)

Description

The VKEEP directive is used to copy results from a REML analysis into GenStat data structures. GenStat automatically stores the save structure for the last y-variate that was analysed using REML, and by default this save structure provides the information for VKEEP. Alternatively, you can save the information from a REML analysis in a save structure using the SAVE parameter in the REML directive, then access the information by specifying the same structure in the SAVE option of VKEEP.

Overall information from the analysis is saved using the options of VKEEP, while the parameters are used to save information for specific model terms. The terms (fixed, random or a mixture) for which you require information are defined by a formula using the TERMS parameter. The other parameters can then be used to specify structures for saving information for each of the model terms.

Options RESIDUALS and FITTEDVALUES are used to specify variates to hold the residuals and fitted values, which are defined according to the setting of the RMETHOD option, as for the REML directive. The residual variance can be stored in a scalar using option SIGMA2.

The variance-covariance matrix for the estimates of the variance component can be saved using the VCOVARIANCE option. (The estimates themselves are saved using the COMPONENTS parameter, as described below.)

The VESTIMATES option is used to save a variate containing all the variance parameters estimated in the model. The VARESTIMATES option can supply a symmetric matrix to save the variance-covariance matrix for the estimates of the variance parameters, matching the ordering and contents of VESTIMATES. The vector of labels for these parameters can be saved the VLABELS option. The ALLEFFECTS option allows you to save the full set of fixed and random effects, excluding those in the absorbing factor model, and the ALLVCOVARIANCE option can be used to store their variance-covariance matrix. This matrix will often be very large, and is useful only for looking at covariances between effects associated with different model terms, since the variance-covariance matrices for individual model terms can be stored using the VAREFFECTS parameter. The unit-by-unit variance-covariance matrix can be saved using the UVCOVARIANCE option (and this may be even larger).

The MVESTIMATES option can save a variate containing estimates of the missing values, the MVSE option saves their standard errors, and the MVUNITS option saves a list of the units that are missing.

The residual deviance from fitting the full fixed model or the submodel can be saved using options DEVIANCE and SUBDEVIANCE respectively, and the associated residual degrees of freedom can be saved using options DF and SUBDF. The degrees of freedom fitted by the (full) fixed model can be saved by the DFFIXED option, and the degrees of freedom in the random model can be saved by the DFRANDOM option. The RSS option can save the residual sum of squares from fitting the fixed model by generalized least squares.

The INDEX option saves an index of the units that were included in the the analysis. (This will depend on the patterns of missing values, if any, and the setting of the MVINCLUDE option of REML.) The MODEL option can be used to save formulae, giving the model terms fitted as fixed, random, spline or residual terms.

The formula specified by the TERMS parameter is expanded to give a series of model terms. The other parameters of VKEEP are taken in parallel with these terms. The string 'Constant' can be used within the formula to save structures associated with the constant term.

The COMPONENTS parameter allows you to save the estimated variance component for each random term in the TERMS list. Details of the covariance model fitted to each random term can be saved using the COVARIANCEMODEL parameter. The information is saved in a pointer. The contents of the pointer depend upon the complexity of the covariance model fitted and the setting of the CFORMAT parameter. First we consider the default setting: CFORMAT=variancematrices. If no covariance model has been fitted, the pointer will have two elements for the scalar (variance component) and the covariance matrix (identity - a diagonal matrix with number of rows equal to the number of levels of the term). If a covariance model has been fitted, the component matrices used to construct the model will be saved. The full covariance matrix can then be generated by taking a direct product of the component matrices and multiplying by the scalar. Alternatively, if CFORMAT=parameters, the pointer contains the component parameters of the model. The RMATRIX option provides an alternative way of saving the covariance model fitted to the residual term.

Tables of means for each term can be saved using the MEANS parameter, and standard errors of differences between the means are saved by SEDMEANS. You can also save the estimated variance-covariance matrix for the means of each term using parameter VARMEANS.

For example, you can save table of means and variance-covariance matrices of the means for terms A and B, by the command

VKEEP A+B; MEANS=MeanA,MeanB; VARMEANS=VarmeanA,VarmeanB

MeanA and MeanB will then be tables containing predicted means for factors A and B, and VarmeanA and VarmeanB will be symmetric matrices containing the variances and covariances between the table cells.

The EFFECTS parameter is used to save tables of estimated parameters. A symmetric matrix of the standard errors of differences between the effects of each term can be saved using parameter SEDEFFECTS, and the estimated variance-covariance matrix for the parameters can be saved using parameter VAREFFECTS. The DESIGNMATRIX parameter saves the design matrix used to fit the effects of each term.

You can save details of splines that have been fitted for each term using the SPLBLUP, SPLDESIGN, SPLX and SPLSMOOTH parameters. The information is saved in pointers with an element for each combination of the levels of the factors in the term (i.e. for each spline that has been fitted). The pointers elements are variates for SPLBLUP (best linear unbiased predictors) and SPLX (knot points), matrices for SPLDESIGN (design matrices), and scalars for SPLSMOOTH (smoothing parameters).

If the term involves a covariate, the CADJUSTMENT parameter can save the adjustment that will have been made to its values during the analysis. This will be zero if option CADJUST was set to none when the fixed and random models were defined by VCOMPONENTS. Alternatively, if CADJUST had its default setting of mean, each covariate will have been centred by subtracting its (weighted) mean.

The Wald statistic for a fixed term can be saved using the WALD parameter. The WMETHOD option controls whether these are from the table where terms are added sequentially to the model, or that where terms are dropped from the full fixed model. The associated F statistic, and its numerator and denominator numbers of degrees of freedom, can be saved by the FSTATISTIC, NDF and DDF parameters, respectively. The FMETHOD option specifies which algorithm to use to calculate the denominator numbers of degrees of freedom. The default, automatic, will use any stored values that have been calculated for this analysis by earlier REML, VDISPLAY or VKEEP statements; otherwise it will choose automatically between the two available methods. (See REML for more details.)

The WORKSPACE option can save the workspace setting that was used in the REML command that performed the analysis, and the EXIT option can save a code defining the exit status of the analysis. The codes (which are also used in the EXIT parameter of REML) are as follows:

0 analysis was completed successfully;

1 analysis did not converged within the specified number of iterations (but no fault occurred);

2 the fit was halted because no progress could be made;

3 the fit was halted the log-likelihood was diverging;

4 a parameter has gone out of bounds;

5 insufficient workspace;

6 no save structure is available (no REML command or a fault occurred (may be set by VKEEP but not by REML);

-1 the algorithm performed an iteration but failed for an indeterminate reason before the exit status was established;

-2 a failure occurred prior to calling the fitting algorithm.

Options: RESIDUALS, FITTEDVALUES, SIGMA2, VCOVARIANCE, VESTIMATES, VARESTIMATES, VLABELS, MVESTIMATES, MVUNITS, ALLEFFECTS, ALLVCOVARIANCE, DEVIANCE, DF, SUBDEVIANCE, SUBDF, RSS, INDEX, MODELS, RMATRIX, RMETHOD, CFORMAT, UVCOVARIANCE, DFFIXED, DFRANDOM, FMETHOD, WMETHOD, WORKSPACE, EXIT, SAVE.

Parameters: TERMS, COMPONENTS, COVARIANCEMODEL, MEANS, SEDMEANS, VARMEANS, EFFECTS, SEDEFFECTS, VAREFFECTS, DESIGNMATRIX, SPLBLUP, SPLDESIGN, SPLX, SPLSMOOTH, CADJUSTMENT, WALD, FSTATISTIC, NDF, DDF.

VKEEP directive

Options

Parameters

Description

See also