regress               package:regress               R Documentation

_F_i_t _a _G_a_u_s_s_i_a_n _L_i_n_e_a_r _M_o_d_e_l _i_n _w_h_i_c_h _t_h_e _C_o_v_a_r_i_a_n_c_e _S_t_r_u_c_t_u_r_e _i_s
_a _L_i_n_e_a_r _C_o_m_b_i_n_a_t_i_o_n _o_f _K_n_o_w_n _M_a_t_r_i_c_e_s _b_y _M_a_x_i_m_i_s_i_n_g _t_h_e _R_e_s_i_d_u_a_l _L_o_g
_L_i_k_e_l_i_h_o_o_d

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

 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.

print.level: 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.

_D_e_t_a_i_l_s:

     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 returned values in the regress object are on the
     variance parameter scale.  The summary of the regress object takes
     this into consideration and all outputted information is on the
     variance component scale.

_V_a_l_u_e:

   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 parameter estimates, interpretation depends on value
          of 'pos' (on log scale if pos > 0).

sigma.cov: Covariance matrix for the variance parameter 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
          'summary'.

_A_u_t_h_o_r(_s):

     David Clifford, Peter McCullagh.

_R_e_f_e_r_e_n_c_e_s:

     G. Tunnicliffe Wilson, "On the use of marginal likelihood in time
     series model estimation."  JRSS B, Vol 51, No 1, 1989, 15-27.

_E_x_a_m_p_l_e_s:

       ## Example of Random Effects model from Venables and Ripley, page 205
       library("nlme")
       library("regress")
       data(Oats)
       names(Oats) <- c("B","V","N","Y")
       
       ## Using regress
       oats.reg <- regress(Y~N+V,~B+I(B:V),identity=TRUE,print.level=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)

