dr4pl (version 2.0.0)

dr4pl: Fitting 4 Parameter Logistic (4PL) models to dose-response data.

Description

This function fits a 4PL model to dose-response data. Users can obtain fitted parameter estimates as return values. Using auxiliary functions provided by this R package, users can plot a fitted dose-response curve and obtain confidence intervals of true parameters. In addition, the goodness-of-fit test for model adequacy of the 4PL models can be performed when replicates are available for each dose level.

Usage

dr4pl(...)
# S3 method for formula
dr4pl(
  formula,
  data = list(),
  init.parm = dr4pl_theta(),
  trend = "auto",
  method.init = "Mead",
  method.robust = "squared",
  method.optim = "Nelder-Mead",
  use.Hessian = FALSE,
  level = 0.9999,
  failure.message = FALSE,
  upperl = NULL,
  lowerl = NULL,
  ...
)
# S3 method for data.frame
dr4pl(
  data,
  dose,
  response,
  init.parm = dr4pl_theta(),
  trend = "auto",
  method.init = "Mead",
  method.robust = "squared",
  method.optim = "Nelder-Mead",
  use.Hessian = FALSE,
  level = 0.9999,
  failure.message = FALSE,
  upperl = NULL,
  lowerl = NULL,
  ...
)
# S3 method for default
dr4pl(
  dose,
  response,
  init.parm = dr4pl_theta(),
  trend = "auto",
  method.init = "Mead",
  method.robust = "squared",
  method.optim = "Nelder-Mead",
  use.Hessian = FALSE,
  level = 0.9999,
  failure.message = FALSE,
  upperl = NULL,
  lowerl = NULL,
  ...
)

Arguments

...

Further arguments to be passed to constrOptim.

formula

Symbolic description of the model to be fit. Either of the form 'response ~ dose' or as a data frame with response values in first column and dose values in second column.

data

Data frame containing variables in the model.

init.parm

Either a call to [dr4pl_theta], or a Vector of initial parameters to be optimized in the model.

• UpperLimit: \(\theta[1]\)

• IC50/EC50: \(\theta[2]\)

• Slope: \(\theta[3]\)

• LowerLimit: \(\theta[4]\)

dr4pl assumes \(\theta[1]>\theta[4]\). Note that when using upperl and lowerl, the user may need to set this parameter because the estimated parameters may not be within the feasible region.

trend

Indicator of whether a dose-response curve is a decreasing \(\theta[3]<0\) or increasing curve \(\theta[3]>0\). The default is "auto" which indicates that the trend of the curve is automatically determined by data. The option "decreasing" will impose a restriction \(\theta[3]<=0\) while the option "increasing" will impose a restriction \(\theta[3]>=0\) in an optimization process.

method.init

Method of obtaining initial values of the parameters. If this parameter is left unassigned, a default "Mead" method will be used. Assign "logistic" to use the logistic method.

method.robust

Parameter to select loss function for the robust estimation method to be used to fit a model. The argument NULL indicates the sum of squares loss, "absolute" indicates the absolute deviation loss, "Huber" indicates Huber's loss and "Tukey" indicates Tukey's biweight loss.

method.optim

Method of optimization of the loss function specified by method.robust. This function argument is directly passed to the function constrOptim which is provided in the base package of R.

use.Hessian

Indicator of whether the Hessian matrix (TRUE) or the gradient vector is used in the Hill bounds.

level

Confidence level to be used in Hill bounds computation.

failure.message

Indicator of whether a message indicating attainment of the Hill bounds and possible resolutions will be printed to the console (TRUE) or hidden (FALSE).

upperl

Either NULL or a numeric vector of length 4 that specifies the upper limit for the initial parameters of \(c(\theta[1],\theta[2],\theta[3],\theta[4])\) during the optimization process. By default no upperl is assumed. If the user wants to constain only some parameter values, set desired numeric bound in the appropriate position and fill Inf to impose no upper bounds on other values. All upperl values must be greater than corresponding initalized parameters.

lowerl

Either NULL or a numeric vector of length 4 that specifies the lower limit for the initial parameters of \(c(\theta[1],\theta[2],\theta[3],\theta[4])\) during the optimization process. By default no lowerl is assumed. If the user wants to constain only some parameter values, set desired numeric bound in the appropriate position and fill -Inf to impose no lower bounds on other values. All lowerl values must be greater than corresponding initalized parameters.

dose

Vector of dose levels

response

Vector of responses

Value

A 'dr4pl' object for which "confint", "gof", "print" and "summary" methods are implemented. For details, see the help page of each method. For example, type ?confint.dr4pl to obtain the confidence intervals of parameters of the 'dr4pl' object.

Methods (by class)

• formula: General 4PL model fitting function for analysis of dose-response relation.

• data.frame: Method for when formula argument is missing. dose and response arguments are necessary

• default: Used in the default case, supplying a single dose and response variable

Details

This function fits a 4 parameter logistic (4PL) model to dose-response data. A formula of the model is $$\theta[1]+(\theta[4]-\theta[1])/(1+(z/\theta[2])^\theta[3])$$

method.init specifies an initialization method to get initial parameter estimates based on data. The currently supported initialization methods are "logistic" and 'Mead'. For further details, see the vignette.

method.optim specifies an optimization method to be used in "constrOptim" function. The currently supported optimization techniques include "Nelder-Mead", "BFGS", "CG", "L-BFGS-B", "SANN" and "Brent". For further details, see the help page of optim.

method.robust chooses a robust estimation method among 4 methods. The method of estimation is usually identified by the loss function of the method. This package supports 4 types of loss functions: sum-of-squares loss, absolute deviation loss, Huber's loss and Tukey's biweight loss. Each of loss function is explained in detail in the vignette.

See Also

confint.dr4pl, gof.dr4pl, print.dr4pl, summary.dr4pl

Examples

# NOT RUN {
  ##Assign method.init = "logistic" to use logistic method of estimation.
  ##default method
  a <- dr4pl(dose = sample_data_1$Dose,
             response = sample_data_1$Response,
             method.init = "logistic")
  plot(a)

  ##Use default or Assign method.init = "Mead" to use Mead's method of estimation.
  # Use method.robust to select desired loss function
  # formula method
  b <- dr4pl(formula = Response~Dose,
             data = sample_data_4,
             method.init = "Mead",
             method.robust = "Tukey" )
  plot(b)

  #data.frame method
  c <- dr4pl(data = sample_data_10,
             dose = Dose,
             response = Response)
  plot(c)

  ##compatable with ggplot
  library(ggplot2) #load ggplot2
  c <- dr4pl(Response~Dose,
             data = drc_error_2,
             method.optim = "CG",
             trend = "decreasing" )
  d <- plot(c, x.breaks = c(.00135, .0135, .135, 1.35, 13.5))
  d + theme_grey()
# }