

gnls(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', `sub-
          set', 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 formu-
          las of the form `p1~x1+...+xm', with possibly dif-
          ferent 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) indi-
          cates 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 docu-
          mentation of `corClasses' for a description of the
          available `corStruct' classes. If a grouping vari-
          able 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 `var-
          Classes' for a description of the available `var-
          Func' classes. Defaults to `NULL', corresponding
          to homoscesdatic 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 mes-
          sage 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 algo-
          rithm 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'.

_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 `gnlsOb-
     ject' 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 and Douglas Bates

_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 mod-
     els 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 Wolfin-
     ger, 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.

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

     `gnlsControl', `gnlsObject', `varFunc', `corClasses',
     `varClasses'

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

     library(nlme)
     data(Soybean)
     # variance increases with a power of the absolute fitted values
     fm1 <- gnls(weight ~ SSlogis(Time, Asym, xmid, scal), Soybean,
                 weights = varPower())
     # errors follow an auto-regressive process of order 1
     fm2 <- gnls(weight ~ SSlogis(Time, Asym, xmid, scal), Soybean,
                 correlation = corAR1())

