regress {regress}R Documentation

Fit a Gaussian Linear Model with Linear Covariance Structure

Description

Fits Gaussian linear models in which the covariance structure can be expressed as a linear combination of known matrices. For example, block effects models and spatial models that include a nugget effect. Fits model by maximising the residual log likelihood, also known as the REML log likelihood or restricted log likelihood. Uses a Newton-Raphson algorithm to maximise the residual log likelihood.

Usage

regress(formula, Vformula, identity=TRUE, start=NULL, fraction=1,
pos, verbose=0, gamVals=NULL, maxcyc=50, tol=1e-4, data, print.level)

Arguments

formula a symbolic description of the model to be fitted. The details of model specification are the same as for lm
Vformula Specifies the matrices to include in the covariance structure. Each term is either a symmetric matrix, or a factor. Independent Gaussian random effects are included by passing the corresponding block factor.
identity Logical variable, includes the identity as the final matrix of the covariance structure. Default is TRUE
start Specify the variance components at which the Newton-Raphson algorithm starts. Default value is rep(var(y),k).
fraction The proportion of each step to take. Default value is 1. Useful to prevent taking huge steps in the first few iterations.
pos logical vector of length k, where k is the number of matrices in the covariance structure. Indicates which variance components are positive (TRUE) and which are real (FALSE). Important for multivariate problems.
verbose Controls level of time output, takes values 0, 1 or 2, Default is 0, level 1 gives parameter estimates and value of log likelihood at each stage.
gamVals When k=2, the marginial log likelihood based on the residual configuration statistic (see Tunnicliffe Wilson(1989)), is evaluated first at (1-gam) V1 + gam V2 for each value of gam in gamVals, a set of values from the unit interval. Subsequently the Newton-Raphson algorithm is started at variance components corresponding the the value of gam that has the highest marginal log likelihood. This is overridden if start is specified.
maxcyc Maximum number of cycles allowed. Default value is 50. A warning is output to the screen if this is reached before convergence.
tol Convergence criteria. If the change in residual log likelihood for one cycle is less than tol the algorithm finishes. Default value is 1e-4.
data an optional data frame containing the variables in the model. By default the variables are taken from 'environment(formula)', typically the environment from which 'regress' is called.
print.level Deprecated

Details

As the code is running it outputs the variance components, and the residual log likelihood at each iteration.

To avoid confusion over terminology. I define variance components to be the multipliers of the matrices and variance parameters to the parameter space over which the Newton-Raphson algorithm is run. I can force a component to be positive be defining the corresponding variance parameter on the log scale.

All output to the screen is for variance components (i.e. the multiples of the matrices). Values for start are on the variance component scale. Use pos to force certain variance components to be positive.

NOTE: The final stage of the algorithm converts the estimates of the variance components and the Fisher Information to the usual linear scale, i.e. as if pos were a vector of zeroes.

NOTE: No predict functionality is provided with regress due to some ambiguity. Are we predicting conditional on the observed data. Are we predicting observations from the fitted model itself? It is all normal anyway so it is straightforward, see our paper on regress.

Value

trace Matrix with one row for each iteration of algorithm. Each row contains the residual log likelihood, marginal log likelihood, variance parameters and increments.
llik Value of the marginal log likelihood at the point of convergence.
cycle Number of cycles to convergence.
rdf Residual degrees of freedom.
beta Estimate of the linear effects.
beta.cov Estimate of the covariance structure for terms in beta.
beta.se Standard errors for terms in beta.
sigma Variance component estimates, interpretation does not depend on value of pos
sigma.cov Covariance matrix for the variance component estimates based on the Fisher Information at the point of convergence.
W Inverse of covariance matrix at point of convergence.
Q $I - X^T (X^T W X)^-1 X^T W$ at point of convergence.
fitted $X beta$, the fitted values.
predicted If identity=TRUE, decompose y into the part associated with the identity and that assosicated with the rest of the variance structure, this second part is the predicted values. If $Sigma = V1 + V2$ at point of convergence then y = V1 W y + V2 W y is the decomposition.
pos Indicator for the scale for each variance parameter.
Vnames Names associated with each variance component, used in print.regress.
formula Copy of formula
Vformula Updated version of Vformula to include identity if necessary
model Response, covariates and matrices/factors to be used for model fitting

Author(s)

David Clifford, Peter McCullagh.

References

G. Tunnicliffe Wilson, "On the use of marginal likelihood in time series model estimation." JRSS B, Vol 51, No 1, 1989, 15-27. D. Clifford and P. McCullagh, "The regress Library" R News.

Examples

  ## Example of Random Effects model from Venables and Ripley, page 205
  library("nlme")
  ##library("regress")
  data(Oats)
  names(Oats) <- c("B","V","N","Y")
  Oats$N <- as.factor(Oats$N)

  ## Using regress
  oats.reg <- regress(Y~N+V,~B+I(B:V),identity=TRUE,verbose=1,data=Oats)
  summary(oats.reg)

  ## Using lme
  oats.lme <- lme(Y~N+V,random=~1|B/V,data=Oats,method="REML")
  summary(oats.lme)

[Package regress version 1.1-2 Index]