FSA (version 0.8.11)

nlsTracePlot: Adds model fits from nls iterations to active plot.

Description

Adds model fits from iterations of the nls algorithm as returned when trace=TRUE. Useful for diagnosing model fitting problems or issues associated with starting values.

Usage

nlsTracePlot(object, fun, from = NULL, to = NULL, n = 199, lwd = 2, pal = paletteChoices(), rev.col = FALSE, legend = "topright", cex.leg = 0.9, box.lty.leg = 0, add = TRUE)

Arguments

object

An object saved from nls or from capture.output using try with nls. See details.

fun

A function that represents the model being fit in nls. This must take the x-axis variable as the first argument and model parameters as a vector in the second argument. See details.

from, to

The range over which the function will be plotted. Defaults to range of the x-axis of the active plot.

n

The number of value at which to evaluate the function for plotting (i.e., the number of values from from to to). Larger values make smoother lines.

lwd

A numeric used to indicate the line width of the fitted line.

pal

A character that is the name of a palette. Must be one of “rich”, “cm”, “default”, “grey”, “gray”, “heat”, “jet”, “rainbow”, “topo”, or “terrain”, which are given in paletteChoices.

rev.col

A logical that indicates that the order of colors for plotting the lines should be reversed.

legend

Controls use and placement of the legend. See details.

cex.leg

A single numeric value that represents the character expansion value for the legend. Ignored if legend=FALSE.

box.lty.leg

A single numeric values that indicates the type of line to use for the box around the legend. The default is to not plot a box.

add

A logical indicating whether the lines should be added to the existing plot (defaults to =TRUE).

Value

A matrix with the residual sum-of-squares in the first column and parameter estimates in the remaining columns for each iteration (rows) of nls as provided when trace=TRUE.

Details

Nonlinear models fit through the nls function start with starting values for model parameters and iteratively search for other model parameters that continuously reduced the residual sum-of-squares (RSS) until some pre-determined criterion suggest that the RSS cannot be (substantially) further reduced. With good starting values and well-behaved data the minimum RSS may be found in a few (<10) iterations.="" however,="" poor="" starting="" values="" may="" lead="" to="" a="" prolonged="" search.="" or="" pooly="" behaved="" data="" failed="" an="" understanding="" of="" iterations="" in="" search="" why="" this="" happened="" choices="" that="" more="" successful="" the="" trace=TRUE argument of nls allows one to see the values at each iterative step. This function takes the “trace” results to plot the function at each step on a previously existing plot, thus providing a visual of the iterative process.

The object argument may an object saved from a successful run of nls. See the SpotVA1 and CodNorwegion examples.

However, if nls fails to converge to a solution then the nls does not return a useful object to be given to this function. In this case, trace=TRUE should be added to the failed nls call, which should then be wrapped in try to work-around the error returned from nls not converging to a solution and then in to capture the “trace” results. The result from capture.output should in turn be saved to an object that is then given to object of this function. See the BSkateGB example.

The function in fun is used to make predictions given the model parameter values at each step of the iteration. This function must accept the explanatory/independent variable as its first argument and values for all model parameters in a vector as its second argument. These types of functions are returned by vbFuns, GompertzFuns, logisticFuns, and RichardsFuns for common growth models and srFuns for common strock-recruitment models. See examples.

Examples

## Examples following a successful fit
data(SpotVA1)
vb1 <- vbFuns()
fit1 <- nls(tl~vb1(age,Linf,K,t0),data=SpotVA1,start=list(Linf=12,K=0.3,t0=0))
plot(tl~age,data=SpotVA1,pch=21,bg="gray40")
nlsTracePlot(fit1,vb1,legend="bottomright")

data(CodNorwegian)
r1 <- srFuns("Ricker")
fitSR1 <- nls(log(recruits)~log(r1(stock,a,b)),data=CodNorwegian,start=list(a=3,b=0.03))
plot(recruits~stock,data=CodNorwegian,pch=21,bg="gray40",xlim=c(0,200))
nlsTracePlot(fitSR1,r1)

# no plot, but returns trace results as a matrix
( tmp <- nlsTracePlot(fitSR1,r1,add=FALSE) )

## Not run: 
# if (require(FSAdata)) {
#   data(BSkateGB)
#   wtr <- filterD(BSkateGB,season=="winter")
#   bh1 <- srFuns()
#   trc <- capture.output(try(
#   fitSR1 <- nls(recruits~bh1(spawners,a,b),wtr,
#                 start=srStarts(recruits~spawners,data=wtr),trace=TRUE)
#   ))
#   plot(recruits~spawners,data=wtr,pch=21,bg="gray40")
#   nlsTracePlot(trc,bh1)
#   # zoom in on y-axis
#   plot(recruits~spawners,data=wtr,pch=21,bg="gray40",ylim=c(0.02,0.07))
#   nlsTracePlot(trc,bh1,legend="top")
#   # return just the trace results
#   ( tmp <- nlsTracePlot(trc,bh1,add=FALSE) )
# }
# ## End(Not run)