gnlmm3: Generalized Nonlinear Mixed Models for Three-parameter Distributions

Description

gnlmm3 fits user-specified nonlinear regression equations to one or more parameters of the common three parameter distributions. The intercept of the location regression has a normally-distributed random effect. This normal mixing distribution is computed by Gauss-Hermite integration.

Usage

gnlmm3(
  y = NULL,
  distribution = "normal",
  mu = NULL,
  shape = NULL,
  nest = NULL,
  family = NULL,
  linear = NULL,
  pmu = NULL,
  pshape = NULL,
  pfamily = NULL,
  psd = NULL,
  exact = FALSE,
  wt = 1,
  scale = NULL,
  points = 10,
  common = FALSE,
  delta = 1,
  envir = parent.frame(),
  print.level = 0,
  typsize = abs(p),
  ndigit = 10,
  gradtol = 1e-05,
  stepmax = 10 * sqrt(p %*% p),
  steptol = 1e-05,
  iterlim = 100,
  fscale = 1
)

Value

A list of class gnlm is returned that contains all of the relevant information calculated, including error codes.

Arguments

y: A response vector for uncensored data, a two column matrix for binomial data or censored data, with the second column being the censoring indicator (1: uncensored, 0: right censored, -1: left censored), or an object of class, response (created by restovec) or repeated (created by rmna) or lvna). If the repeated data object contains more than one response variable, give that object in envir and give the name of the response variable to be used here.
distribution: Either a character string containing the name of the distribution or a function giving the -log likelihood and calling the location, shape, and family functions. Distributions are Box-Cox transformed normal, generalized inverse Gauss, generalized logistic, Hjorth, generalized gamma, Burr, generalized Weibull, power exponential, Student t, generalized extreme value, power variance function Poisson, and skew Laplace. (For definitions of distributions, see the corresponding [dpqr]distribution help.)
mu: A user-specified function of pmu, and possibly linear, giving the regression equation for the location. This may contain a linear part as the second argument to the function. It may also be a formula beginning with ~, specifying a either linear regression function for the location parameter in the Wilkinson and Rogers notation or a general function with named unknown parameters. If it contains unknown parameters, the keyword linear may be used to specify a linear part. If nothing is supplied, the location is taken to be constant unless the linear argument is given.
shape: A user-specified function of pshape, and possibly linear and/or mu, giving the regression equation for the dispersion or shape parameter. This may contain a linear part as the second argument to the function and the location function as last argument (in which case shfn must be set to TRUE). It may also be a formula beginning with ~, specifying either a linear regression function for the shape parameter in the Wilkinson and Rogers notation or a general function with named unknown parameters. If it contains unknown parameters, the keyword linear may be used to specify a linear part and the keyword mu to specify a function of the location parameter. If nothing is supplied, this parameter is taken to be constant unless the linear argument is given. This parameter is the logarithm of the usual one.
nest: The variable classifying observations by the unit upon which they were observed. Ignored if y or envir has class, response.
family: A user-specified function of pfamily, and possibly linear, for the regression equation of the third (family) parameter of the distribution. This may contain a linear part that is the second argument to the function. It may also be a formula beginning with ~, specifying either a linear regression function for the family parameter in the Wilkinson and Rogers notation or a general function with named unknown parameters. If neither is supplied, this parameter is taken to be constant unless the linear argument is given. In most cases, this parameter is the logarithm of the usual one.
linear: A formula beginning with ~ in W&R notation, specifying the linear part of the regression function for the location parameter or list of two such expressions for the location and/or shape parameters.
pmu: Vector of initial estimates for the location parameters. If mu is a formula with unknown parameters, their estimates must be supplied either in their order of appearance in the expression or in a named list.
pshape: Vector of initial estimates for the shape parameters. If shape is a formula with unknown parameters, their estimates must be supplied either in their order of appearance in the expression or in a named list.
pfamily: Vector of initial estimates for the family parameters. If family is a formula with unknown parameters, their estimates must be supplied either in their order of appearance in the expression or in a named list.
psd: Initial estimate of the standard deviation of the normal mixing distribution.
exact: If TRUE, fits the exact likelihood function for continuous data by integration over intervals of observation, i.e. interval censoring.
wt: Weight vector.
scale: The scale on which the random effect is applied: identity, log, logit, reciprocal, or exp.
points: The number of points for Gauss-Hermite integration of the random effect.
common: If TRUE, at least two of mu, shape, and family must both be either functions with, as argument, a vector of parameters having some or all elements in common between them so that indexing is in common between them or formulae with unknowns. All parameter estimates must be supplied in pmu. If FALSE, parameters are distinct between the two functions and indexing starts at one in each function.
delta: Scalar or vector giving the unit of measurement (always one for discrete data) for each response value, set to unity by default. Ignored if y has class, response. For example, if a response is measured to two decimals, delta=0.01. If the response is transformed, this must be multiplied by the Jacobian. The transformation cannot contain unknown parameters. For example, with a log transformation, delta=1/y. (The delta values for the censored response are ignored.)
envir: Environment in which model formulae are to be interpreted or a data object of class, repeated, tccov, or tvcov; the name of the response variable should be given in y. If y has class repeated, it is used as the environment.
print.level: Arguments for nlm.
typsize: Arguments for nlm.
ndigit: Arguments for nlm.
gradtol: Arguments for nlm.
stepmax: Arguments for nlm.
steptol: Arguments for nlm.
iterlim: Arguments for nlm.
fscale: Arguments for nlm.

Author

J.K. Lindsey

Details

The scale of the random effect is the link function to be applied. For example, if it is log, the supplied mean function, mu, is transformed as exp(log(mu)+sd), where sd is the random effect parameter.

