

   FFiitt NNoonnlliinneeaarr MMooddeell UUssiinngg GGeenneerraalliizzeedd LLeeaasstt SSqquuaarreess

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

   AArrgguummeenntts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 the `corStruct' construc-
             tor. Defaults to `NULL', corresponding to uncorre-
             lated 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 saying which subset of the
             rows of `data' should  be  used in the fit. This
             can be a logical vector, or a numeric vector indi-
             cating 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'.

   DDeessccrriippttiioonn::

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

   VVaalluue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Auutthhoorr((ss))::

        Jose Pinheiro and Douglas Bates

   RReeffeerreennccees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.
        (1997), 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. (1997) "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Seeee AAllssoo::

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

   EExxaammpplleess::

        library(lme)
        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())

