gnlmm3               package:repeated               R Documentation

_G_e_n_e_r_a_l_i_z_e_d _N_o_n_l_i_n_e_a_r _M_i_x_e_d _M_o_d_e_l_s _f_o_r _T_h_r_e_e-_p_a_r_a_m_e_t_e_r _D_i_s_t_r_i_b_u_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

     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.

_U_s_a_g_e:

     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,
             typsiz=abs(p), ndigit=10, gradtol=0.00001, stepmax=10*sqrt(p%*%p),

_A_r_g_u_m_e_n_t_s:

       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.

  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.

    nest: The variable classifying observations by the unit upon which
          they were observed. Ignored if 'y' or 'envir' has class,
          response.

     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.

   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.)

   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.

   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.

  others: Arguments controlling 'nlm'.

_V_a_l_u_e:

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

_A_u_t_h_o_r(_s):

     J.K. Lindsey

_S_e_e _A_l_s_o:

     'finterp', 'fmr', 'glm', 'gnlmix', 'glmm', 'gnlr', 'gnlr3',
     'hnlmix', 'lm', 'nlr', 'nls'.

_E_x_a_m_p_l_e_s:

     library(gnlm)
     # 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 <- gnlr3(y, dist="Student", mu=mu, pmu=c(0,0,0), pshape=1, pfamily=1))
     gnlmm3(y, dist="Student", mu=mu, nest=nest, pmu=z$coef[1:3],
             pshape=z$coef[4], pfamily=z$coef[5], psd=50, points=3)
     # or equivalently
     gnlmm3(y, dist="Student", mu=~exp(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)
     # or with identity link
     print(z <- 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 <- 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 <- 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)