It is recommended that initial estimates for pmu, pshape, and pfamily be obtained from gnlr3.

Nonlinear regression models can be supplied as formulae where parameters are unknowns in which case factor variables cannot be used and parameters must be scalars. (See finterp.)

The printed output includes the -log likelihood (not the deviance), the corresponding AIC, the maximum likelihood estimates, standard errors, and correlations.

Examples

Run this code


# data objects
sex <- c(0,1,1)
sx <- tcctomat(sex)
#dose <- matrix(rpois(30,10),nrow=3)
dose <- matrix(c(8,9,11,9,11,11,7,8,7,12,8,8,9,10,15,10,9,9,20,14,4,7,
	4,13,10,13,6,13,11,17),nrow=3)
dd <- tvctomat(dose)
# vectors for functions
dose <- as.vector(t(dose))
sex <- c(rep(0,10),rep(1,20))
nest <- rbind(rep(1,10),rep(2,10),rep(3,10))
#y <- (rt(30,5)+exp(0.2+0.3*dose+0.5*sex+rep(rnorm(3),rep(10,3))))*3
y <- c(62.39712552,196.94419614,2224.74940087,269.56691601,12.86079662,
	14.96743546, 47.45765042,156.51381687,508.68804438,281.11065302,
	92.32443655, 81.88000484, 40.26357733, 13.04433670, 15.58490237,
	63.62154867, 23.69677549, 53.52885894, 88.02507682, 34.04302506,
	44.28232323,116.80732423,106.72564484, 25.09749055, 12.61839145,
	-0.04060996,153.32670123, 63.25866087, 17.79852591,930.52558064)
y <- restovec(matrix(y, nrow=3), nest=nest, name="y")
reps <- rmna(y, ccov=sx, tvcov=dd)
#
# log linear regression with Student t distribution
mu <- function(p) exp(p[1]+p[2]*sex+p[3]*dose)
## print(z <- gnlm::gnlr3(y, dist="Student", mu=mu, pmu=c(0,0,0), pshape=1, pfamily=1))
## starting values for pmu and pshape from z$coef[1:3] and z$coef[4] respectively
## starting value for pfamily in z$coef[5]
gnlmm3(y, dist="Student", mu=mu, nest=nest, pmu=c(3.69,-1.19, 0.039),
       pshape=5, pfamily=0, psd=40, points=3)
# or equivalently
gnlmm3(y, dist="Student", mu=~exp(b0+b1*sex+b2*dose), nest=nest,
       pmu=c(3.69,-1.19, 0.039), pshape=5, pfamily=0, psd=40,
       points=3, envir=reps)
if (FALSE) {
# or with identity link
print(z <- gnlm::gnlr3(y, dist="Student", mu=~sex+dose, pmu=c(0.1,0,0), pshape=1,
	pfamily=1))
gnlmm3(y, dist="Student", mu=~sex+dose, nest=nest, pmu=z$coef[1:3],
	pshape=z$coef[4], pfamily=z$coef[5], psd=50, points=3)
# or
gnlmm3(y, dist="Student", mu=~b0+b1*sex+b2*dose, nest=nest, pmu=z$coef[1:3],
	pshape=z$coef[4], pfamily=z$coef[5], psd=50, points=3, envir=reps)
#
# nonlinear regression with Student t distribution
mu <- function(p) p[1]+exp(p[2]+p[3]*sex+p[4]*dose)
print(z <- gnlm::gnlr3(y, dist="Student", mu=mu, pmu=c(1,1,0,0), pshape=1,
	pfamily=1))
gnlmm3(y, dist="Student", mu=mu, nest=nest, pmu=z$coef[1:4],
	pshape=z$coef[5], pfamily=z$coef[6], psd=50, points=3)
# or
mu2 <- function(p, linear) p[1]+exp(linear)
gnlmm3(y, dist="Student", mu=mu2, linear=~sex+dose, nest=nest,
	pmu=z$coef[1:4], pshape=z$coef[5], pfamily=z$coef[6], psd=50,
	points=3)
# or
gnlmm3(y, dist="Student", mu=~a+exp(linear), linear=~sex+dose, nest=nest,
	pmu=z$coef[1:4], pshape=z$coef[5], pfamily=z$coef[6], psd=50,
	points=3)
# or
gnlmm3(y, dist="Student", mu=~b4+exp(b0+b1*sex+b2*dose), nest=nest,
	pmu=z$coef[1:4], pshape=z$coef[5], pfamily=z$coef[6], psd=50,
	points=3, envir=reps)
#
# include regression for the shape parameter with same mu function
shape <- function(p) p[1]+p[2]*sex
print(z <- gnlm::gnlr3(y, dist="Student", mu=mu, shape=shape, pmu=z$coef[1:4],
	pshape=c(z$coef[5],0), pfamily=z$coef[6]))
gnlmm3(y, dist="Student", mu=mu, shape=shape, nest=nest,
	pmu=z$coef[1:4], pshape=z$coef[5:6], pfamily=z$coef[7],
	psd=5, points=3)
# or
gnlmm3(y, dist="Student", mu=mu, shape=shape, nest=nest, pmu=z$coef[1:4],
	pshape=z$coef[5:6], pfamily=z$coef[7], psd=5, points=3,
	envir=reps)
# or
gnlmm3(y, dist="Student", mu=~b4+exp(b0+b1*sex+b2*dose), shape=~a1+a2*sex,
	nest=nest, pmu=z$coef[1:4], pshape=z$coef[5:6],
	pfamily=z$coef[7], psd=5, points=3, envir=reps)
}

Run the code above in your browser using DataLab