albertopessia / drda

Dose-response data analysis

drda

Overview

drda is an R package for fitting growth curves and performing dose-response data analysis.

The current available models are:

• 5-parameter logistic function
• 5-parameter log-logistic function
• 4-parameter logistic function
• 4-parameter log-logistic function
• 2-parameter logistic function
• 2-parameter log-logistic function
• Gompertz function
• log-Gompertz function

A 6-parameter (log-)logistic function is also available for theoretical research, but its use in real applications is discouraged because it is usually non-identifiable from data.

Installation

You can install the latest stable release of the drda R package from CRAN with

install.packages("drda")

To install the latest development version of the package from GitHub use

# install.packages("remotes")
remotes::install_github("albertopessia/drda")

Usage

Load the package

library(drda)

Example data

Package drda comes with our own example dataset:

?voropm2

head(voropm2)

Default fitting

# by default `drda` uses a 4-parameter logistic function for model fitting

# common R API for fitting models
fit <- drda(response ~ log_dose, data = voropm2)

# get a general overview of the results
summary(fit)

# get parameter estimates by using generic functions...
coef(fit)
sigma(fit)

# ... or accessing the variables directly
fit$coefficients
fit$sigma

# compare the estimated model against a flat horizontal line, or the full
# 5-parameter logistic model, using AIC, BIC, and the Likelihood Ratio Test
# (LRT)
#
# note that the LRT is testing the null hypothesis of a flat horizontal line
# being as a good fit as the chosen model, therefore we expect the test to be
# significant
#
# if the test is not significant, a horizontal line is probably a better model
anova(fit)

Other models

# use the `mean_function` argument to select a different model
fit_l2 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic2")
fit_l4 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic4")
fit_l5 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic5")
fit_gz <- drda(response ~ log_dose, data = voropm2, mean_function = "gompertz")

# which model should be chosen?
anova(fit_l2, fit_l4, fit_l5, fit_gz)

# 5-parameter logistic function provides the best fit (AIC and BIC are minimum)

Weighted fit

# it is possible to give each observation its own weight
fit_weighted <- drda(response ~ log_dose, data = voropm2, weights = weight)

# all the commands shown so far are available for a weighted fit as well

Constrained optimization

# it is possible to fix parameter values by setting the `lower_bound` and
# `upper_bound` appropriately
#
# unconstrained parameters have a lower bound of `-Inf` and an upper bound of
# `Inf`
#
# Important: be careful when deciding the constraints, because the optimization
#            problem might become very difficult to solve within a reasonable
#            number of iterations.
#
# In this particular example we are:
#   - fixing the alpha parameter to 1
#   - fixing the delta parameter to -1
#   - constraining the growth rate to be between 1 and 5
#   - not constraining the `phi` parameter, i.e. the `log(EC50)`
lb <- c(1, -1, 1, -Inf)
ub <- c(1, -1, 5,  Inf)

fit <- drda(
  response ~ log_dose, data = voropm2, lower_bound = lb, upper_bound = ub,
  max_iter = 260
)

summary(fit)

# if the algorithm does not converge, we can try to increase the maximum number
# of iterations or provide our own starting point
fit <- drda(
  response ~ log_dose, data = voropm2, lower_bound = lb, upper_bound = ub,
  start = c(1, -1, 2.6, 5), max_iter = 10000
)

summary(fit)

Basic plot functionality

fit_l5 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic5")

# plot the data used for fitting, the maximum likelihood curve, and
# *approximate* confidence intervals for the curve
plot(fit_l5)

# combine all curves in the same plot
fit_l2 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic2")
fit_l4 <- drda(response ~ log_dose, data = voropm2, mean_function = "logistic4")
plot(fit_l2, fit_l4, fit_l5)

# modify default plotting options
# use `legend_show = FALSE` to remove the legend altogether
plot(
  fit_l5, base = "10", col = "magenta", xlab = "x", ylab = "y", level = 0.9,
  midpoint = FALSE, main = "Example plot", legend_location = "topright",
  legend = "5-parameter logistic function"
)

