[Lme4-commits] r1499 - pkg/lme4Eigen/man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Sun Jan 8 00:35:51 CET 2012
Author: dmbates
Date: 2012-01-08 00:35:51 +0100 (Sun, 08 Jan 2012)
New Revision: 1499
Added:
pkg/lme4Eigen/man/GHrule.Rd
pkg/lme4Eigen/man/NelderMead-class.Rd
pkg/lme4Eigen/man/NelderMead.Rd
pkg/lme4Eigen/man/golden-class.Rd
pkg/lme4Eigen/man/golden.Rd
Modified:
pkg/lme4Eigen/man/lmer.Rd
pkg/lme4Eigen/man/mkdevfun.Rd
Log:
Documentation updates.
Added: pkg/lme4Eigen/man/GHrule.Rd
===================================================================
--- pkg/lme4Eigen/man/GHrule.Rd (rev 0)
+++ pkg/lme4Eigen/man/GHrule.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -0,0 +1,51 @@
+\name{GHrule}
+\alias{GHrule}
+\title{
+ Nodes and weights for Gauss-Hermite quadrature
+}
+\description{
+ Returns the nodes, weights and the logarithm of the standard Gaussian
+ density for a Gauss-Hermite quadrature rule, with the standard
+ Gaussian density as the kernel, of order \code{ord}.
+}
+\usage{
+GHrule(ord)
+}
+\arguments{
+ \item{ord}{
+ positive integer not exceeding 25 - the order of the rule.
+ }
+}
+\details{
+ Univariate Gauss-Hermite quadrature evaluates the integral of a
+ function that is multiplied by a \dQuote{kernel} where the kernel is a
+ multiple of \eqn{e^{-z^2}}{exp(-z^2)} or
+ \eqn{e^{-z^2/2}}{exp(-z^2/2)}. For statisticians the natural
+ candidate is the standard normal density,
+ \eqn{\phi(z)=e^{-z^2/2}/\sqrt(2\pi)}{exp(-z^2/2)/sqrt(2*pi)}.
+ A \eqn{k}{k}th-order Gauss-Hermite formula provides knots,
+ \eqn{z_i,i=1,...,k}{z[i]}, and weights, \eqn{w_i,i=1,\dots,k}{w[i]}, such that
+ \deqn{\int_{\mathbb{R}}t(z)\phi(z)\,dz\approx\sum_{i=1}^kw_it(z_i)}{int[-Inf]^Inf t(z) phi(z) dz ~ sum[i=1]^k w[i] t(z[i])}
+}
+\note{
+ The choice of the value of \eqn{k} depends on the behavior of the function
+ \eqn{t(z)}. If \eqn{t(z)} is a polynomial of degree \eqn{k-1} then the
+ Gauss-Hermite formula for order \eqn{k} or greater provides the exact
+ value of the integral. The fact that we want \eqn{t(z)} to behave
+ like a low-order polynomial is often neglected in the formulation of
+ a Gauss-Hermite approximation to an integral.
+}
+\value{
+ a numeric matrix with \code{ord} rows and three columns named
+ \dQuote{z}, \dQuote{w} and \dQuote{ldnorm}.
+}
+\references{
+ Based on code in the \dQuote{SparseGrid} package.
+}
+%\author{}
+%\note{}
+%\seealso{}
+\examples{
+GHrule(5)
+}
+\keyword{math}
Added: pkg/lme4Eigen/man/NelderMead-class.Rd
===================================================================
--- pkg/lme4Eigen/man/NelderMead-class.Rd (rev 0)
+++ pkg/lme4Eigen/man/NelderMead-class.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -0,0 +1,63 @@
+\name{NelderMead-class}
+\Rdversion{1.1}
+\docType{class}
+\alias{NelderMead-class}
+\title{Class \code{"NelderMead"}}
+\description{
+ A reference class for a Nelder-Mead simplex optimizer allowing box
+ constraints on the parameters and using reverse communication.
+}
+\section{Extends}{
+ All reference classes extend and inherit methods from \code{"\linkS4class{envRefClass}"}.
+}
+\references{
+ Based on code in the NLopt collection.
+}
+%\author{}
+\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.}
+\seealso{\code{\link{glmer}}, \code{\link{nlmer}}}
+\examples{
+showClass("NelderMead")
+}
+\keyword{classes}
+\section{Fields}{
+ \describe{
+ \item{\code{Ptr}:}{\code{externalptr} to the instance of the C++ class}
+ \item{\code{lowerbd}:}{\code{numeric} vector of lower bounds - some
+ or all of the elements may be \code{-Inf} for parameters with no
+ lower bound.}
+ \item{\code{upperbd}:}{\code{numeric} vector of upper bounds - some
+ or all of the elements may be \code{Inf} for parameters with no
+ upper bound.}
+ \item{\code{xstep}:}{\code{numeric} vector of initial steps to
+ generate the simplex. All the elements must be non-zero.}
+ \item{\code{xtol}:}{\code{numeric} vector of tolerances on the parameters}
+ }
+}
+\section{Methods}{
+ \describe{
+ \item{\code{setFtolAbs(fta)}:}{set the absolute tolerance on the
+ function value.}
+ \item{\code{newf(value)}:}{provide the function value at the current
+ \code{xeval} vector.}
+ \item{\code{setMaxeval(mxev)}:}{set the maximum number of function evaluations.}
+ \item{\code{value()}:}{return the lowest function value previously recorded}
+ \item{\code{setMinfMax(minf)}:}{set the maximum value to be declared
+ as the minimum function value. Defaults to \code{-Inf}.}
+ \item{\code{setFtolRel(ftr)}:}{set the relative tolerance on the
+ function value.}
+ \item{\code{setForceStop(stp)}:}{Force the iterations to stop. This
+ method is unlikely to be used in an algorithm using reverse communication.}
+ \item{\code{ptr()}:}{return the external pointer, \code{Ptr},
+ regenerating the C++ object if necessary.}
+ \item{\code{xeval()}:}{next value of the parameters at which to
+ evaluate the objective function}
+ \item{\code{setIprint(iprint)}:}{set the parameter controlling
+ printing of intermediate results. If \code{iprint > 0} then the
+ function and parameter values are printed every \code{iprint} evaluations.}
+ \item{\code{xpos()}:}{position of the minimum objective value seen
+ to this point.}
+ }
+}
Added: pkg/lme4Eigen/man/NelderMead.Rd
===================================================================
--- pkg/lme4Eigen/man/NelderMead.Rd (rev 0)
+++ pkg/lme4Eigen/man/NelderMead.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -0,0 +1,26 @@
+\name{NelderMead}
+\alias{NelderMead}
+\title{Generator object for the Nelder-Mead optimizer class.}
+\section{Methods}{
+ \describe{
+ \item{\code{new(lower, upper, xst, x0, xt, \dots)}:}{Create a new
+ \code{\linkS4class{NelderMead}} object.}
+ }
+}
+\arguments{
+ \item{lower}{numeric vector of lower bounds - elements may be
+ \code{-Inf}.}
+ \item{upper}{numeric vector of upper bounds - elements may be
+ \code{Inf}.}
+ \item{xst}{numeric vector of initial step sizes to establish the
+ simplex - all elements must be non-zero.}
+ \item{x0}{numeric vector of starting values for the parameters.}
+ \item{xt}{numeric vector of tolerances on the parameters.}
+ \item{\dots}{additional, optional arguments. None are used at present.}
+}
+\note{Arguments to the \code{new} methods must be named arguments.}
+\description{The generator objects for the
+ \code{\linkS4class{NelderMead}} class of optimizers subject to box
+ constraints and using reverse communications.}
+\seealso{\code{\linkS4class{NelderMead}}}
+\keyword{classes}
Added: pkg/lme4Eigen/man/golden-class.Rd
===================================================================
--- pkg/lme4Eigen/man/golden-class.Rd (rev 0)
+++ pkg/lme4Eigen/man/golden-class.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -0,0 +1,43 @@
+\name{golden-class}
+\Rdversion{1.1}
+\docType{class}
+\alias{golden-class}
+\title{Class \code{"golden"}}
+\description{
+ A reference class for a golden search scalar optimizer using reverse
+ communication.
+}
+\section{Extends}{
+ All reference classes extend and inherit methods from \code{"\linkS4class{envRefClass}"}.
+}
+%\references{}
+%\author{}
+%\note{}
+%\seealso{}
+\examples{
+showClass("golden")
+}
+\keyword{classes}
+\section{Fields}{
+ \describe{
+ \item{\code{Ptr}:}{\code{externalptr} to the instance of the C++ class}
+ \item{\code{lowerbd}:}{numeric scalar - the lower bound on the
+ interval within which to minimize the objective.}
+ \item{\code{upperbd}:}{numeric scalar - the upper bound on the
+ interval within which to minimize the objective.}
+ }
+}
+\section{Methods}{
+ \describe{
+ \item{\code{newf(value)}:}{provide the function value at the current
+ \code{xeval}.}
+ \item{\code{value()}:}{return the lowest function value recorded to
+ this point.}
+ \item{\code{ptr()}:}{return the external pointer, \code{Ptr},
+ regenerating the C++ object if necessary.}
+ \item{\code{xeval()}:}{next value of the parameter at which to
+ evaluate the objective function.}
+ \item{\code{xpos()}:}{position of the minimum objective value seen
+ to this point.}
+ }
+}
Added: pkg/lme4Eigen/man/golden.Rd
===================================================================
--- pkg/lme4Eigen/man/golden.Rd (rev 0)
+++ pkg/lme4Eigen/man/golden.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -0,0 +1,20 @@
+\name{golden}
+\alias{golden}
+\title{Generator object for the Nelder-Mead optimizer class.}
+\section{Methods}{
+ \describe{
+ \item{\code{new(lower, upper, \dots)}:}{Create a new
+ \code{\linkS4class{golden}} object.}
+ }
+}
+\arguments{
+ \item{lower}{lower bound for the scalar parameter - must be finite.}
+ \item{upper}{upper bound for the scalar parameter - must be finite.}
+ \item{\dots}{additional, optional arguments. None are used at present.}
+}
+\note{Arguments to the \code{new} methods must be named arguments.}
+\description{The generator objects for the
+ \code{\linkS4class{golden}} class of a scalar optimizer for a
+ parameter within an interval. The optimizer uses reverse communications.}
+\seealso{\code{\linkS4class{golden}}}
+\keyword{classes}
Modified: pkg/lme4Eigen/man/lmer.Rd
===================================================================
--- pkg/lme4Eigen/man/lmer.Rd 2012-01-07 23:35:27 UTC (rev 1498)
+++ pkg/lme4Eigen/man/lmer.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -13,20 +13,17 @@
\usage{
lmer(formula, data, REML = TRUE, sparseX = FALSE,
control = list(), start = NULL, verbose = 0L,
- %doFit = TRUE, %compDev = TRUE, _support too - FIXME? _
subset, weights, na.action, offset, contrasts = NULL,
- devFunOnly = FALSE,
- \dots)
-
+ devFunOnly = FALSE, \dots)
glmer(formula, data, family = gaussian, sparseX = FALSE,
control = list(), start = NULL, verbose = 0, nAGQ = 1,
compDev = TRUE, subset, weights, na.action, offset,
contrasts = NULL, mustart, etastart, devFunOnly = FALSE,
- tolPwrss = 1e-06, \dots)
-
-nlmer(formula, data, family = gaussian, start = NULL,
- verbose = 0L, nAGQ = 1L, doFit = TRUE, subset, weights,
- na.action, offset, contrasts = NULL, devFunOnly = 0L, \dots)
+ tolPwrss = 1e-10, optimizer = c("NelderMead", "bobyqa"), \dots)
+nlmer(formula, data, control=list(), start = NULL, verbose = 0L,
+ nAGQ = 1L, subset, weights, na.action, offset,
+ contrasts = NULL, devFunOnly = 0L, tolPwrss = 1e-10,
+ optimizer = c("NelderMead", "bobyqa"), \dots)
}
\arguments{
\item{formula}{a two-sided linear formula object describing the
@@ -82,6 +79,11 @@
\item{tolPwrss}{numeric scalar - the tolerance for declaring
convergence in the penalized weighted residual sum-of-squares
step. Defaults to 1e-06.}
+ \item{optimizer}{which optimizer to use in the second phase of
+ optimization. The default is \code{\link{NelderMead}} and the
+ alternative is \code{\link{bobyqa}}. For difficult model fits we
+ have found \code{\link{NelderMead}} to be more reliable but
+ occasionally slower than \code{\link{bobyqa}}.}
\item{\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} and \code{nAGQ} arguments.}
@@ -165,6 +167,12 @@
## using nAGQ=0L only gets close to the optimum
(gm1a <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
cbpp, binomial, nAGQ = 0L))
+## using nAGQ=9L provides a better evaluation of the deviance
+(gm1b <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
+ cbpp, binomial, nAGQ = 9L))
+## check with nAGQ=25L
+(gm1c <- glmer(cbind(incidence, size - incidence) ~ period + (1 | herd),
+ cbpp, binomial, nAGQ = 25L))
## GLMM with individual-level variability (accounting for overdispersion)
cbpp$obs <- 1:nrow(cbpp)
Modified: pkg/lme4Eigen/man/mkdevfun.Rd
===================================================================
--- pkg/lme4Eigen/man/mkdevfun.Rd 2012-01-07 23:35:27 UTC (rev 1498)
+++ pkg/lme4Eigen/man/mkdevfun.Rd 2012-01-07 23:35:51 UTC (rev 1499)
@@ -9,16 +9,14 @@
deviance.
}
\usage{
-mkdevfun(pp, resp, rho, nAGQ=1L)
+mkdevfun(rho, nAGQ=1L)
}
\arguments{
- \item{pp}{a prediction module, typically of class
- \code{\linkS4class{merPredD}}.%% FIXME merPred --> *D and *S ??
- }
- \item{resp}{a response module, e.g., of class
+ \item{rho}{an environment containing \code{pp},
+ a prediction module, typically of class
+ \code{\linkS4class{merPredD}},%% FIXME merPred --> *D and *S ??
+ and \code{resp}, a response module, e.g., of class
\code{\linkS4class{lmerResp}}.}
- \item{rho}{an environment containing auxillary information for the
- function evaluation}
\item{nAGQ}{scalar integer - the number of adaptive Gauss-Hermite
quadrature points. A value of 0 indicates that both the
fixed-effects parameters and the random effects are optimized by the
More information about the Lme4-commits
mailing list