Package 'dr4pl' reference manual

Title:	Dose Response Data Analysis using the 4 Parameter Logistic (4pl) Model
Description:	Models the relationship between dose levels and responses in a pharmacological experiment using the 4 Parameter Logistic model. Traditional packages on dose-response modelling such as 'drc' and 'nplr' often draw errors due to convergence failure especially when data have outliers or non-logistic shapes. This package provides robust estimation methods that are less affected by outliers and other initialization methods that work well for data lacking logistic shapes. We provide the bounds on the parameters of the 4PL model that prevent parameter estimates from diverging or converging to zero and base their justification in a statistical principle. These methods are used as remedies to convergence failure problems. Gadagkar, S. R. and Call, G. B. (2015) <doi:10.1016/j.vascn.2014.08.006> Ritz, C. and Baty, F. and Streibig, J. C. and Gerhard, D. (2015) <doi:10.1371/journal.pone.0146021>.
Authors:	Justin T. Landis [aut, cre], Alice Peng [ctb], Hyowon An [aut], Aubrey G. Bailey [aut], Dirk P. Dittmer [aut], James S. Marron [aut]
Maintainer:	Justin T. Landis <[email protected]>
License:	GPL (>= 2)
Version:	2.0.0
Built:	2024-11-11 04:46:23 UTC
Source:	https://bitbucket.org/dittmerlab/dr4pl

Obtain coefficients of a 4PL model

Description

This function obtains the coefficients of a 4PL model. Estimates of the four parameters, the upper asymptote, IC50, slope and lower asymptote, are returned.

Usage

## S3 method for class 'dr4pl'
coef(object, ...)
## S3 method for class 'dr4pl'
coef(object, ...)

Arguments

`object`	A 'dr4pl' object
`...`	arguments passed to coef

Value

A vector of parameters

Examples

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_2)  # Fit a 4PL model to data
coef(obj.dr4pl)  # Print parameter estimates

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_3)  # Fit a 4PL model to data
coef(obj.dr4pl)  # Print parameter estimates

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_2)  # Fit a 4PL model to data
coef(obj.dr4pl)  # Print parameter estimates

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_3)  # Fit a 4PL model to data
coef(obj.dr4pl)  # Print parameter estimates

Fit a 4 parameter logistic (4PL) model to dose-response data.

Description

Compute the approximate confidence intervals of the parameters of a 4PL model based on the asymptotic normality of least squares estimators.

Usage

## S3 method for class 'dr4pl'
confint(object, parm = NULL, level = 0.95, ...)
## S3 method for class 'dr4pl'
confint(object, parm = NULL, level = 0.95, ...)

Arguments

`object`	An object of the dr4pl class
`parm`	parameters of the dr4pl object. Usually made with [dr4pl_theta]
`level`	Confidence level
`...`	Other parameters to be passed to vcov

Details

This function computes the approximate confidence intervals of the true parameters of a 4PL model based on the asymptotic normality of the least squares estimators in nonlinear regression. The Hessian matrix is used to obtain the second order approximation to the sum-of-squares loss function. Please refer to Subsection 5.2.2 of Seber and Wild (1989).

Value

A matrix of the confidence intervals in which each row represents a parameter and each column represents the lower and upper bounds of the confidence intervals of the corresponding parameters.

References

Seber GAF, Wild CJ (1989). Nonlinear regression, Wiley Series in Probability and Mathematical Statistics: Probability and Mathematical Statistics. John Wiley \& Sons, Inc., New York. ISBN 0-471-61760-1, doi:10.1002/0471725315, http://dx.doi.org.libproxy.lib.unc.edu/10.1002/0471725315.

Examples

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_1)  # Fit a 4PL model to data

## Use the data 'sample_data_1' to obtain confidence intervals.
confint(obj.dr4pl)  # 95% confidence intervals
confint(obj.dr4pl, level = 0.99)  # 99% confidence intervals

theta <- FindInitialParms(x = sample_data_1$Dose, y = sample_data_1$Response)

# Use the same data 'sample_data_1' but different parameter estimates to obtain
# confidence intervals.
confint(obj.dr4pl, parm = theta)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_1)  # Fit a 4PL model to data

## Use the data 'sample_data_1' to obtain confidence intervals.
confint(obj.dr4pl)  # 95% confidence intervals
confint(obj.dr4pl, level = 0.99)  # 99% confidence intervals