License

This package is free and open source software licensed under MIT.

drda's Issues

Getting distorted curves when attempting to plot multiple curves in the same plot

Thanks @albertopessia for this user-friendly and well-documented package.

When I try to plot multiple dose-response curves in the same plot, the curves get distorted - due to change(s) in x or y axes. Consider the following example:

# Data
dose <- c( -4, -4.30, -4.60, -4.90, -5.20, -5.50, -5.80, -6.10, -6.40, -6.70, -7)
response <- c(3, 10, 24, 32, 45, 58, 71, 88, 92, 95, 99)

# Model 1
m1 <- drda(formula = response ~ dose, mean_function = "logistic4")

# Model 2
low_bound <- c(0, 100, -7, -Inf)
up_bound <- c(0, 100, -4, Inf)
m2 <- drda(formula = response ~ log_dose, upper_bound = up_bound, lower_bound = low_bound)

# Plot
plot(m1, m2) 

Defining axis limits appears to be the only working solution:

plot(m, m2, 
        xlim = c(-7, .4), 
        ylim = c(0, 100), 
        legend = c("Model_1", "Model_2")) 

Is there something obvious I am missing here or is this the expected behavior?

> sessionInfo()
R version 4.0.2 (2020-06-22)
Platform: x86_64-apple-darwin17.0 (64-bit)
Running under: macOS  10.16

Matrix products: default
LAPACK: /Library/Frameworks/R.framework/Versions/4.0/Resources/lib/libRlapack.dylib

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] pracma_2.3.3 drda_1.0.0  

loaded via a namespace (and not attached):
 [1] fansi_0.5.0      assertthat_0.2.1 dplyr_1.0.7      crayon_1.4.1     utf8_1.2.2      
 [6] grid_4.0.2       R6_2.5.1         DBI_1.1.1        lifecycle_1.0.1  gtable_0.3.0    
[11] magrittr_2.0.1   scales_1.1.1     pillar_1.6.4     ggplot2_3.3.5    rlang_0.4.11    
[16] generics_0.1.0   vctrs_0.3.8      ellipsis_0.3.2   tools_4.0.2      glue_1.4.2      
[21] purrr_0.3.4      munsell_0.5.0    tinytex_0.34     xfun_0.26        compiler_4.0.2  
[26] pkgconfig_2.0.3  colorspace_2.0-2 tidyselect_1.1.1 tibble_3.1.5  

[BUG]nauc() function

Hello

I am trying to use the nauc() function but get the following message

Error in if (tmp < xlim[2]) { : missing value where TRUE/FALSE needed
In addition: Warning message:
In log((ylim[2] - alpha)/(beta - ylim[2])) : NaNs produced.

[BUG] Error plotting: Error in seq.default(x1, x2, by = ceiling((x2 - x1)/6)) : invalid '(to - from)/by'

Describe the bug

Thanks for this package! I noticed the above bug. When the input data frame is not sorted by dose, the plot utility does not work under base != 'n'.

To Reproduce

library(tidyverse)
library(drda)
voropm2 <- voropm2 %>% arrange(desc(dose))
fit <- drda(response ~ dose, data = voropm2,mean_function='loglogistic5',max_iter = 10000)
plot(fit,base="10")

yields:

Error in seq.default(x1, x2, by = ceiling((x2 - x1)/6)) : 
  invalid '(to - from)/by'

Expected behavior

I expect the sorting of the data frame to not impact results/plots generated. Right now I can work around the issue by sorting dataframes passed to the package, but this should probably be documented and eventually corrected.

Desktop (please complete the following information):

• OS: macOS
• Platform: aarch64-apple-darwin20 (64-bit)
• R: 4.2.1
• drda version: [e.g. 2.0.1]

Get standard error from predict

thanks for this package. It’s working well for me…

But is there any way to get standard error from predictions on a drda fit object (eg, predict(fit, se.fit=T) ).