Fit a Nonlinear Model by Minimum Sums

DESCRIPTION:

Minimizes a sum of nonlinear functions over parameters in a data frame.

USAGE:

ms(formula, data = <<see below>>, start = <<see below>>, 
   control = <<see below>>, trace = F) 

REQUIRED ARGUMENTS:

formula
a formula specifying the nonlinear model. There will be no left side to the ~ expression, and the right side of the formula is essentially an arbitrary S-PLUS expression.

OPTIONAL ARGUMENTS:

data
a data frame in which to do the computations. In addition to the usual data variables, the data frame may contain parameters (set, typically, by using the assignment form of parameters or param) that establish initial values.
start
a list or numerical vector. Although it is optional, use of start is recommended for unambiguous specification of the parameters. If start is omitted, the assumption is that any names occurring in formula that are not variables in the data frame are parameters. The list form of start allows the individual parameter names to refer to subsets of the parameters of arbitrary length. If a numeric starting vector is supplied, the named parameters must each be of length 1.
control
list of control values to be used in the iteration. See ms.control for the possible control parameters and their default settings.
trace
logical value or character string naming a tracing function. The built-in functions that are suitable are trace.ms and browser.ms. If trace is TRUE, then trace.ms is used. No tracing is performed when trace is FALSE.

VALUE:

an object of class "ms" with the final parameters, function and derivative values, and some internal information about the fit. See ms.object.

SIDE EFFECTS:

if tracing is in effect, then there will be printing and/or browsing.

DETAILS:

The standard tracer function is trace.ms. Also available, by trace="browser.ms", is an invocation of the interactive browser, in a frame containing all the fitting information. See the definition of these functions for the calling sequence to any do-it-yourself tracer function. The use of special trace functions with ms should be distinguished from the standard S-PLUS tracing. The latter is simpler and usually the best way to track the modeling. Tracing through ms allows access in S-PLUS to the internal flags of the Fortran minimization algorithm. If you don't need to look at that information, you can usually trace a function you have written to compute the model information. Often tracing on exit, for example, trace(mymodel, exit = browser) is a good way to look at your function mymodel just before it returns the next model values. (Remember to untrace it before you edit it.)

CONVERGENCE MESSAGES:

The possible messages, and their meanings, are as follows:

X

successive parameter values are within a specified tolerance of each other.

RELATIVE
successive objective values are within a specified tolerance of each other.
BOTH
both of the above.
ABSOLUTE
applies only if the minimum is meant to be zero, as for example solving a system of nonlinear equations using a least-squares objective.
SINGULAR
this happens when the optimization algorithm thinks it can't make any further progress because it has too many degrees of freedom. If you get this message, it usually means that the objective function is either not differentiable, or it may not have an optimum.
FALSE
this is what gets returned when the optimization algorithm can't make further progress. This usual cause of this is that the user has supplied a gradient, but the gradient is computed incorrectly.

The optimization also might stop if it exceeds a prescribed number of function evaluations, or a prescribed iteration limit.

REFERENCES:

Chambers, J. M., and Hastie, T. J. (eds) (1992). Statistical Models in S, Chapter 10, "Nonlinear Models". Pacific Grove, CA.: Wadsworth & Brooks/Cole.

SEE ALSO:

, , , , , .

EXAMPLES:

lprob <- function(lp)log(1+ exp(lp)) - lp  # log-likelihood 
fit.alpha <- ms(~ lprob(D * alpha), pingpong) 
lprob2 <- function(lp, X) { 
# lp is the linear predictor, X is data in the linear predictor 
          elp <- exp(lp) 
          z <- 1 + elp 
          value <- log(z) - lp 
          attr(value, "gradient") <- - X/z 
          value 
} 
fit.alpha.2 <- ms(~ lprob2(D * alpha, D), pingpong)