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 token	Which random terms to use when calculating RESIDUALS (final, all, notspline); default uses the setting from the REML statement
CFORMAT = string token	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 token	Controls how to calculate F-statistics for fixed terms (automatic, none, algebraic, numerical); default auto
WMETHOD = string token	Controls which Wald statistics are saved (add, drop); default drop
WORKSPACE = scalar	Saves the workspace setting that was used in the REML command
YVARIATE = dummy	Dummy to be set to the y-variate of the analysis
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	Denominator 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). This uses the random and residual terms, but not spline terms. It cannot be formed if the model contains sparse inverse covariance matrices, for example from VPEDIGREE.

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 MODELS option can be used to save a pointer, with labels 'Fixed', 'Spline', 'Random' and 'Residual', containing formulae for the model terms fitted as fixed, spline, random or residual terms. The labels can be specified in either lower or upper case, or any mixture. The YVARIATE option can be set to a dummy to point to the variate that was analysed (i.e. the variate defined by the Y parameter of REML).

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 converge 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);
7    value of deviance at final iteration larger than at previous iteration(s);
-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, YVARIATE, EXIT, SAVE.

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

See also

Directives: REML, VCOMPONENTS, VSTRUCTURE, VDISPLAY, VPREDICT, VSTATUS.

Procedures: VAIC, VCHECK, VFRESIDUALS, VFUNCTION, VHERITABILITY, VLSD, VMCOMPARISON, VSPREADSHEET, VUVCOVARIANCE.

Commands for: REML analysis of linear mixed models.

Example

" Examples 2:5.3.1-3, 2:5.5.1, 2:5.5.2, 2:5.9.1a, 2:5.9.2 "
" Split-plot design (Yates 1937, p.74; also John 1971, p.99)."
UNITS [NVALUES=72]
FACTOR [LEVELS=6] Blocks  
& [LEVELS=3] Wplots  
& [LEVELS=4] Subplots
GENERATE Blocks,Wplots,Subplots
FACTOR [LABELS=!T(Victory,'Golden rain',Marvellous)] Variety
& [LABELS=!T('0 cwt','0.2 cwt','0.4 cwt','0.6 cwt')] Nitrogen
VARIATE Yield; EXTRA=' of oats' 
READ [SERIAL=yes] Nitrogen,Variety,Yield 
 4 3 2 1 1 2 4 3 1 2 3 4 3 1 2 4 4 1 2 3 2 1 3 4
 2 3 4 1 4 2 3 1 1 4 2 3 3 4 1 2 1 3 4 2 2 3 4 1
 4 1 3 2 3 4 1 2 3 4 2 1 3 1 4 2 4 3 1 2 1 2 3 4 :
 3 3 3 3 1 1 1 1 2 2 2 2 3 3 3 3 1 1 1 1 2 2 2 2
 2 2 2 2 3 3 3 3 1 1 1 1 3 3 3 3 2 2 2 2 1 1 1 1
 2 2 2 2 1 1 1 1 3 3 3 3 1 1 1 1 2 2 2 2 3 3 3 3 :
156 118 140 105 111 130 174 157 117 114 161 141
104  70  89 117 122  74  89  81 103  64 132 133
108 126 149  70 144 124 121  96  61 100  91  97
109  99  63  70  80  94 126  82  90 100 116  62
 96  60  89 102 112  86  68  64 132 124 129  89
118  53 113  74 104  86  89  82  97  99 119 121 :
VCOMPONENTS [Nitrogen*Variety] Blocks/Wplots/Subplots
REML [METHOD=Fisher] Yield
VDISPLAY [PRINT=means,stratumvariances]
VLSD Nitrogen
VGRAPH
VPLOT
VARIATE [VALUES=2(1...18)2] Row
& [VALUES=(1,2)18,(3,4)18] Column
VDFIELDRESIDUALS Y=Row; X=Column
REML     [PRINT=*] Yield
VPREDICT [PRINT=description,prediction,avesed] Nitrogen
VPREDICT [PRINT=description,prediction,avesed] Variety
VPREDICT [PRINT=description,prediction,sed] Variety,Nitrogen
TABLE     [CLASSIFICATION=Nitrogen; VALUES=-3,1,1,1] Ncomp
CALCULATE Ncomp = Ncomp / 3
VTCOMPARISONS Ncomp
VKEEP TERMS=Variety; MEANS=MV; SEDMEANS=SedV; VARMEANS=VarV
& [SIGMA2=Sigma2] Blocks/Wplots; COMPONENTS=Cb,Cwp
PRINT MV
PRINT [RLPRINT=integers,labels; CLPRINT=integers; RLWIDTH=20] SedV
PRINT [RLPRINT=integers,labels; CLPRINT=integers] VarV
PRINT Cb,Cwp,Sigma2
VFRESIDUALS [RESIDUALS=residual; SERESIDUALS=seresidual;\
            FITTEDVALUES=fittedvalue; SEFITTEDVALUES=sefittedvalue]
PRINT       Yield,fittedvalue,sefittedvalue,residual,seresidual
VFIXEDTESTS [FIXEDTESTS=Drop]
PRINT       Drop[]
VFIXEDTESTS [FIXEDTESTS=Add; WMETHOD=add]
PRINT       Add[]