corSymm                 package:nlme                 R Documentation

General Correlation Structure

Description:

     This function is a constructor for the 'corSymm' class,
     representing a general correlation structure. The internal
     representation of this structure, in terms of unconstrained
     parameters, uses the spherical parametrization defined in Pinheiro
     and Bates (1996).  Objects created using this constructor must
     later be initialized using the  appropriate 'Initialize' method.

Usage:

     corSymm(value, form, fixed)

Arguments:

   value: an optional vector with the parameter values. Default is
          'numeric(0)', which results in a vector of zeros of
          appropriate dimension being assigned to the parameters when
          'object' is initialized (corresponding to an identity
          correlation structure).

    form: a one sided formula of the form '~ t', or '~ t | g',
          specifying a time covariate 't' and,  optionally, a grouping
          factor 'g'. A covariate for this correlation structure must
          be integer valued. When a grouping factor is present in
          'form', the correlation structure is assumed to apply only to
          observations within the same grouping level; observations
          with different grouping levels are assumed to be
          uncorrelated. Defaults to '~ 1', which corresponds to using
          the order of the observations in the data as a covariate, and
          no groups.

   fixed: an optional logical value indicating whether the coefficients
          should be allowed to vary in the optimization, or kept fixed
          at their initial value. Defaults to 'FALSE', in which case
          the coefficients are allowed to vary.

Value:

     an object of class 'corSymm' representing a general correlation
     structure.

Author(s):

     Jose Pinheiro Jose.Pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

References:

     Pinheiro, J.C. and Bates., D.M.  (1996) "Unconstrained
     Parametrizations for Variance-Covariance Matrices", Statistics and
     Computing, 6, 289-296.

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer.

See Also:

     'Initialize.corSymm',  'summary.corSymm'

Examples:

     ## covariate is observation order and grouping factor is Subject
     cs1 <- corSymm(form = ~ 1 | Subject)

     # Pinheiro and Bates, p. 225 
     cs1CompSymm <- corCompSymm(value = 0.3, form = ~ 1 | Subject)
     cs1CompSymm <- Initialize(cs1CompSymm, data = Orthodont)
     corMatrix(cs1CompSymm)

     # Pinheiro and Bates, p. 226
     cs1Symm <- corSymm(value =
             c(0.2, 0.1, -0.1, 0, 0.2, 0),
                        form = ~ 1 | Subject)
     cs1Symm <- Initialize(cs1Symm, data = Orthodont)
     corMatrix(cs1Symm)

     # example gls(..., corSpher ...)
     # Pinheiro and Bates, pp. 261, 263
     fm1Wheat2 <- gls(yield ~ variety - 1, Wheat2)
     # p. 262 
     fm2Wheat2 <- update(fm1Wheat2, corr =
        corSpher(c(28, 0.2),
          form = ~ latitude + longitude, nugget = TRUE))

     # example gls(..., corSymm ... )
     # Pinheiro and Bates, p. 251
     fm1Orth.gls <- gls(distance ~ Sex * I(age - 11), Orthodont,
                        correlation = corSymm(form = ~ 1 | Subject),
                        weights = varIdent(form = ~ 1 | age))

