R: Fitting dose-response models

drm {drc} | R Documentation

## Fitting dose-response models

### Description

A general model fitting function for analysis of concentration/dose/time-effect/response data.

### Usage

      drm(formula, curveid, pmodels, weights, data = NULL, subset, fct,
      type = c("continuous", "binomial", "Poisson", "quantal", "event"),
      bcVal = NULL, bcAdd = 0,
      start, na.action = na.omit, robust = "mean", logDose = NULL,
      control = drmc(), lowerl = NULL, upperl = NULL, separate = FALSE, pshifts = NULL)

### Arguments

`formula` | a 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.
`curveid` | a numeric vector or factor containing the grouping of the data.
`pmodels` | a data frame with a many columns as there are parameters in the non-linear function. Or a list containing a formula for each parameter in the nonlinear function.
`weights` | a numeric vector containing weights. For continuous/quantitative responses weights are multiplied inside the squared errors (see the details below). For binomial reponses weights provide information about the total number of binary observations used to obtain the response (which is a proportion): 1/2 and 10/20 lead to different analyses due to the different totals (2 vs. 20) even though the proportion in both cases is 0.5.
`data` | an optional data frame containing the variables in the model.
`subset` | an optional vector specifying a subset of observations to be used in the fitting process.
`fct` | a list with three or more elements specifying the non-linear function, the accompanying self starter function, the names of the parameter in the non-linear function and, optionally, the first and second derivatives as well as information used for calculation of ED values. Currently available functions include, among others, the four- and five-parameter log-logistic models `LL.4`, `LL.5` and the Weibull model `W1.4`. Use `getMeanFunctions` for a full list.
`type` | a character string specifying the data type (parameter estimation will depend on the data type as different log likelihood function will be used).
`bcVal` | a numeric value specifying the lambda parameter to be used in the Box-Cox transformation.
`bcAdd` | a numeric value specifying the constant to be added on both sides prior to Box-Cox transformation. The default is 0.
`start` | an optional numeric vector containing starting values for all mean parameters in the model. Overrules any self starter function.
`na.action` | a function for treating mising values ('NA's). Default is `na.omit`.
`robust` | a character string specifying the rho function for robust estimation. Default is non-robust least squares estimation ("mean"). Available robust methods are: median estimation ("median"), least median of squares ("lms"), least trimmed squares ("lts"), metric trimming ("trimmed"), metric winsorizing ("winsor") and Tukey's biweight ("tukey").
`logDose` | a numeric value or NULL. If log doses value are provided the base of the logarithm should be specified (exp(1) for the natural logarithm and 10 for 10-logarithm).

`control` | a list of arguments controlling constrained optimisation (zero as boundary), maximum number of iteration in the optimisation, relative tolerance in the optimisation, warnings issued during the optimisation.
`lowerl` | a numeric vector of lower limits for all parameters in the model (the default corresponds to minus infinity for all parameters).
`upperl` | a numeric vector of upper limits for all parameters in the model (the default corresponds to plus infinity for all parameters).
`separate` | logical value indicating whether curves should be fit separately (independent of each other).
`pshifts` | a matrix of constants to be added to the matrix of parameters. Default is no shift for all parameters.

### Details

This function relies on the general optimiser function `optim` for the minimisation of negative log likelihood function. For a continuous response this reduces to least squares estimation, which is carried out by minimising the following sums of squares

∑_{i=1}^N [w_i (y_i-f_i)]^2

where y_i, f_i, and w_i correspond to the observed value, expected value, and the weight respectively, for the ith observation (from 1 to N).

The control arguments are specified using the function `drmc`.

Setting `lowerl` and/or `upperl` automatically invokes constrained optimisation.

The columns of a data frame argument to `pmodels` are automatically converted into factors. This does not happen if a list is specified.

### Value

An object of class 'drc'.

### Note

For robust estimation MAD (median abslolute deviance) is used to estimate the residual variance.

### Author(s)

Christian Ritz and Jens C. Streibig

### See Also

Examples using `drm` found in the help pages of `ryegrass` (continuous data), `secalonic` (continuous data), and `selenium` (binomial data), as well as for a number of other datasets and functions in `drc`.

[Package drc version 3.0-1 Index]