theta <- FindInitialParms(x = sample_data_1$Dose, y = sample_data_1$Response)

# Use the same data 'sample_data_1' but different parameter estimates to obtain
# confidence intervals.
confint(obj.dr4pl, parm = theta)

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 class '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 class '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,
  ...
)

## Default S3 method:
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,
  ...
)
dr4pl(...)

## S3 method for class '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 class '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,
  ...
)

## Default S3 method:
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

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.

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

Author(s)

Hyowon An, [email protected]

Justin T. Landis, [email protected]

Aubrey G. Bailey, [email protected]

Examples

  ##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()
##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()

Private function to fit the 4PL model to dose-response data

Description

Private function that actually fits the 4PL model to data. If the Hill bounds are attained at the end of optimization processes, then an indicator of convergence failure so that dr4pl.default can look for a remedy for convergence failure.

Usage

dr4plEst(
  dose,
  response,
  init.parm,
  trend,
  method.init,
  method.optim,
  method.robust,
  use.Hessian,
  level,
  upperl,
  lowerl,
  ...
)
dr4plEst(
  dose,
  response,
  init.parm,
  trend,
  method.init,
  method.optim,
  method.robust,
  use.Hessian,
  level,
  upperl,
  lowerl,
  ...
)

Arguments

`dose`	Vector of dose levels
`response`	Vector of responses
`init.parm`	Vector of initial parameters of the 4PL model supplied by a user.
`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. Should be one of "logistic" for the logistic method or "Mead" for the Mead method. The default option is the Mead method.
`method.optim`	Method of optimization of the parameters. This argument is directly delivered to the `constrOptim` function provided in the "base" package of R.
`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.
`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.
`upperl`	upper limit to init.parm
`lowerl`	lower limit to init.parm
`...`	Further arguments to be passed to `constrOptim`.

Value

List of final parameter estimates, name of robust estimation, loss value and so on.

Single High Outlier

Description

These are a handful of experimentally derived datasets from the wet-laboratory. These all have numerical errors in other dose-response curve-packages, but not using these methods. This data set exemplifies the case of a single extreme outlier of one dose measurement.

Examples

  a <- dr4pl(Response~Dose, data = drc_error_1, method.init = "logistic", method.robust = "Tukey")
  plot(a)
a <- dr4pl(Response~Dose, data = drc_error_1, method.init = "logistic", method.robust = "Tukey")
  plot(a)

Multiple High Outliers at Different measurements

Description

Examples

  a <- dr4pl(Response~Dose, data = drc_error_2, trend = "decreasing", method.optim = "CG")
  plot(a)
a <- dr4pl(Response~Dose, data = drc_error_2, trend = "decreasing", method.optim = "CG")
  plot(a)

Support Problem and Outliers at a Single Dose Level

Description

Examples

  a <- dr4pl(Response~Dose, data = drc_error_3, method.init = "Mead", method.robust = "Huber")
  plot(a)
a <- dr4pl(Response~Dose, data = drc_error_3, method.init = "Mead", method.robust = "Huber")
  plot(a)

Support Problem

Description

Examples

  a <- dr4pl(Response~Dose, data = drc_error_4, method.init = "logistic")
  plot(a)
a <- dr4pl(Response~Dose, data = drc_error_4, method.init = "logistic")
  plot(a)

FindHillBounds

Description

Compute the Hill bounds based on initial parameter estimates and data.

Usage

FindHillBounds(x, y, theta, use.Hessian = FALSE, level = 0.9999)
FindHillBounds(x, y, theta, use.Hessian = FALSE, level = 0.9999)

Arguments

`x`	Vector of doses.
`y`	Vector of responses.
`theta`	Parameters of a 4PL model.
`use.Hessian`	Indicator of whether the Hessian matrix (TRUE) or the gradient vector is used in confidence interval computation.
`level`	Confidence level to be used in computing the Hill bounds.

Details

This function computes the Hill bounds based on initial parameter estimates and data. It basically computes the confidence intervals of the true parameters based on the variance-covariance matrix of a given initial parameter estimates. The half of a hessian matrix is used as a variance-covariance matrix. If matrix inversion of the variance-covariance matrix is infeasible, a variation of the method in Wang et al. (2010) is used. The parameter level is only for simulation.

Value

Data frame whose first column represents the bounds on the IC50 parameter in log 10 scale and second column represents the bounds on the slope parameter.

Author(s)

Hyowon An, [email protected].

References

Higham NJ (2002). “Computing the nearest correlation matrix—a problem from finance.” IMA J. Numer. Anal., 22(3), 329–343. ISSN 0272-4979, doi:10.1093/imanum/22.3.329, http://dx.doi.org.libproxy.lib.unc.edu/10.1093/imanum/22.3.329. Wang Y, Jadhav A, Southal N, Huang R, Nguyen DT (2010). “A grid algorithm for high throughput fitting of dose-response curve data.” Curr Chem Genomics, 4, 57–66.

FindInitialParms

Description

Find initial parameter estimates for a 4PL model.

Usage

FindInitialParms(
  x,
  y,
  trend = "auto",
  method.init = "Mead",
  method.robust = "squared"
)
FindInitialParms(
  x,
  y,
  trend = "auto",
  method.init = "Mead",
  method.robust = "squared"
)

Arguments

`x`	Vector of dose levels
`y`	Vector of responses
`trend`	Indicator of whether the curve is a decreasing $\theta[3]<0$ or increasing curve $\theta[3]>0$ . See `dr4pl` for detailed explanation.
`method.init`	Method of obtaining initial values of the parameters. See `dr4pl` for detailed explanation.
`method.robust`	Parameter to select loss function for the robust estimation method to be used to fit a model. See `dr4pl` for detailed explanation.

Value

Initial parameter estimates of a 4PL model in the order of the upper asymptote, IC50, Slope and lower asymptote parameters.

FindLogisticGrids

Description

Compute the grids on the upper and lower asymptote parameters for the logistic method based on initial parameter estimates and data.

Usage

FindLogisticGrids(x, y, retheta.init, use.Hessian = FALSE)
FindLogisticGrids(x, y, retheta.init, use.Hessian = FALSE)

Arguments

`x`	Vector of doses.
`y`	Vector of responses.
`retheta.init`	Parameters of a 4PL model among which the EC50 parameter is in the log 10 dose scale.
`use.Hessian`	Indicator of whether the Hessian matrix (TRUE) or the gradient vector is used in confidence interval computation.

Details

This function computes the grids on the upper and lower asymptote parameters based on initial parameter estimates and data. It basically computes the confidence intervals of the true parameters based on the variance-covariance matrix of the given initial parameter estimates. If matrix inversion of the variance-covariance matrix is infeasible, a variation of the method in Wang et al. (2010) is used.

Value

Data frame whose first column represents the grid on the upper asymptote parameter and second column represents the grid o the lower asymptote.

Author(s)

Hyowon An

References

Wang Y, Jadhav A, Southal N, Huang R, Nguyen DT (2010). “A grid algorithm for high throughput fitting of dose-response curve data.” Curr Chem Genomics, 4, 57–66.

Obtain Inhibitory Concentrations (IC) of a dose-response curve

Description

This function obtains estimates of the IC's of a dose-response curve. Typically the IC50 parameter is of interest, but sometimes IC10 or IC90 are important aspects of a dose-response curve. By controlling the function argument, a user can obtain the IC's at various levels.

Usage

IC(object, inhib.percent)
IC(object, inhib.percent)

Arguments

`object`	Object of the class 'dr4pl' for which the IC values are obtained
`inhib.percent`	Inhibited percentages at which thc IC values are obtained

Value

IC values at the inhibited percentages provided by the argument inhib.percent

Examples

data.test <- data.frame(x = c(0.0001, 0.001, 0.01, 0.1, 1),
                        y = c(10, 9, 5, 1, 0))
obj.dr4pl <- dr4pl(y ~ x,
                   data = data.test)
IC(obj.dr4pl, inhib.percent = c(10, 90))

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_4)  # Fit a 4PL model to data
IC(obj.dr4pl, inhib.percent = c(10, 50, 90))

data.test <- data.frame(x = c(0.0001, 0.001, 0.01, 0.1, 1),
                        y = c(10, 9, 5, 1, 0))
obj.dr4pl <- dr4pl(y ~ x,
                   data = data.test)
IC(obj.dr4pl, inhib.percent = c(10, 90))

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_4)  # Fit a 4PL model to data
IC(obj.dr4pl, inhib.percent = c(10, 50, 90))

Compute an estimated mean response.

Description

Compute an estimated mean response.

Usage

MeanResponse(...)

## S3 method for class 'dr4pl'
MeanResponse(dr4pl, theta = NULL, ...)

## S3 method for class 'numeric'
MeanResponse(theta, x, ...)

## S3 method for class 'dr4pl_theta'
MeanResponse(theta, x, ...)

## S3 method for class 'dr4pl_log10'
MeanResponse(theta, x, ...)
MeanResponse(...)

## S3 method for class 'dr4pl'
MeanResponse(dr4pl, theta = NULL, ...)

## S3 method for class 'numeric'
MeanResponse(theta, x, ...)

## S3 method for class 'dr4pl_theta'
MeanResponse(theta, x, ...)

## S3 method for class 'dr4pl_log10'
MeanResponse(theta, x, ...)

Arguments

`...`	arguments to be passed to S3 methods
`dr4pl`	dr4pl object
`theta`	Parameters of the dr4pl object. Usually made with [dr4pl_theta]
`x`	domain values for 4PL model. Values should always be passed to this function on the linear space.

Value

Predicted response values.

Detect outliers by the method of Motulsky and Brown (2006).

Description

Detect outliers by the method of Motulsky and Brown (2006).

Usage

OutlierDetection(residuals)
OutlierDetection(residuals)

Arguments

residuals

Vector of residuals from a robust fit.

Details

This function detects outliers from a vector of residuals obtained from a robust fit. The method used here is the same with Motulsky and Brown (2006) except that the median absolute deviation is used instead of the sample quantile based estimator suggested in that paper. Based on the False Discovery Rate (FDR) a set of multiple outliers that have lower FDR's than a threshold are reported.

Value

Vector of indices of outliers in the input vector of residuals

Author(s)

Hyowon An

References

Motulsky HJ, Brown RE (2006). “Detecting outliers when fitting data with nonlinear regression - a new method based on robust nonlinear regression and the false discovery rate.” BMC Bioinformatics, 7, 123.

Make a plot of a 4PL model curve and data

Description

This function displays a dose-response curve and data. As a default, the x-axis represents dose levels in log 10 scale and the y-axis represents responses. The black solid line represents a dose-response curve. The blue filled circles represent data points and red triangles represent outliers.

Usage

## S3 method for class 'dr4pl'
plot(
  x,
  type.curve = "all",
  text.title = "Dose-response plot",
  text.x = "Dose",
  text.y = "Response",
  indices.outlier = NULL,
  breaks.x = NULL,
  breaks.y = NULL,
  ...
)
## S3 method for class 'dr4pl'
plot(
  x,
  type.curve = "all",
  text.title = "Dose-response plot",
  text.x = "Dose",
  text.y = "Response",
  indices.outlier = NULL,
  breaks.x = NULL,
  breaks.y = NULL,
  ...
)

Arguments

`x`	‘dr4pl’ object whose data and mean response function will be plotted.
`type.curve`	Indicator of the type of a dose-response curve. "all" indicates that data and a curve will be plotted while "data" indicates that only data will be plotted.
`text.title`	Character string for the title of a plot with a default set to "Dose response plot".
`text.x`	Character string for the x-axis of the plot with a default set to "Dose".
`text.y`	Character string for the y-axis of the plot with a default set to "Response".
`indices.outlier`	Pass a vector indicating all indices which are outliers in the data.
`breaks.x`	Vector of desired break points for the x-axis
`breaks.y`	Vector of desired break points for the y-axis
`...`	All arguments that can normally be passed to ggplot.

Author(s)

Hyowon An, [email protected]

Justin T. Landis, [email protected]

Aubrey G. Bailey, [email protected]

Examples

## Not run: 
dr4pl.1 <- dr4pl(Response ~ Dose, data = sample_data_1)

plot(dr4pl.1)

## Able to further edit plots.
library(ggplot2) #needed to change color to green
dr4pl.1 <- dr4pl(Response ~ Dose,
                        data = sample_data_1,
                        text.title = "Sample Data Plot")

a <- plot(dr4pl.1)
a + geom_point(color = "green", size = 5)

## Bring attention to outliers using parameter indices.outlier.
dr4pl.3 <- dr4pl(Response ~ Dose,
                 data = drc_error_3,
                 method.init = "Mead",
                 method.robust = "absolute")
plot(dr4pl.3, indices.outlier = c(90, 101))

## Change the plot title default with parameter text.title.
dr4pl.1 <- dr4pl::dr4pl(Response ~ Dose,
                        data = sample_data_1)
plot(dr4pl.1, text.title = "My New Dose Response plot")

##Change the labels of the x and y axis to your need
library(drc)  # Needed to load 'decontaminants' data set
data.hpc <- subset(decontaminants, group %in% "hpc")
dr4pl.hpc <- dr4pl(count~conc, data = data.hpc)
plot(dr4pl.hpc,
     text.title = "hpc Decontaminants Plot",
     text.x = "Concentration",
     text.y = "Count")

## End(Not run)

## Not run: 
dr4pl.1 <- dr4pl(Response ~ Dose, data = sample_data_1)

plot(dr4pl.1)

## Able to further edit plots.
library(ggplot2) #needed to change color to green
dr4pl.1 <- dr4pl(Response ~ Dose,
                        data = sample_data_1,
                        text.title = "Sample Data Plot")

a <- plot(dr4pl.1)
a + geom_point(color = "green", size = 5)

## Bring attention to outliers using parameter indices.outlier.
dr4pl.3 <- dr4pl(Response ~ Dose,
                 data = drc_error_3,
                 method.init = "Mead",
                 method.robust = "absolute")
plot(dr4pl.3, indices.outlier = c(90, 101))

## Change the plot title default with parameter text.title.
dr4pl.1 <- dr4pl::dr4pl(Response ~ Dose,
                        data = sample_data_1)
plot(dr4pl.1, text.title = "My New Dose Response plot")

##Change the labels of the x and y axis to your need
library(drc)  # Needed to load 'decontaminants' data set
data.hpc <- subset(decontaminants, group %in% "hpc")
dr4pl.hpc <- dr4pl(count~conc, data = data.hpc)
plot(dr4pl.hpc,
     text.title = "hpc Decontaminants Plot",
     text.x = "Concentration",
     text.y = "Count")

## End(Not run)

Print the dr4pl object to screen.

Description

Print the dr4pl object to screen.

Usage

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

Arguments

`x`	a dr4pl object to be printed
`...`	all normally printable arguments

Examples

ryegrass.dr4pl <- dr4pl(Response ~ Dose,
                        data = sample_data_1)
print(ryegrass.dr4pl)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_5)
print(obj.dr4pl)
ryegrass.dr4pl <- dr4pl(Response ~ Dose,
                        data = sample_data_1)
print(ryegrass.dr4pl)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_5)
print(obj.dr4pl)

Print the dr4pl object summary to screen.

Description

Print the dr4pl object summary to screen.

Usage

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

Arguments

`x`	a dr4pl object to be summarized
`...`	all normally printable arguments

Examples

library(drc)  # Needed for the data set 'ryegras'
dr4pl.ryegrass <- dr4pl(rootl ~ conc, data = ryegrass)
print(summary(dr4pl.ryegrass))

dr4pl.7 <- dr4pl(Response ~ Dose, data = sample_data_7)
print(summary(dr4pl.7))
library(drc)  # Needed for the data set 'ryegras'
dr4pl.ryegrass <- dr4pl(rootl ~ conc, data = ryegrass)
print(summary(dr4pl.ryegrass))

dr4pl.7 <- dr4pl(Response ~ Dose, data = sample_data_7)
print(summary(dr4pl.7))

sample_data_1

Description

These are a handful of experimentally derived datasets from the wet-laboratory. These may or may not have numerical errors in other dose-response curve-packages, but definitly not using these methods.

Examples

  a <- dr4pl(Response~Dose, data = sample_data_1)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_1)
  plot(a)

sample_data_10

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_10)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_10)
  plot(a)

sample_data_11

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_11)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_11)
  plot(a)

sample_data_12

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_12)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_12)
  plot(a)

sample_data_13

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_13)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_13)
  plot(a)

sample_data_2

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_2)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_2)
  plot(a)

sample_data_3

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_3)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_3)
  plot(a)

sample_data_4

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_4)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_4)
  plot(a)

sample_data_5

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_5)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_5)
  plot(a)

sample_data_6

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_6)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_6)
  plot(a)

sample_data_7

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_7)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_7)
  plot(a)

sample_data_8

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_8)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_8)
  plot(a)

sample_data_9

Description

Examples

  a <- dr4pl(Response~Dose, data = sample_data_9)
  plot(a)
a <- dr4pl(Response~Dose, data = sample_data_9)
  plot(a)

summary

Description

Print the summary of a dr4pl object.

Usage

## S3 method for class 'dr4pl'
summary(object, parm = NULL, ...)
## S3 method for class 'dr4pl'
summary(object, parm = NULL, ...)

Arguments

`object`	a dr4pl object to be summarized
`parm`	parameters of the dr4pl object. Usually made with [dr4pl_theta]
`...`	additional arguments to be passed to [calculate.dr4pl]

Examples

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_5)  # Fit a 4PL model to data
summary(obj.dr4pl)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_6)  # Fit a 4PL model to data
summary(obj.dr4pl)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_5)  # Fit a 4PL model to data
summary(obj.dr4pl)

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_6)  # Fit a 4PL model to data
summary(obj.dr4pl)

Obtain the variance-covariance matrix of the parameter estimators of a 4PL model.

Description

This function obtains the variance-covariance matrix of the parameter estimators of a 4PL model. The variance-covariance matrix returned by this function can be used to compute the standard errors and confidence intervals for statistical inference.

Usage

## S3 method for class 'dr4pl'
vcov(object, parm = NULL, use.Hessian = T, ...)

## S3 method for class 'dr4pl_param'
vcov(object, dose, response, use.Hessian = T, ...)
## S3 method for class 'dr4pl'
vcov(object, parm = NULL, use.Hessian = T, ...)

## S3 method for class 'dr4pl_param'
vcov(object, dose, response, use.Hessian = T, ...)

Arguments

`object`	An object of the dr4pl class.
`parm`	parameters of the dr4pl object. Usually made with [dr4pl_theta]. The class of this object determines in which space the covariance is calculated for theta_2.
`use.Hessian`	logical, if set to TRUE, the default, then the Hessian matrix scaled by 1/2 is used as an approximation to C.hat. Otherwise the First order Jacobian is used instead.
`...`	dots for future extensions
`dose`	dose levels
`response`	response values

Details

This function obtains the variance-covariance matrix of the parameter estimators of a 4PL model. The Hessian matrix is used to obtain the second order approximation to the sum-of-squares loss function, and then the standard errors are computed as the square roots of the half of the Hessian matrix. Please refer to Subsection 5.2.2 of Seber and Wild (1989).

Value

The variance-covariance matrix of the parameter estimators of a 4PL model whose columns are in the order of the upper asymptote, IC50, slope and lower asymptote from left to right and whose rows are in the same order.

a covariance matrix. If the 'parm' argument is of the class 'dr4pl_log10', then the covariance of row/column 2 represents log10(theta_2). If theta is of 'dr4pl_theta', then the covariance of row/column 2 represents theta_2 in linear space.

References

Examples

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_1)  # Fit a 4PL model to data
vcov(obj.dr4pl)  # Variance-covariance matrix of the parameters

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_2)  # Fit a 4PL model to data
vcov(obj.dr4pl)  # Variance-covariance matrix of the parameters

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_1)  # Fit a 4PL model to data
vcov(obj.dr4pl)  # Variance-covariance matrix of the parameters

obj.dr4pl <- dr4pl(Response ~ Dose, data = sample_data_2)  # Fit a 4PL model to data
vcov(obj.dr4pl)  # Variance-covariance matrix of the parameters

Package 'dr4pl'

Help Index

Obtain coefficients of a 4PL model

Description

Usage

Arguments

Value

Examples

Fit a 4 parameter logistic (4PL) model to dose-response data.

Description

Usage

Arguments

Details

Value

References

Examples

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

Description

Usage

Arguments

Details

Value

Methods (by class)

Author(s)

See Also

Examples

Private function to fit the 4PL model to dose-response data

Description

Usage

Arguments

Value

Single High Outlier

Description

Examples

Multiple High Outliers at Different measurements

Description

Examples

Support Problem and Outliers at a Single Dose Level

Description

Examples

Support Problem

Description

Examples

FindHillBounds

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

FindInitialParms

Description

Usage

Arguments

Value

FindLogisticGrids

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Obtain Inhibitory Concentrations (IC) of a dose-response curve

Description

Usage

Arguments

Value

Examples

Compute an estimated mean response.

Description

Usage

Arguments

Value

Detect outliers by the method of Motulsky and Brown (2006).

Description

Usage