bmdHetVarMA: Benchmark dose estimation with heterogeneous variance based...

In DoseResponse/bmd: Benchmark dose estimation for dose-response data

Benchmark dose estimation with heterogeneous variance based on model averaging (MA)

Description

Estimation of benchmark doses and benchmark dose lower limit based on the hybrid method from a list of dose response model fits with the option to specify a heterogeneous variance structure, where the variance depends on the dose level and/or the fitted values

Usage

bmdHetVarMA(modelList, modelWeights = c("AIC", "BIC"), bmr, 
            backgType = c("absolute", "hybridSD", "hybridPercentile"), 
            backg = NA, def = c("hybridExc", "hybridAdd"), interval = c("boot", "none"), 
            R = 1000, level = 0.95, progressInfo = TRUE,display = TRUE)

Arguments

modelList	a list of dose-response models with a heterogeneous variance structure of class drcHetVar
modelWeights	character string specifying the type of weights used, "AIC" or "BIC", or a numeric vector of the same length as the modelList with user defined weights
bmr	numeric value of benchmark response level for which to calculate the benchmark dose
backgType	character string specifying how the background level is specified. The options are "absolute", "hybridSD" and "hybridPercentile". "absolute" - the background level is specified by the user through the backg argument: p0 = 1 - phi((back - f(0))/sigma(0)) for "hybridExc" and "hybridAdd" definitions. "hybridSD" - the background risk is specified by the user in terms of number of SDs from the mean of the control group. p0 = 1 - phi(((backg*sigma(0) + f(0)) - f(0))/sigma(0)) = 1 - phi(backg), where phi is the normal distribution function and sigma(0) is the SD for the control group. "hybridPercentile" - the background risk is specified by the user in terms of percentile from the control group distribution (assuming a normal distribution). p0 = 1 - phi((x0 - f(0))/sigma(0)) = 1 - backg. where x0 is the level for which the response is considered adverse, phi is the normal distribution function and sigma(0) is the SD for the control group
backg	numeric value specifying the background level. Defaults to 2 SD for "hybridSD" background and 0.9 for "hybridPercentile"
def	character string specifying the definition of the benchmark dose to use in the calculations. "hybridExc" (excess hybrid), "hybridAdd" (additional hybrid), available. "hybridExc" - BMR is defined as: BMR = (1 - phi((x0 - f(BMD))/sigma(BMD)) - p0)/ (1- p0), where x0 is the level for which the response is considered adverse, phi is the normal distribution function and sigma(BMD) is the SD at the benchmark dose. "hybridAdd" - BMR is defined as: BMR = 1 - phi((x0 - f(BMD))/sigma(BMD)) - p0, where x0 is the level for which the response is considered adverse, phi is the normal distribution function and sigma(BMD) is the SD at the benchmark dose.
interval	character string specifying the type of confidence interval to use: "boot" (default) or "none" "boot" - BMDL is based on nonparametric percentile bootstrapping. "none" - no confidence interval is computed.
R	number of bootstrap samples. Ignored if interval = "none"
level	numeric value specifying the levle of the confidence interval underlying BMDL. Default is 0.95
progressInfo	logical. If TRUE, progress info is be printed while bootstrap confidence intervals are estimated. Default is TRUE.
display	logical. If TRUE the results are displayed; otherwise they are not

Details

The aim to provide an R package calculating the benchmark dose (BMD) and the lower limit of the corresponding 95% confidence interval (BMDL) for continuous and quantal dose-response data for a range of dose-response models based on the available definitions of the benchmark dose concepts.

REFERENCES TO BE ADDED/WRITTEN

Value

A list of four elements: Results contain the estimated BMD and BMDL, Boot.samples.used gives the number of boot samples that resulted in succesful estimations and were accordingly used in the estimation of BMDL (and BMDU), Interval gives BMDL and BMDU, which is identical to the confidence interval for the percentile interval approach, and modelWeights includes the estimated weights.

Author(s)

Signe M. Jensen and Jens Riis Baalkilde

Examples

library(drc)
library(drcData)
library(bmd)
# install.packages("gridExtra") # OPTIONAL - USED FOR PLOTTING A drcHetVar OBJECT.

# ryegrass data
set.seed(123)
ryegrass.hetVar.list <- list(
  drmHetVar(rootl ~ conc, ~ fitted + I(fitted^2), data = ryegrass, fct = LL.4()),
  drmHetVar(rootl ~ conc, ~ fitted + I(fitted^2), data = ryegrass, fct = LN.4()),
  drmHetVar(rootl ~ conc, ~ fitted + I(fitted^2), data = ryegrass, fct = W1.4()),
  drmHetVar(rootl ~ conc, ~ fitted + I(fitted^2), data = ryegrass, fct = W2.4()))
bmdHetVarMA(ryegrass.hetVar.list, modelWeights = "AIC", bmr = 0.1, backgType = "hybridPercentile",
            backg = 0.1, def = "hybridExc", R = 100, level = 0.95)
bmdHetVarMA(ryegrass.hetVar.list, modelWeights = c(0.4, 0.2, 0.1, 0.3), bmr = 0.1, 
            backgType = "hybridPercentile", backg = 0.1, 
            def = "hybridExc", R = 50, level = 0.95) # user-defined weights

# barley data
set.seed(123)
barley.hetVar.list <- list(drmHetVar(weight ~ Dose, ~ fitted + I(fitted^2), 
                                     data = barley, fct = LL.4()),
                           drmHetVar(weight ~ Dose, ~ fitted + I(fitted^2), 
                                     data = barley, fct = W2.4()))
bmdHetVarMA(barley.hetVar.list, modelWeights = "AIC", bmr = 0.1, backgType = "hybridSD", backg = 2,
            def = "hybridExc", R = 50, level = 0.95, progressInfo = TRUE, display = TRUE)

# GiantKelp data
set.seed(123)
GiantKelp.hetVar.list <- list(
  drmHetVar(tubeLength ~ dose, ~ fitted + I(fitted^2), data = GiantKelp, fct = LL.4()),
  drmHetVar(tubeLength ~ dose, ~ log(dose+1) + I(log(dose+1)^2), data = GiantKelp, fct = LL.4()))
bmdHetVarMA(GiantKelp.hetVar.list, modelWeights = "AIC", bmr = 0.1, backgType = "hybridSD",
            backg = 1, def = "hybridExc", R = 50, level = 0.95, progressInfo = TRUE, 
            display = TRUE)

DoseResponse/bmd documentation built on July 4, 2025, 11:20 p.m.