[Lme4-commits] r1513 - branches/roxygen/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Tue Jan 24 23:09:34 CET 2012
Author: dmbates
Date: 2012-01-24 23:09:33 +0100 (Tue, 24 Jan 2012)
New Revision: 1513
Modified:
branches/roxygen/R/AllClass.R
branches/roxygen/R/AllGeneric.R
branches/roxygen/R/GHrule.R
branches/roxygen/R/lmList.R
branches/roxygen/R/lmer.R
branches/roxygen/R/profile.R
branches/roxygen/R/sparsegrid.R
branches/roxygen/R/utilities.R
Log:
Added roxygen2 tags. Re-arranged organization.
Modified: branches/roxygen/R/AllClass.R
===================================================================
--- branches/roxygen/R/AllClass.R 2012-01-24 22:07:09 UTC (rev 1512)
+++ branches/roxygen/R/AllClass.R 2012-01-24 22:09:33 UTC (rev 1513)
@@ -1,5 +1,22 @@
### Class definitions for the package
+##' @useDynLib lme4Eigen .registration=TRUE
+NULL
+##' Class "lmList" of 'lm' Objects on Common Model
+##'
+##' Class \code{"lmList"} is an S4 class with basically a list of objects of
+##' class \code{\link{lm}} with a common model.
+##' @name lmList-class
+##' @aliases lmList-class lmList.confint-class coef,lmList-method
+##' formula,lmList-method confint,lmList-method plot,lmList-method
+##' show,lmList-method update,lmList-method plot,lmList.confint-method
+##' plot,lmList.confint,ANY-method
+##' @docType class
+##' @section Objects from the Class: Objects can be created by calls of the form
+##' \code{new("lmList", ...)} or, more commonly, by a call to
+##' \code{\link{lmList}}.
+##' @keywords classes
+##' @export
setClass("lmList",
representation(call = "call",
pool = "logical"),
@@ -12,6 +29,29 @@
### shouldn't we have "merPred" with two *sub* classes "merPredD" and "merPredS"
### for the dense and sparse X cases ?
+##' Generator object for the \code{\linkS4class{merPredD}} class
+##'
+##' The generator object for the \code{\linkS4class{merPredD}} reference class.
+##' Such an object is primarily used through its \code{new} method.
+##'
+##'
+##' @param X dense model matrix for the fixed-effects parameters, to be stored
+##' in the \code{X} field.
+##' @param Zt transpose of the sparse model matrix for the random effects. It
+##' is stored in the \code{Zt} field.
+##' @param Lambdat transpose of the sparse lower triangular relative variance
+##' factor (stored in the \code{Lambdat} field).
+##' @param Lind integer vector of the same length as the \code{"x"} slot in the
+##' \code{Lambdat} field. Its elements should be in the range 1 to the length
+##' of the \code{theta} field.
+##' @param theta numeric vector of variance component parameters (stored in the
+##' \code{theta} field).
+##' @section Methods: \describe{ \item{list("new(X, Zt, Lambdat, Lind,
+##' theta)")}{Create a new \code{\linkS4class{merPredD}} object}\item{:}{Create
+##' a new \code{\linkS4class{merPredD}} object} }
+##' @seealso \code{\linkS4class{merPredD}}
+##' @keywords classes
+##' @export
merPredD <-
setRefClass("merPredD", # Predictor class for mixed-effects models with dense X
fields =
@@ -182,6 +222,66 @@
merPredD$lock("Lambdat", "LamtUt", "Lind", "RZX", "Ut", "Utr", "V", "VtV", "Vtr",
"X", "Xwts", "Zt", "beta0", "delb", "delu", "theta", "u0")
+##' Class \code{"merPredD"} - a dense predictor reference class
+##'
+##' A reference class for a mixed-effects model predictor module with a dense
+##' model matrix for the fixed-effects parameters. The reference class is
+##' associated with a C++ class of the same name. As is customary, the
+##' generator object, \code{\link{merPredD}}, for the class has the same name as
+##' the class.
+##' @name merPredD-class
+##' @note Objects from this reference class correspond to objects in a C++
+##' class. Methods are invoked on the C++ class object using the external
+##' pointer in the \code{Ptr} field. When saving such an object the external
+##' pointer is converted to a null pointer, which is why there are redundant
+##' fields containing enough information as R objects to be able to regenerate
+##' the C++ object. The convention is that a field whose name begins with an
+##' upper-case letter is an R object and the corresponding field, whose name
+##' begins with the lower-case letter is a method. References to the
+##' external pointer should be through the method, not directly through the
+##' \code{Ptr} field.
+##' @section Extends: All reference classes extend and inherit methods from
+##' \code{"\linkS4class{envRefClass}"}.
+##' @seealso \code{\link{lmer}}, \code{\link{glmer}}, \code{\link{nlmer}},
+##' \code{\link{merPredD}}, \code{\linkS4class{merMod}}.
+##' @keywords classes
+##' @examples
+##'
+##' showClass("merPredD")
+##' str(slot(lmer(Yield ~ 1|Batch, Dyestuff), "pp"))
+##'
+NULL
+
+##' Generator objects for the response classes
+##'
+##' The generator objects for the \code{\linkS4class{lmResp}},
+##' \code{\linkS4class{lmerResp}}, \code{\linkS4class{glmResp}} and
+##' \code{\linkS4class{nlsResp}} reference classes. Such objects are
+##' primarily used through their \code{new} methods.
+##'
+##' @aliases lmResp lmerResp glmResp nlsResp
+##' @param y the numeric response vector
+##' @param family a \code{\link{family}} object
+##' @param nlmod the nonlinear model function
+##' @param nlenv an environment holding data objects for evaluation of
+##' \code{nlmod}
+##' @param pnames a character vector of parameter names
+##' @param gam a numeric vector - the initial linear predictor
+##' @note Arguments to the \code{new} methods must be named arguments.
+##' @section Methods:
+##' \describe{
+##' \item{\code{new(y=y)}:}{Create a new
+##' \code{\linkS4class{lmResp}} or \code{\linkS4class{lmerResp}} object.}
+##' \item{\code{new(family=family, y=y)}:}{Create a new
+##' \code{\linkS4class{glmResp}} object.}
+##' \item{\code{new(y=y, nlmod=nlmod, nlenv=nlenv, pnames=pnames,
+##' gam=gam)}:}{Create a new
+##' \code{\linkS4class{nlsResp}} object.}
+##' }
+##' @seealso \code{\linkS4class{lmResp}}, \code{\linkS4class{lmerResp}},
+##' \code{\linkS4class{glmResp}}, \code{\linkS4class{nlsResp}}
+##' @keywords classes
+##' @export
lmResp <- # base class for response modules
setRefClass("lmResp",
fields =
@@ -245,6 +345,44 @@
lmResp$lock("mu", "offset", "sqrtXwt", "sqrtrwt", "weights", "wtres", "y")
+##' Classes \code{"lmResp"}, \code{"glmResp"}, \code{"nlsResp"} and
+##' \code{"lmerResp"}
+##'
+##' Reference classes for response modules, including linear models,
+##' \code{"lmResp"}, generalized linear models, \code{"glmResp"}, nonlinear
+##' models, \code{"nlsResp"} and linear mixed-effects models, \code{"lmerResp"}.
+##' Each reference class is associated with a C++ class of the same name. As is
+##' customary, the generator object for each class has the same name as the
+##' class.
+##' @name lmResp-class
+##' @aliases lmResp-class glmResp-class lmerResp-class nlsResp-class
+##' @note Objects from these reference classes correspond to objects in C++
+##' classes. Methods are invoked on the C++ classes using the external pointer
+##' in the \code{ptr} field. When saving such an object the external pointer is
+##' converted to a null pointer, which is why there are redundant fields
+##' containing enough information as R objects to be able to regenerate the C++
+##' object. The convention is that a field whose name begins with an upper-case
+##' letter is an R object and the corresponding field whose name begins with the
+##' lower-case letter is a method. Access to the external pointer should be
+##' through the method, not through the field.
+##' @section Extends: All reference classes extend and inherit methods from
+##' \code{"\linkS4class{envRefClass}"}. Furthermore, \code{"glmResp"},
+##' \code{"nlsResp"} and \code{"lmerResp"} all extend the \code{"lmResp"} class.
+##' @seealso \code{\link{lmer}}, \code{\link{glmer}}, \code{\link{nlmer}},
+##' \code{\linkS4class{merMod}}.
+##' @examples
+##'
+##' showClass("lmResp")
+##' str(lmResp$new(y=1:4))
+##' showClass("glmResp")
+##' str(glmResp$new(family=poisson(), y=1:4))
+##' showClass("nlsResp")
+##' showClass("lmerResp")
+##' str(lmerResp$new(y=1:4))
+##' @keywords classes
+NULL
+
+##' @export
lmerResp <-
setRefClass("lmerResp",
fields=
@@ -276,6 +414,7 @@
setOldClass("family")
+##' @export
glmResp <-
setRefClass("glmResp",
fields=
@@ -362,6 +501,7 @@
glmResp$lock("family", "n", "eta")
+##' @export
nlsResp <-
setRefClass("nlsResp",
fields=
@@ -408,6 +548,21 @@
nlsResp$lock("nlmod", "nlenv", "pnames")
+##' Generator object for the \code{\linkS4class{glmFamily}} class
+##'
+##' The generator object for the \code{\linkS4class{glmFamily}} reference class.
+##' Such an object is primarily used through its \code{new} method.
+##'
+##'
+##' @param family a \code{\link{family}} object
+##' @note Arguments to the \code{new} method must be named arguments.
+##' @section Methods: \describe{
+##' \item{\code{new(family=family)}}{Create a new
+##' \code{\linkS4class{glmFamily}} object}
+##' }
+##' @seealso \code{\linkS4class{glmFamily}}
+##' @keywords classes
+##' @export
glmFamily <- # used in tests of family definitions
setRefClass("glmFamily",
fields=list(Ptr="externalptr", family="family"),
@@ -446,7 +601,53 @@
.Call(glmFamily_variance, ptr(), as.numeric(mu))
})
)
+##' Class \code{"glmFamily"} - a reference class for \code{\link{family}}
+##'
+##' This class is a wrapper class for \code{\link{family}} objects specifying a
+##' distibution family and link function for a generalized linear model
+##' (\code{\link{glm}}). The reference class contains an external pointer to a
+##' C++ object representing the class. For common families and link functions
+##' the functions in the family are implemented in compiled code so they can be
+##' accessed from other compiled code and for a speed boost.
+##'
+##'
+##' @name glmFamily-class
+##' @docType class
+##' @note Objects from this reference class correspond to objects in a C++
+##' class. Methods are invoked on the C++ class using the external pointer in
+##' the \code{Ptr} field. When saving such an object the external pointer is
+##' converted to a null pointer, which is why there is a redundant field
+##' \code{ptr} that is an active-binding function returning the external
+##' pointer. If the \code{Ptr} field is a null pointer, the external pointer is
+##' regenerated for the stored \code{family} field.
+##' @section Extends: All reference classes extend and inherit methods from
+##' \code{"\linkS4class{envRefClass}"}.
+##' @seealso \code{\link{family}}, \code{\link{glmFamily}}
+##' @keywords classes
+##' @examples
+##'
+##' str(glmFamily$new(family=poisson()))
+NULL
+##' Generator object for the golden search optimizer class.
+##'
+##' The generator objects for the \code{\linkS4class{golden}} class of a scalar
+##' optimizer for a parameter within an interval. The optimizer uses reverse
+##' communications.
+##'
+##'
+##' @param lower lower bound for the scalar parameter - must be finite.
+##' @param upper upper bound for the scalar parameter - must be finite.
+##' @param \dots additional, optional arguments. None are used at present.
+##' @note Arguments to the \code{new} methods must be named arguments.
+##' @section Methods:
+##' \describe{
+##' \item{\code{new(lower=lower, upper=upper)}}{Create a new
+##' \code{\linkS4class{golden}} object.}
+##' }
+##' @seealso \code{\linkS4class{golden}}
+##' @keywords classes
+##' @export
golden <-
setRefClass("golden", # Reverse communication implementation of Golden Search
fields =
@@ -482,7 +683,43 @@
xpos = function() .Call(golden_xpos, ptr())
)
)
+##' Class \code{"golden"}
+##'
+##' A reference class for a golden search scalar optimizer using reverse
+##' communication.
+##'
+##'
+##' @name golden-class
+##' @docType class
+##' @section Extends: All reference classes extend and inherit methods from
+##' \code{"\linkS4class{envRefClass}"}.
+##' @keywords classes
+##' @examples
+##'
+##' showClass("golden")
+##'
+NULL
+##' Generator object for the Nelder-Mead optimizer class.
+##'
+##' The generator objects for the \code{\linkS4class{NelderMead}} class of
+##' optimizers subject to box constraints and using reverse communications.
+##'
+##'
+##' @param lower numeric vector of lower bounds - elements may be \code{-Inf}.
+##' @param upper numeric vector of upper bounds - elements may be \code{Inf}.
+##' @param xst numeric vector of initial step sizes to establish the simplex -
+##' all elements must be non-zero.
+##' @param x0 numeric vector of starting values for the parameters.
+##' @param xt numeric vector of tolerances on the parameters.
+##' @param \dots additional, optional arguments. None are used at present.
+##' @note Arguments to the \code{new} methods must be named arguments.
+##' @section Methods:
+##' \describe{\code{new(lower, upper, xst, x0, xt)}}{Create a new
+##' \code{\linkS4class{NelderMead}} object}
+##' @seealso \code{\linkS4class{NelderMead}}
+##' @keywords classes
+##' @export
NelderMead <-
setRefClass("NelderMead", # Reverse communication implementation of Nelder-Mead simplex optimizer
fields =
@@ -534,7 +771,57 @@
xpos = function() .Call(NelderMead_xpos, ptr())
)
)
+##' Class \code{"NelderMead"}
+##'
+##' A reference class for a Nelder-Mead simplex optimizer allowing box
+##' constraints on the parameters and using reverse communication.
+##'
+##'
+##' @name NelderMead-class
+##' @docType class
+##' @note This is the default optimizer for the second stage of
+##' \code{\link{glmer}} and \code{\link{nlmer}} fits. We found that it was more
+##' reliable and often faster than more sophisticated optimizers.
+##' @section Extends: All reference classes extend and inherit methods from
+##' \code{"\linkS4class{envRefClass}"}.
+##' @seealso \code{\link{glmer}}, \code{\link{nlmer}}
+##' @references Based on code in the NLopt collection.
+##' @keywords classes
+##' @examples
+##'
+##' showClass("NelderMead")
+NULL
+##' Class "merMod" of Fitted Mixed-Effect Models
+##'
+##' A mixed-effects model represented as a \code{\linkS4class{merPredD}} object
+##' and a response module of a class that inherits from class
+##' \code{\linkS4class{lmResp}}. A model with a \code{\linkS4class{lmerResp}}
+##' response has class \code{lmerMod}; a \code{\linkS4class{glmResp}} response
+##' has class \code{glmerMod}; and a \code{\linkS4class{nlsResp}} response has
+##' class \code{nlmerMod}.
+##'
+##' @name merMod-class
+##' @aliases merMod-class lmerMod-class glmerMod-class nlmerMod-class
+##' anova,merMod-method coef,merMod-method deviance,merMod-method
+##' fitted,merMod-method formula,merMod-method logLik,merMod-method
+##' model.frame,merMod-method model.matrix,merMod-method print,merMod-method
+##' show,merMod-method simulate,merMod-method summary,merMod-method
+##' terms,merMod-method update,merMod-method VarCorr,merMod-method
+##' vcov,merMod-method print,summary.mer-method show,summary.mer-method
+##' summary,summary.mer-method vcov,summary.mer-method
+##' @docType class
+##' @section Objects from the Class: Objects are created by calls to
+##' \code{\link{lmer}}, \code{\link{glmer}} or \code{\link{nlmer}}.
+##' @seealso \code{\link{lmer}}, \code{\link{glmer}}, \code{\link{nlmer}},
+##' \code{\linkS4class{merPredD}}, \code{\linkS4class{lmerResp}},
+##' \code{\linkS4class{glmResp}}, \code{\linkS4class{nlsResp}}
+##' @keywords classes
+##' @examples
+##'
+##' showClass("merMod")
+##'
+##' @export
setClass("merMod",
representation(Gp = "integer",
call = "call",
@@ -548,8 +835,11 @@
devcomp = "list",
pp = "merPredD"))
+##' @export
setClass("lmerMod", representation(resp="lmerResp"), contains="merMod")
+##' @export
setClass("glmerMod", representation(resp="glmResp"), contains="merMod")
+##' @export
setClass("nlmerMod", representation(resp="nlsResp"), contains="merMod")
Modified: branches/roxygen/R/AllGeneric.R
===================================================================
--- branches/roxygen/R/AllGeneric.R 2012-01-24 22:07:09 UTC (rev 1512)
+++ branches/roxygen/R/AllGeneric.R 2012-01-24 22:09:33 UTC (rev 1513)
@@ -1,9 +1,6 @@
-setGeneric("lmList",
- function(formula, data, family, subset, weights,
- na.action, offset, pool, ...)
- standardGeneric("lmList"))
## utilities, these *exported*:
+##' @export getL
setGeneric("getL", function(x) standardGeneric("getL"))
fixed.effects <- function(object, ...) {
@@ -22,8 +19,40 @@
eval(mCall, parent.frame())
}
-setGeneric("sigma", function(object, ...) standardGeneric("sigma"))
+##' Extract the residual standard error from a fitted model.
+##'
+##' This is a generic function. At present the only methods are for mixed-effects
+##' models of class \code{\linkS4class{merMod}}.
+##' @title Extract residual standard error
+##' @param object a fitted model.
+##' @param ... additional, optional arguments. (None are used in the merMod method)
+##' @return the residual standard error as a scalar
+##' @export
+sigma <- function(object, ...) UseMethod("sigma")
+##' Check if a model has been fit according to the REML criterion
+##'
+##' This is a generic function. At present the only methods are for mixed-effects
+##' models of class \code{\linkS4class{merMod}}.
+##' @title Check for a REML fit
+##' @param x a fitted model.
+##' @param ... additional, optional arguments. (None are used in the merMod method)
+##' @return \code{TRUE} if \code{x} has been fit by REML, otherwise FALSE
+##' @export
+isREML <- function(x, ...) UseMethod("isREML")
+
+##' Refit a model using the maximum likelihood criterion
+##'
+##' This function is primarily used to get a maximum likelihood fit of
+##' a linear mixed-effects model for an \code{\link{anova}} comparison.
+##' @title Refit a model by maximum likelihood criterion
+##' @param x a fitted model, usually of class \code{"\linkS4class{lmerMod}"},
+##' to be refit according to the maximum likelihood criterion
+##' @param ... optional additional parameters. None are used at present.
+##' @return an object like \code{x} but fit by maximum likelihood
+##' @export
+refitML <- function(x, ...) UseMethod("refitML")
+
if (FALSE) {
setGeneric("HPDinterval",
function(object, prob = 0.95, ...) standardGeneric("HPDinterval"))
Modified: branches/roxygen/R/GHrule.R
===================================================================
--- branches/roxygen/R/GHrule.R 2012-01-24 22:07:09 UTC (rev 1512)
+++ branches/roxygen/R/GHrule.R 2012-01-24 22:09:33 UTC (rev 1513)
@@ -1,4 +1,27 @@
-GHrule <- function (ord) {
+##' Create a univariate Gauss-Hermite quadrature rule
+##'
+##' This version of Gauss-Hermite quadrature provides the node
+##' positions and weights for a scalar integral of a function
+##' multiplied by the standard normal density.
+##' @title Univariate Gauss-Hermite quadrature rule
+##' @param ord scalar integer between 1 and 25 - the order, or number of
+##' nodes and weights, in the rule. When the function being
+##' multiplied by the standard normal density is a polynomial of
+##' order 2k-1 the rule of order k integrates the product exactly.
+##' @param asMatrix logical scalar - should the result be returned as
+##' a matrix. If \code{FALSE} a data frame is returned. Defaults
+##' to \code{TRUE}.
+##' @return a matrix with \code{ord} rows and three columns which are
+##' \code{z} the node positions, \code{w} the weights and
+##' \code{ldnorm}, the logarithm of the normal density evaluated at
+##' the nodes.
+##' @examples
+##' (r5 <- GHrule(5, asMatrix=FALSE))
+##' ## second, fourth, sixth, eighth and tenth central moments of the
+##' ## standard Gaussian density
+##' with(r5, sapply(seq(2, 10, 2), function(p) sum(w * z^p)))
+##' @export
+GHrule <- function (ord, asMatrix=TRUE) {
stopifnot(length(ord) == 1,
(ord <- as.integer(ord)) > 0L,
ord < 26L)
@@ -134,5 +157,7 @@
} else fr <- rbind(fr[rev(seq_len(nr)),], fr)
if (ord > 1L) fr[seq_len(ord %/% 2L), "z"] <- -fr[seq_len(ord %/% 2L), "z"]
rownames(fr) <- NULL
- as.matrix(within(fr, ldnorm <- dnorm(z, log=TRUE)))
+ fr <- within(fr, ldnorm <- dnorm(z, log=TRUE))
+ if (asMatrix) return(as.matrix(fr))
+ fr
}
Modified: branches/roxygen/R/lmList.R
===================================================================
--- branches/roxygen/R/lmList.R 2012-01-24 22:07:09 UTC (rev 1512)
+++ branches/roxygen/R/lmList.R 2012-01-24 22:09:33 UTC (rev 1513)
@@ -12,50 +12,63 @@
list(model = form, groups = rhs[[3]])
}
-setMethod("lmList", signature(formula = "formula", data = "data.frame"),
- function(formula, data, family, subset, weights,
- na.action, offset, pool, ...)
- {
- mCall <- mf <- match.call()
- m <- match(c("family", "data", "subset", "weights",
- "na.action", "offset"), names(mf), 0)
- mf <- mf[c(1, m)]
- ## substitute `+' for `|' in the formula
+##' @title List of lm Objects with a Common Model
+##' @param formula a linear formula object of the form
+##' \code{y ~ x1+...+xn | g}. In the formula object, \code{y} represents
+##' the response, \code{x1,...,xn} the covariates, and \code{g} the
+##' grouping factor specifying the partitioning of the data according to
+##' which different \code{lm} fits should be performed.
+##' @inheritParams lmer
+##' @param family an optional family specification for a generalized
+##' linear model.
+##' @param pool logical scalar, should the variance estimate pool the
+##' residual sums of squares
+##' @param ... additional, optional arguments to be passed to the
+##' model function or family evaluation.
+##' @export
+lmList <- function(formula, data, family, subset, weights,
+ na.action, offset, pool, ...) {
+ stopifnot(is(formula, "formula"))
+ mCall <- mf <- match.call()
+ m <- match(c("family", "data", "subset", "weights",
+ "na.action", "offset"), names(mf), 0)
+ mf <- mf[c(1, m)]
+ ## substitute `+' for `|' in the formula
### FIXME: Figure out what to do here instead of subbars
-# mf$formula <- subbars(formula)
- mf$x <- mf$model <- mf$y <- mf$family <- NULL
- mf$drop.unused.levels <- TRUE
- mf[[1]] <- as.name("model.frame")
- frm <- eval(mf, parent.frame())
- mform <- modelFormula(formula)
- if (missing(family)) {
- val <- lapply(split(frm, eval(mform$groups, frm)),
- function(dat, formula)
- {
- ans <- try({
- data <- as.data.frame(dat)
- lm(formula, data)
- })
- if (inherits(ans, "try-error"))
- NULL
- else ans
- }, formula = mform$model)
- } else {
- val <- lapply(split(frm, eval(mform$groups, frm)),
- function(dat, formula, family)
- {
- ans <- try({
- data <- as.data.frame(dat)
- glm(formula, family, data)
- })
- if (inherits(ans, "try-error"))
- NULL
- else ans
- }, formula = mform$model, family = family)
- }
- if (missing(pool)) pool <- TRUE
- new("lmList", val, call = mCall, pool = pool)
- })
+ # mf$formula <- subbars(formula)
+ mf$x <- mf$model <- mf$y <- mf$family <- NULL
+ mf$drop.unused.levels <- TRUE
+ mf[[1]] <- as.name("model.frame")
+ frm <- eval(mf, parent.frame())
+ mform <- modelFormula(formula)
+ if (missing(family)) {
+ val <- lapply(split(frm, eval(mform$groups, frm)),
+ function(dat, formula)
+ {
+ ans <- try({
+ data <- as.data.frame(dat)
+ lm(formula, data)
+ })
+ if (inherits(ans, "try-error"))
+ NULL
+ else ans
+ }, formula = mform$model)
+ } else {
+ val <- lapply(split(frm, eval(mform$groups, frm)),
+ function(dat, formula, family)
+ {
+ ans <- try({
+ data <- as.data.frame(dat)
+ glm(formula, family, data)
+ })
+ if (inherits(ans, "try-error"))
+ NULL
+ else ans
+ }, formula = mform$model, family = family)
+ }
+ if (missing(pool)) pool <- TRUE
+ new("lmList", val, call = mCall, pool = pool)
+}
setMethod("coef", signature(object = "lmList"),
@@ -181,9 +194,11 @@
new("lmList.confint", aperm(val, c(3, 2, 1)))
}
+##' @importFrom graphics plot
+##' @S3method plot lmList.confint
plot.lmList.confint <- function(x, y, ...)
{
- stopifnot(require("lattice"))
+## stopifnot(require("lattice"))
arr <- as(x, "array")
dd <- dim(arr)
dn <- dimnames(arr)
Modified: branches/roxygen/R/lmer.R
===================================================================
--- branches/roxygen/R/lmer.R 2012-01-24 22:07:09 UTC (rev 1512)
+++ branches/roxygen/R/lmer.R 2012-01-24 22:09:33 UTC (rev 1513)
@@ -1,29 +1,87 @@
-##' Fit a linear mixed-effects model
-##'
-##' @title Fit a linear mixed-effects model
+##' Fit a linear mixed model (LMM)
+##'
+##' @title Fit Linear Mixed-Effects Models
+##' @concept LMM
+##' @aliases lmer
##' @param formula a two-sided linear formula object describing the
-##' fixed-effects part of the model, with the response on the left of a
-##' \code{~} operator and the terms, separated by \code{+} operators, on
-##' the right. The vertical bar character \code{"|"} separates an
-##' expression for a model matrix and a grouping factor.
+##' fixed-effects part of the model, with the response on the left of a
+##' \code{~} operator and the terms, separated by \code{+} operators, on
+##' the right. The vertical bar character \code{"|"} separates an
+##' expression for a model matrix and a grouping factor.
##' @param data an optional data frame containing the variables named in
-##' \code{formula}. By default the variables are taken from the
-##' environment from which \code{lmer} is called.
-##' @param REML logical - Should the estimates be chosen to optimize the
-##' REML criterion (as opposed to the log-likelihood)? Defaults to \code{TRUE}.
+##' \code{formula}. By default the variables are taken from the environment
+##' from which \code{lmer} is called.
+##' @param REML logical scalar - Should the estimates be chosen to optimize
+##' the REML criterion (as opposed to the log-likelihood)? Defaults to
+##' \code{TRUE}.
##' @param sparseX logical - should a sparse model matrix be used for the
-##' fixed-effects terms? Defaults to \code{FALSE}.
-##' @param control
-##' @param start
-##' @param verbose
-##' @param subset
-##' @param weights
-##' @param na.action
-##' @param offset
-##' @param contrasts
-##' @param devFunOnly
-##' @param ...
-##' @return
+##' fixed-effects terms? Defaults to \code{FALSE}. Currently inactive.
+##' @param control a named list of control parameters for the estimation
+##' algorithm, specifying only the ones to be changed from their
+##' default values. Hence defaults to an empty list.\cr
+##' Possible control options and their default values are:
+##' \describe{
+##' \item{\code{msVerbose}:}{a logical value passed as the
+##' \code{trace} argument to \code{nlminb} (see documentation on
+##' that function). Default is \code{getOption("verbose")}.}
+##' \item{\code{maxIter}:}{a positive integer passed as the
+##' \code{maxIter} argument to \code{nlminb} (see documentation on
+##' that function). Default is \code{300}.}
+##' \item{\code{maxFN}:}{a positive integer specifying the
+##' maximum number of evaluations of the deviance function allowed
+##' during the optimization. Default is \code{900}}.
+##' \item{\code{tol}:}{a positive number specifying the
+##' convergence tolerance, currently only for the PWRSS iterations
+##' in \code{glmer()}. Default is \code{0.000001}}.
+##' }
+##' @param start a named list of starting values for the parameters in the
+##' model. For \code{lmer} this can be a numeric vector or a list with one
+##' component named \code{"theta"}. Infrequently used.
+##' @param verbose integer scalar. If \code{> 0} verbose output is generated
+##' during the optimization of the parameter estimates. If \code{> 1} verbose
+##' output is generated during the individual PIRLS steps.
+##' @param subset an optional expression indicating the subset of the rows of
+##' \code{data} that should be used in the fit. This can be a logical
+##' vector, or 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.
+##' @param weights an optional vector of \sQuote{prior weights} to be used in the
+##' fitting process. Should be \code{NULL} or a numeric vector.
+##' @param na.action a function that indicates what should happen when the
+##' data contain \code{NA}s. The default action (\code{na.fail}) prints
+##' an error message and terminates if there are any incomplete
+##' observations.
+##' @param offset this can be used to specify an \emph{a priori} known component
+##' to be included in the linear predictor during fitting. This should be
+##' \code{NULL} or a numeric vector of length equal to the number of cases.
+##' One or more \code{\link{offset}} terms can be included in the formula
+##' instead or as well, and if more than one is specified their sum is used.
+##' See \code{\link{model.offset}}.
+##' @param contrasts an optional list. See the \code{contrasts.arg} of
+##' \code{model.matrix.default}.
+##' @param devFunOnly logical - return only the deviance evaluation function.
+##' @param \dots other potential arguments. A \code{method} argument was used
+##' in earlier versions of the package. Its functionality has been replaced by
+##' the \code{REML} argument.
+##' @return An object of class \code{"\linkS4class{merMod}"}, for which many
+##' methods are available. See there for details.
+##' @seealso The \code{\linkS4class{merMod}} class, \code{\link[stats]{lm}}
+##' @keywords models
+##' @examples
+##' ## linear mixed models - reference values from older code
+##' (fm1 <- lmer(Reaction ~ Days + (Days|Subject), sleepstudy))
+##' (fm2 <- lmer(Reaction ~ Days + (1|Subject) + (0+Days|Subject), sleepstudy))
+##' anova(fm1, fm2)
+##'
+##' ## dense vs sparse X --------------------------
+##' ## use more sensible example !!
+##' fm3.d <- lmer(Yield ~ 1|Batch, Dyestuff2)
+##' fm3.s <- lmer(Yield ~ 1|Batch, Dyestuff2, sparseX=TRUE)#-> warning
+##' ## check "equality"
+##' stopifnot(all.equal( coef(fm3.d), coef(fm3.s), tol = 1e-14),
+##' all.equal(sigma(fm3.d),sigma(fm3.s), tol = 1e-14),
+##' TRUE)
+##' @export
lmer <- function(formula, data, REML = TRUE, sparseX = FALSE,
control = list(), start = NULL,
verbose = 0L, subset, weights, na.action, offset,
@@ -126,54 +184,100 @@
Gp=reTrms$Gp, devcomp=list(cmp=cmp, dims=dims), pp=rho$pp, resp=rho$resp)
}## { lmer }
-mkdevfun <- function(rho, nAGQ=1L) {
- stopifnot(is.environment(rho), is(rho$resp, "lmResp"))
- ff <- NULL
- if (is(rho$resp, "lmerResp"))
- ff <- function(theta) .Call(lmer_Deviance, pp$ptr(), resp$ptr(), theta)
- else if (is(rho$resp, "glmResp")) {
- if (nAGQ < 2L) {
- rho$glmerLaplace <- glmerLaplace
- ff <- switch(nAGQ + 1L,
- function(theta)
- .Call(glmerLaplace, pp$ptr(), resp$ptr(), theta,
- u0, beta0, verbose, FALSE, tolPwrss),
- function(pars)
- .Call(glmerLaplace, pp$ptr(), resp$ptr(), pars[dpars], u0,
- pars[-dpars], verbose, TRUE, tolPwrss))
- } else {
- rho$glmerAGQ <- glmerAGQ
- rho$GQmat <- GHrule(nAGQ)
- ff <- function(pars)
- .Call(glmerAGQ, pp$ptr(), resp$ptr(), fac, GQmat, pars[dpars],
- u0, pars[-dpars], tolPwrss)
- }
- } else if (is(rho$resp, "nlsResp")) {
- if (nAGQ < 2L) {
- rho$nlmerLaplace <- nlmerLaplace
- ff <- switch(nAGQ + 1L,
- function(theta)
- .Call(nlmerLaplace, pp$ptr(), resp$ptr(), theta,
[TRUNCATED]
To get the complete diff run:
svnlook diff /svnroot/lme4 -r 1513
More information about the Lme4-commits
mailing list