investr (version 1.2.0)

invest: Calibration for Linear and Nonlinear Regression Models.

Description

The function invest computes the inverse estimate and a condfidence interval for the unknown predictor value that corresponds to an observed value of the response (or vector thereof) or specified value of the mean response. See the references listed below for more details.

Usage

invest(object, ...)
## S3 method for class 'lm':
invest(object, y0, interval = c("inversion", "Wald", "none"),
  level = 0.95, mean.response = FALSE, data, boot = FALSE,
  type = c("parametric", "nonparametric"), nsim = 1, seed = NULL,
  progress = FALSE, lower, upper, tol = .Machine$double.eps^0.25,
  maxiter = 1000, adjust = c("none", "Bonferroni"), k, ...)
## S3 method for class 'nls':
invest(object, y0, interval = c("inversion", "Wald", "none"),
  level = 0.95, mean.response = FALSE, data, boot = FALSE,
  type = c("parametric", "nonparametric"), nsim = 1, seed = NULL,
  progress = FALSE, lower, upper, tol = .Machine$double.eps^0.25,
  maxiter = 1000, adjust = c("none", "Bonferroni"), k, ...)
## S3 method for class 'lme':
invest(object, y0, interval = c("inversion", "Wald", "none"),
  level = 0.95, mean.response = FALSE, data, lower, upper, q1, q2,
  tol = .Machine$double.eps^0.25, maxiter = 1000, ...)

Arguments

object

An object that inherits from class "lm", "nls", or "lme".

...

Additional optional arguments. At present, no optional arguments are used.

y0

The value of the observed response(s) or specified value of the mean response.

interval

The type of interval required.

level

A numeric scalar between 0 and 1 giving the confidence level for the interval to be calculated.

mean.response

Logical indicating whether confidence intervals should correspond to an individual response (FALSE) or a mean response (TRUE).

data

An optional data frame. This is required if object$data is NULL.

boot

Logical indicating whether to carry out a bootstrap simulation.

type

Character string specifying the type of bootstrap, "parametric" or "nonparametric".

nsim

Positive integer specifying the number of bootstrap simulations; the bootstrap B (or R).

seed

Optional argument to set.seed.

progress

Logical indicating whether to display a text-based progress bar during the bootstrap simulation.

lower

The lower endpoint of the interval to be searched.

upper

The upper endpoint of the interval to be searched.

tol

The desired accuracy passed on to uniroot. Recommend a minimum of 1e-10.

maxiter

The maximum number of iterations passed on to uniroot.

adjust

A logical value indicating if an adjustment should be made to the critical value used in calculating the confidence interval. This is useful for when the calibration curve is to be used multiple, say k, times.

k

The number times the calibration curve is to be used for computing a confidence interval. Only needed when adjust = "Bonferroni".

q1

Optional lower cutoff to be used in forming confidence intervals. Only used when object inherits from class "lme". Defaults to qnorm((1+level)/2).

q2

Optional upper cutoff to be used in forming confidence intervals. Only used when object inherits from class "lme". Defaults to qnorm((1-level)/2).

Value

• If boot = FALSE, then an object of class "calibrate" containing the following components:
  • estimateThe estimate of x0.
  • lwrThe lower confidence limit for x0.
  • uprThe upper confidence limit for x0.
  • seAn estimate of the standard error (Wald interval only).
  • intervalThe method used for calculatinglowerandupper(only used byprintmethod).
  Otherwise, an object of class "bootCal" containing the following components:
  • originalThe estimate of x0.
  • bootrepsThe lower confidence limit for x0.
  • nsimThe number of bootstrap replicates.
  • levelThe desired confidence level.

References

Greenwell, B. M., and Schubert Kabban, C. M. (2014). investr: An R Package for Inverse Estimation. The R Journal, 6(1), 90--100. URL http://journal.r-project.org/archive/2014-1/greenwell-kabban.pdf.

Graybill, F. A., and Iyer, H. K. (1994). Regression analysis: Concepts and Applications. Duxbury Press.

Huet, S., Bouvier, A., Poursat, M-A., and Jolivet, E. (2004) Statistical Tools for Nonlinear Regression: A Practical Guide with S-PLUS and R Examples. Springer.

Seber, G. A. F., and Wild, C. J. (1989) Nonlinear regression. Wiley.

Oman, Samuel D. (1998). Calibration with Random Slopes. Biometrics 85(2): 439--449. doi:10.1093/biomet/85.2.439.

Examples

##
## Nasturtium example (nonlinear regression with replication)
##

## Log-logistic model
mod <- nls(weight ~ theta1/(1 + exp(theta2 + theta3 * log(conc))),
           start = list(theta1 = 1000, theta2 = -1, theta3 = 1),
           data = nasturtium)

## Compute approximate 95\% calibration intervals
invest(mod, y0 = c(309, 296, 419), interval = "inversion")
invest(mod, y0 = c(309, 296, 419), interval = "Wald")

## Bootstrap calibration intervals
#boo <- invest(mod, y0 = c(309, 296, 419), boot = TRUE, nsim = 9999,
#              progress = TRUE, seed = 101)
#boo  # print bootstrap summary
#plot(boo)  # plot results