frair_boot_methods: frair methods
In dpritchard/frair: Tools for Functional Response Analysis

Description Usage Arguments Details Value Author(s) See Also Examples

Documentation for methods for class frboot

## S3 method for class 'frboot'
print(x, ...)
## S3 method for class 'frboot'
confint(object, parm='all', level=0.95, ..., citypes='all')
## S3 method for class 'frboot'
plot(x, xlab=x$xvar, ylab=x$yvar, ...)
## S3 method for class 'frboot'
lines(x, all_lines=FALSE, tozero=FALSE, bootcol=1, bootalpha=1/sqrt(x$n_boot), ...)
## S3 method for class 'frboot'
drawpoly(x, ..., probs=c(0.025, 0.975), tozero=FALSE)

## S3 method for class 'frconf'
print(x, ...)

`x, object`	Output from a call to `frair_boot` (or `confint.frboot`).
`parm`	A character vector. Which parameter to get CIs for? See Details.
`level`	A numeric. The confidence limit for CIs.
`citypes`	A character vector. What kind of CI? See Details.
`all_lines`	A logical. Should the bootstrapped results be plotted? See Details.
`tozero`	A logical. Should the line be drawn to the origin? See Details.
`xlab`	Label for the x-axis.
`ylab`	Label for the y-axis.
`bootcol`	A valid colour for the bootstrapped lines.
`bootalpha`	A numeric (0-1). A transparency for the (inevitably overlapping) lines.
`probs`	Lower and upper tails for confidence interval polygons. See `quantile`.
`...`	Other items passed to underlying functions.

This documents standard methods for FRAIR objects of class frboot. However, because standard naming conventions have been used, some undocumented utility functions might also work (e.g. coefficients)

The code underlying confint.frboot is quite complex and relies heavily on the excellent work done by Brian Ripley in boot.ci. Some of the complexity of boot.ci is hidden, but, like all FRAIR objects you can access the original method by passing the output directly (e.g. boot.ci(object$fit)).

Like print.bootci the print() method for objects produced by print.frboot will report potentially unstable intervals. However, these are calculated and returned by confint.frboot, not when print() is called (see Value, below). When calling confint.frboot you can request (a combination of) different intervals. The default 'all' is equivalent to c('norm', 'basic', 'stud', 'perc', 'bca') which are the Normal approximation, Basic, Studentised, Percentile and BCa intervals, respectively. Each has strengths and weaknesses which the user should be aware of.

lines and drawpoly only add lines or polygons to an existing plot, so an active graphics device needs to be present. By default all is FALSE. The simple reason for this is because the code is a little slow (on some devices), so currently it is an 'opt-in' option.

drawpoly draws empirical confidence intervals. The intervals are constructed by evaluating every set of bootstrapped coefficients at:

seq(from=min(x$x), to=max(x$x), length.out = 50).

and then calculating the empirical confidence limits at each value of x by:

apply(val, 2, quantile, na.rm=T, probs=probs)

Note that this is a rough approximation of a bootstrapped confidence interval and does not account for some of the intricacies (e.g. bootstrap bias) described in boot.ci.

Note also, that if tozero is TRUE, then both lines and drawpoly attempt to draw to zero by evaluating every set of bootstrapped coefficients at:

seq(from=0, to=max(x$x), length.out = 50)

If the coefficients provided by a fit to the orginal data produce a value that is undefined at zero, then these functions will plot lines to a small, non-zero number (1e-04) instead (with a warning). However, this does not guarantee that all of the values produced by the bootstrapped coefficients will produce sensible values. Clearly the intention here is to provide a nice-looking representation of the fitted curve and it is up to the user to determine why their desired curve is undefined at zero.

confint.frboot returns a nested list with m items at the top level and n items at the second level, where m is the number of coefficients and n is the number of types of confidence intervals. Each named object at the second level is a list containing:

`lower`	The upper limit.
`upper`	The lower limit.
`bootciout`	The output from `boot.ci` (if successful; NA otherwise).

and optionally:

`errors`	The error(s) encountered by `boot.ci`.
`warnings`	The warning(s) encountered by `boot.ci`, plus a warning if extreme values were used.
`notes`	A comment on potential instability of intervals, if justified.

These last two items combine 'true' warnings and the tests for interval stability described in print.bootci.

All confidence intervals are calculated on the original scale. If you want to calculate intervals on a transformed scale, call boot.ci directly using the boot.ci(object$fit) syntax.

Daniel Pritchard

frair_boot, lines, polygon.

# This example is not run to save CRAN build server time...
## Not run: 
data(gammarus)

# Holling's is the wrong fit for these data based on the experimental design
# But it runs more quickly, so is a useful demonstration
outhol <- frair_fit(eaten~density, data=gammarus, response='hollingsII', 
        start=list(a = 1, h = 0.08), fixed=list(T=40/24))
outholb <- frair_boot(outhol)

confint(outholb)

# Illustrate bootlines
plot(outholb, xlim=c(0,30), type='n', main='All bootstrapped lines')
lines(outholb, all_lines=TRUE)
points(outholb, pch=20, col=rgb(0,0,0,0.2))

# Illustrate bootpolys
plot(outholb, xlim=c(0,30), type='n', main='Empirical 95 percent CI')
drawpoly(outholb, col=rgb(0,0.5,0))
points(outholb, pch=20, col=rgb(0,0,0,0.2))

## End(Not run)