1. Home
2. VKEEP directive

# VKEEP directive

Copies information from a `REML` analysis into Genstat data structures.

### Options

`RESIDUALS` = variate Residuals from the analysis Fitted values from the analysis Variance component for the lowest stratum Variance-covariance matrix for the estimates of the variance components Saves a vector of all parameters in the variance model Variance-covariance matrix for the parameters in the variance model (as saved by `VESTIMATES`) Vector of text labels for the `VESTIMATES` and `VARESTIMATES` structures Estimates of missing values Standard errors of missing-value estimates Unit numbers of missing values Full set of estimated fixed and random effects Variance-covariance matrix for the full set of fixed and random effects not associated with the absorbing factor Residual deviance from fitting the full fixed model Residual degrees of freedom after fitting the full fixed model Residual deviance after fitting the submodel of the fixed model Residual degrees of freedom after fitting the submodel of the fixed model Residual sum of squares from fitting the `FIXED` model by general least squares with a covariance matrix derived from the estimated variance components Index of units included in the analysis Pointer to formulae giving the fixed, random, spline and residual terms fitted Saves details of the covariance model fitted to the residual Which random terms to use when calculating `RESIDUALS` (`final`, `all`, `notspline`); default uses the setting from the `REML` statement Whether the covariance matrices or the parameters are saved for a `COVARIANCEMODEL` (`variancematrices`, `parameters`); default `vari` Unit-by-unit variance-covariance matrix Number of degrees of freedom in the fixed model Number of degrees of freedom in the random model Controls how to calculate F-statistics for fixed terms (`automatic`, `none`, `algebraic`, `numerical`); default `auto` Controls which Wald statistics are saved (`add`, `drop`); default `drop` Saves the workspace setting that was used in the `REML` command Dummy to be set to the y-variate of the analysis Exit status of the fit (0 if successful) 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 Estimated variance components Saves details of the covariance model fitted to a random term Table of predicted means for each term Standard errors of differences between the predicted means Variance-covariance matrix of the means Table of estimated regression coefficients for each term Standard errors of differences between the estimated parameters of each term Variance-covariance matrix of the effects of a term Saves the design matrix for the term 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 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 Knot points for spline terms, saved in a pointer with a variate for each combination of the levels of the factors in the term 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 For a term involving covariates, saves the adjustment made to its values during the analysis Wald statistic (fixed terms only) F statistics (fixed terms only) Numerator d.f. (fixed terms only) 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`.

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'
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[]