Mixed Effects Model Using a Kinship Matrix.

DESCRIPTION:

A similar function to lme, but allowing for a complete specification of the covariance matrix for the random effects.

USAGE:

lmekin(fixed, data=sys.parent, random,
       varlist, variance, sparse=c(20, .05),
       rescale=T, pdcheck=T,
       subset, weight, na.action)

REQUIRED ARGUMENTS:

fixed
a two-sided linear formula object describing the fixed-effects part of the model, with the response on the left of a ~ operator and the terms, separated by + operators, on the right.
random
model statement for the random effects.

OPTIONAL ARGUMENTS:

data
a data frame containing the variables named in fixed, random, weights, subset. By default the variables are taken from the environment from which lmekin is called.
varlist
variance specifications, often of class bdsmatrix, describing the variance/covariance structure of one or more of the random effects.
variance
fixed values for the variances of selected random effects. Values of 0 indicate that the final value should be solved for.
sparse
determines which levels of random effects factor variables, if any, for which the program will use sparse matrix techniques. If a grouping variable has less than sparse[1] levels, then sparse methods are not used for that variable. If it has greater than or equal to sparse[1] unique levels, sparse methods will be used for those values which represent less than sparse[2] as a proportion of the data. For instance, if a grouping variable has 4000 levels, but 40% of the subjects are in group 1 then 3999 of the levels will be represented sparsely in the variance matrix. A single logical value of F is equivalent to setting sparse[1] to infinity.
rescale
scale any user supplied variance matrices so as to have a diagonal of 1.0.
pdcheck
verify that any user-supplied variance matrix is positive definite (SPD). It has been observed that IBD matrices produced by some software are not strictly SPD. Sometimes models with these matrices still work (throughout the iteration path, the weighted sum of variance matrices was always SPD) and sometimes they don't. In the latter case, messages about taking the log of negative numbers will occur, and the results of the fit are not necessarily trustworthy.
subset
an expression indicating the subset of the rows of data that should be used in the fit. This can be a logical vector, a numeric vector indicating which observation numbers are to be included, or a character vector of the row names to be included. All observations are included by default.
weight
optional case weights.
na.action
a function that indicates what should happen when the data contain NAs. The default action ( na.fail) causes lme to print an error message and terminate if there are any incomplete observations.

VALUE:

an object of class 'lmekin', sharing similarities with both lm and lme objects.

DETAILS:

The lme function is designed to accept a prototype for the variance matrix of the random effects, with the same prototype applying to all of the groups in the data. For familial genetic random effects, however, each family has a different covariance pattern, necessitating the input of the entire set of covariance matrices. In return, at present lmekin does not have the prototype abilities of lme.

REFERENCES:

Pinheiro, J. C. and Bates., D. M. (2000). Mixed Effect Models in S and S-PLUS. New York: Springer.

SEE ALSO:

.

EXAMPLES:

#
# Make a kinship matrix for the entire study
# These two functions are NOT fast, the makekinship one in particular
#
cfam <- makefamid(main$gid, main$momid, main$dadid)
kmat <- makekinship(cfam, main$gid, main$momid, main$dadid)

# The kinship matrix for the females only: quite a bit smaller
kid <- dimnames(kmat)[[1]]
temp <- main$sex[match(kid, main$gid)] == 'F'
fkmat <- kmat[temp,temp]

# The dimnames on kmat are the gid value, which are necessary to match
# the appropriate row/col of kmat to the analysis data set
# A look at %dense tissue on a mammogram, with age at mammogram and
# weight as covariates, and a familial random effect
fit <- lmekin(percdens ~ mammage + weight, data=anal1,
     random = ~1|gid, kmat=fkmat)