gnls                  package:nlme                  R Documentation

_F_i_t _N_o_n_l_i_n_e_a_r _M_o_d_e_l _U_s_i_n_g _G_e_n_e_r_a_l_i_z_e_d _L_e_a_s_t _S_q_u_a_r_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     This function fits a nonlinear model using generalized least
     squares. The errors are allowed to be correlated and/or have
     unequal variances.

_U_s_a_g_e:

     gnls(model, data, params, start, correlation, weights, subset,
          na.action, naPattern, control, verbose)

_A_r_g_u_m_e_n_t_s:

   model: a two-sided formula object describing the model, with the
          response on the left of a '~' operator and  a nonlinear
          expression involving parameters and covariates on the right.
          If 'data' is given, all names used in the formula should be
          defined as parameters or variables in the data frame.

    data: an optional data frame containing the variables named in
          'model', 'correlation', 'weights',  'subset', and
          'naPattern'. By default the variables are  taken from the
          environment from which 'gnls' is called.

  params: an optional two-sided linear formula of the form
          'p1+...+pn~x1+...+xm', or list of two-sided formulas of the
          form 'p1~x1+...+xm', with possibly different models for each
          parameter. The 'p1,...,pn' represent parameters included on
          the right hand side of 'model' and 'x1+...+xm' define a
          linear model for the parameters (when the left hand side of
          the formula contains several parameters, they are all assumed
          to follow the same linear model described by the right hand
          side expression). A '1' on the right hand side of the
          formula(s) indicates a single fixed effects for the
          corresponding parameter(s). By default, the parameters are
          obtained from the names of 'start'.

   start: an optional named list, or numeric vector, with the initial
          values for the parameters in 'model'. It can be omitted when
          a 'selfStarting' function is used in 'model', in which case
          the starting estimates will be obtained from a single call to
          the 'nls' function.

correlation: an optional 'corStruct' object describing the within-group
          correlation structure. See the documentation of 'corClasses'
          for a description of the available 'corStruct' classes. If a
          grouping variable is to be used, it must be specified in the
          'form' argument to the 'corStruct' constructor. Defaults to
          'NULL', corresponding to uncorrelated  errors.

 weights: an optional 'varFunc' object or one-sided formula describing
          the within-group heteroscedasticity structure. If given as a
          formula, it is used as the argument to 'varFixed',
          corresponding to fixed variance weights. See the
          documentation on 'varClasses' for a description of the
          available 'varFunc' classes. Defaults to 'NULL',
          corresponding to homoscedastic errors.

  subset: an optional expression indicating which subset of the rows of
          'data' 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.

na.action: a function that indicates what should happen when the data
          contain 'NA's.  The default action ('na.fail') causes 'gnls'
          to print an error message and terminate if there are any
          incomplete observations.

naPattern: an expression or formula object, specifying which returned
          values are to be regarded as missing.

 control: a list of control values for the estimation algorithm to
          replace the default values returned by the function
          'gnlsControl'. Defaults to an empty list.

 verbose: an optional logical value. If 'TRUE' information on the
          evolution of the iterative algorithm is printed. Default is
          'FALSE'.

     ...: some methods for this generic require additional arguments. 
          None are used in this method.

_V_a_l_u_e:

     an object of class 'gnls', also inheriting from class 'gls',
     representing the nonlinear model fit. Generic functions such as
     'print', 'plot' and  'summary' have methods to show the results of
     the fit. See 'gnlsObject' for the components of the fit. The
     functions 'resid', 'coef', and 'fitted' can be used to extract
     some of its components.

_A_u_t_h_o_r(_s):

     Jose Pinheiro jose.pinheiro@pharma.novartis.com and Douglas Bates
     bates@stat.wisc.edu

_R_e_f_e_r_e_n_c_e_s:

     The different correlation structures available for the
     'correlation' argument are described in Box, G.E.P., Jenkins,
     G.M., and Reinsel G.C. (1994), Littel, R.C., Milliken, G.A.,
     Stroup, W.W., and Wolfinger, R.D. (1996), and Venables, W.N. and
     Ripley, B.D. (1997). The use of variance functions for linear  and
     nonlinear models is presented in detail in Carrol, R.J. and
     Rupert, D. (1988) and Davidian, M. and Giltinan, D.M. (1995).  

     Box, G.E.P., Jenkins, G.M., and Reinsel G.C. (1994) "Time Series
     Analysis: Forecasting and Control", 3rd Edition, Holden-Day. 

     Carrol, R.J. and Rupert, D. (1988) "Transformation and Weighting
     in Regression", Chapman and Hall.

     Davidian, M. and Giltinan, D.M. (1995) "Nonlinear Mixed Effects
     Models for Repeated Measurement Data", Chapman and Hall.

     Littel, R.C., Milliken, G.A., Stroup, W.W., and Wolfinger, R.D.
     (1996) "SAS Systems for Mixed Models", SAS Institute.

     Venables, W.N. and Ripley, B.D. (1997) "Modern Applied Statistics
     with S-plus", 2nd Edition, Springer-Verlag.

     Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models in S
     and S-PLUS", Springer.

_S_e_e _A_l_s_o:

     'corClasses', 'gnlsControl', 'gnlsObject', 'gnlsStruct',
     'predict.gnls', 'varClasses', 'varFunc'

_E_x_a_m_p_l_e_s:

     # variance increases with a power of the absolute fitted values
     fm1 <- gnls(weight ~ SSlogis(Time, Asym, xmid, scal), Soybean,
                 weights = varPower())
     summary(fm1)