nlsList {nlme} | R Documentation

## List of nls Objects with a Common Model

### Description

`Data` is partitioned according to the levels of the grouping factor defined in `model` and individual `nls` fits are obtained for each `data` partition, using the model defined in `model`.

### Usage

    nlsList(model, data, start, control, level, subset,
            na.action = na.fail, pool = TRUE, warn.nls = NA)
    ## S3 method for class 'nlsList'
    update(object, model., ..., evaluate = TRUE)

### Arguments

`object` | an object inheriting from class `nlsList`, representing a list of fitted `nls` objects.
`model` | either a nonlinear model formula, with the response on the left of a `~` operator and an expression involving parameters, covariates, and a grouping factor separated by the `|` operator on the right, or a `selfStart` function. The method function `nlsList.selfStart` is documented separately.
`model.` | changes to the model – see `update.formula` for details.
`data` | a data frame in which to interpret the variables named in `model`.
`start` | an optional named list with initial values for the parameters to be estimated in `model`. It is passed as the `start` argument to each `nls` call and is required when the nonlinear function in `model` does not inherit from class `selfStart`.
`control` | a list of control values passed as the `control` argument to `nls`. Defaults to an empty list.
`level` | an optional integer specifying the level of grouping to be used when multiple nested levels of grouping are present.
`subset` | an optional expression indicating the subset of the rows of `data` that 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 `nlsList` to print an error message and terminate if there are any incomplete observations.
`pool` | an optional logical value that is preserved as an attribute of the returned value. This will be used as the default for `pool` in calculations of standard deviations or standard errors for summaries.
`warn.nls` | `logical` indicating if `nls()` errors (all of which are caught by `tryCatch`) should be signalled as a “summarizing” `warning`.
`...` | some methods for this generic require additional arguments. None are used in this method.
`evaluate` | If `TRUE` evaluate the new call else return the call.

### Details

As `nls(.)` is called on each sub group, and convergence of these may be problematic, these calls happen with error catching.

Since nlme version `3.1-127` (2016-04), all the errors are caught (via `tryCatch`) and if present, a “summarizing” `warning` is stored as attribute of the resulting `"nlsList"` object and signalled unless suppressed by `warn.nls = FALSE` or currently also when `warn.nls = NA` (default) and `getOption("show.error.messages")` is false.

`nlsList()` originally had used `try(*)` (with its default `silent=FALSE)` and hence all errors were printed to the console unless the global option `show.error.messages` was set to true. This still works, but has been deprecated.

### Value

a list of `nls` objects with as many components as the number of groups defined by the grouping factor. Generic functions such as `coef`, `fixed.effects`, `lme`, `pairs`, `plot`, `predict`, `random.effects`, `summary`, and `update` have methods that can be applied to an `nlsList` object.

### References

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

### See Also

`nls`, `nlme.nlsList`, `nlsList.selfStart`, `summary.nlsList`

### Examples

    fm1 <- nlsList(uptake ~ SSasympOff(conc, Asym, lrc, c0),
       data = CO2, start = c(Asym = 30, lrc = -4.5, c0 = 52))
    summary(fm1)
    cfm1 <- confint(fm1) # via profiling each % FIXME: only *one* message instead of one *each*
    stopifnot((i.ok <- which(sapply(cfm1, class) == "matrix"))
              %in% c(2:4,6:9, 12))
    ## where as (some of) the others gave errors during profile re-fitting :
    str(cfm1[- i.ok])

[Package nlme version 3.1-131 Index]