toxdrc: Pipeline for Dose-Response Curve Analysis

Description

Provides a variety of tools for assessing dose response curves, with an emphasis on toxicity test data. The main feature of this package are modular functions which can be combined through the namesake pipeline, runtoxdrc, to automate the analysis for large and complex datasets. This includes optional data preprocessing steps, like outlier detection, solvent effects, blank correction, averaging technical replicates, and much more. Additionally, this pipeline is adaptable to any long form dataset, and does not require specific column or group naming to work.

Author(s)

Maintainer: Jack Salole salolej@mcmaster.ca

See Also

Useful links:

• https://github.com/jsalole/toxdrc

• Report bugs at https://github.com/jsalole/toxdrc/issues

Average response variable

Description

'averageresponse()' averages a given response variable by the experimental group, such as concentration or exposure length.

Usage

averageresponse(
  dataset,
  Conc,
  Response,
  IDcols = NULL,
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Value

A collapsed 'dataset' with one row for each level of 'Conc'. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with an unmodified copy as 'list_obj$pre_average_dataset'.

Examples

averageresponse(
     dataset = toxresult,
     Conc = Conc,
     Response = RFU,
     IDcols = c("TestID", "Test_Number", "Dye", "Type", "Replicate"),
   )

Blank correct response variable

Description

'blankcorrect()' subtracts a calculated correction value from all responses.

Usage

blankcorrect(
  dataset,
  Conc,
  blank_group = "Blank",
  Response,
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Value

A modified 'dataset' with an additional column, 'c_response'. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with statistics of the correction value as 'list_obj$blank_stats'.

Examples

blankcorrect(
     dataset = toxresult,
     Conc = Conc,
     blank_group = "Blank",
     Response = RFU
   )

Example toxicity test data with multiple experimental groups.

Description

A subset of data from a study using the RTgill-W1 assay (ISO 21115/OECD 249). Briefly, cells are exposed to a toxicant and the fluorescent signal is measured using 3 indicators.

Usage

cellglow

Format

## 'cellglow' A data frame with 1,080 rows and 7 columns:

TestID

Combination of Test_Number, Dye, Type, and Replicate

Test_Number

Identifying number of each effluent sample

Conc

Concentration of reference toxicant (3,4 dichloranaline). 0 is solvent control, "control" is a lab control

RFU

Fluoresence produced as determined by a plate reader

Dye

Three cell viability indicators; aB = alamarBlue, CFDA = 5-CFDA-AM, NR = Neutral Red

Type

Only spiked exists in this dataset; indicates a reference toxicant was added to the effluent.

Replicate

The experimental replicate; replication occured at a well-plate level.

/item ...

Details

Data collected as part of a study. Full dataset is available within a data repository: Salole, Jack; Wilson, Joanna; Taylor, Lisa, 2025, "RTgill-W1 Assay - Optimization and Effluent Testing", https://doi.org/10.5683/SP3/ES7GDM, Borealis, V2.

Source

https://doi.org/10.5683/SP3/ES7GDM

Check for an effect

Description

'checktoxicity()' flags if the response variable exceeds a limit in either direction as evidence of an effect.

Usage

checktoxicity(
  dataset,
  Conc,
  Response,
  effect,
  type = c("relative", "absolute"),
  direction = c("below", "above"),
  reference_group = "0",
  target_group = NULL,
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Value

TRUE if the response variable exceeds a limit in either direction and FALSE otherwise. If 'list_obj' is provided, returns this within a list as 'list_obj$effect'.

Examples

checktoxicity(
 dataset = toxresult,
 Conc = Conc,
 Response = RFU,
 effect = 0.5
)

Configuration functions for the runtoxdrc pipeline

Description

An overview of the modular configuration functions used by [runtoxdrc()]. These configuration functions provide default lists of parameters for customizing different stages of the pipeline to reduce the number of arguments required in [runtoxdrc()]. Each function returns a named list of configuration parameters suitable for passing directly to [runtoxdrc()].

Details

**Available configuration functions:**

• [toxdrc_qc()] — Quality control and filtering options

• [toxdrc_normalization()] — Blank correction and normalization

• [toxdrc_toxicity()] — Toxicity threshold and response-level options

• [toxdrc_modelling()] — Model selection, fitting criteria, and EDx calculation

• [toxdrc_output()] — Output settings

See Also

[runtoxdrc()], [toxdrc_qc()], [toxdrc_normalization()], [toxdrc_toxicity()], [toxdrc_modelling()], [toxdrc_output()]

Check for groups with high CV

Description

This function calculates the coefficient of variation (CV) of each of the exposure conditions, and flags them if they exceed a set value.

Usage

flagCV(dataset, Conc, Response, max_val = 30, list_obj = NULL, quiet = FALSE)

Arguments

Value

A modified 'dataset' with an additional column, 'CVflag'. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with a summary of the CV results as 'list_obj$CVresults'.

Examples

df <- data.frame(x = rep(1:2, each = 3), y = c(10, 11, 9, 20, 40, 60))
flagCV(dataset = df, Conc = x, Response = y, max_val = 30)

Get point estimates from model

Description

Generate point estimates from a dose response curve.

Usage

getECx(
  dataset,
  model,
  EDx = 0.5,
  interval = c("tfls", "fls", "delta", "none"),
  level = 0.95,
  type = c("absolute", "relative"),
  quiet = FALSE,
  EDargs.supplement = list(),
  list_obj = NULL
)

Arguments

Value

A dataframe of the point estimates. If 'list_obj' is provided, returns this within a list as 'list_obj$effectmeasure'.

Generate metadata from a dataframe

Description

Collects identifying or important values from an expeirmental replicate.

Usage

getmetadata(dataset, IDcols, list_obj = NULL, quiet = FALSE)

Arguments

Value

A 1 row dataframe of the identifying parameters of an experimental replicate. If 'list_obj' is provided, returns this within a list as 'list_obj$metadata'.

Compare model fits and select best model

Description

Data is fitted to provided models, typically from the drc package. Models fitted successfully are compared using multiple goodness-of-fit scores, and organized using the score given as the 'metric' argument. arguement.

Usage

modelcomp(
  dataset,
  Conc,
  Response,
  model_list = NULL,
  metric = c("IC", "Res var", "Lack of fit"),
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Details

The 'model_list' argument requires a specific style. The argument must be a list; entries in the list are in the format where the shorthand is the name of the model function. An example of this is '"LL.4" = LL.4()'.

Value

A fitted drm model. If 'list_obj' is provided, returns this within the list as 'list_obj$best_model', along with the model name ('list_obj$best_model_name'), and the model compairison dataframe ('list_obj$model_df'). If model fitting fails, returns NULL.

See Also

[drc::getMeanFunctions()] for compatabile models and their shorthand for 'model_list'.

Examples

toxresult2 <- toxresult[!toxresult$Conc %in% c ("Control", "Blank"),]
toxresult2$Conc <- as.numeric(toxresult2$Conc)
modelcomp(toxresult2, Conc, RFU, metric = "IC")

Normalize response variable

Description

Express a response variable relative to a reference group.

Usage

normalizeresponse(
  dataset,
  Conc,
  reference_group = "0",
  Response,
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Value

A modified 'dataset' with an additional column, 'normalized response'. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with summary statistics surrounding the reference group as 'list_obj$normalize_response_summary'.

Examples

normalizeresponse(
 dataset = toxresult,
 Conc = Conc,
 Response = RFU
)

Check for positive control effect

Description

This function evaluates the difference between a two groups to determine if the difference between them exceeds a set amount. Commonly used to determine if a solvent introduces effects.

Usage

pctl(
  dataset,
  Conc,
  reference_group = "Control",
  positive_group = 0,
  Response,
  max_diff = 10,
  list_obj = NULL,
  quiet = FALSE
)

Arguments

Value

A modified 'dataset' with an additional column, 'Validity'. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with statistics of the positive and reference group as 'list_obj$pctlresults'.

Examples

pctl(
 dataset = toxresult,
 Conc = Conc,
 Response = RFU,
 reference_group = "Control",
 positive_group = "0"
)

Remove outliers iteratively using Grubbs' test.

Description

This function removes statistical outliers from each testing group by iteratively applying Grubbs' test.

Usage

removeoutliers(dataset, Conc, Response, list_obj = NULL, quiet = FALSE)

Arguments

Value

A modified 'dataset' with outliers removed. If 'list_obj' is provided, returns this within a list as 'list_obj$dataset', along with dataframe of removed outliers as 'list_obj$removed_outliers'.

Examples

df <- data.frame(x = rep(1:2, each = 3),y = c(3, 5, 7, 3, 4, 30))
removeoutliers(dataset = df, Conc = x, Response = y)

Point estmation pipeline

Description

'runtoxdrc()' is the pipeline for function in the toxdrc package. This function allows the automated analysis of large datasets, while maintaining a consistent process for each suset of data.

Usage

runtoxdrc(
  dataset,
  Conc,
  Response,
  IDcols = NULL,
  quiet = FALSE,
  qc = toxdrc_qc(),
  normalization = toxdrc_normalization(),
  toxicity = toxdrc_toxicity(),
  modelling = toxdrc_modelling(),
  output = toxdrc_output()
)

Arguments

Value

By default, returns a list of lists with each subset of data having its own entry. Each subset contains dataframes, models, and other objects that track the pipeline process. If 'output = list(condense = TRUE)', the results are summarized into a single dataframe containing the 'IDcols' and model information of each data subset.

See Also

[config_runtoxdrc()] for configuration settings of the pipeline.

Examples

  analyzed_data <- runtoxdrc(
 dataset = cellglow,
 Conc = Conc,
 Response = RFU,
 IDcols = c("Test_Number", "Dye", "Replicate", "Type"),
 quiet = TRUE,
 normalization = toxdrc_normalization(
   blank.correction = TRUE,
   normalize.resp = TRUE
 ),
 modelling = toxdrc_modelling(EDx = c(0.2, 0.5, 0.7))
)

Modelling configuration for for the runtoxdrc pipeline.

Description

Defines how dose-response models are fitted, selected, and how point estimates (EDx) are calculated.

Usage

toxdrc_modelling(
  model.list = list(LL.4 = LL.4(), LN.4 = LN.4(), W1.4 = W1.4(), W2.4 = W2.4()),
  model.metric = c("IC", "Res var", "Lack of fit"),
  EDx = 0.5,
  interval = c("tfls", "fls", "delta", "none"),
  level = 0.95,
  type = c("relative", "absolute"),
  quiet = FALSE,
  EDargs.supplement = list()
)

Arguments

Value

A named list containing model fitting and selection settings for use in [runtoxdrc()].

See Also

[config_runtoxdrc], [runtoxdrc()], [drc::ED()], [getMeanFunctions()], [modelcomp()]

Examples

toxdrc_modelling(EDargs.supplement = list(interval = "delta", level = 0.9))

Set normalization configuration for the runtoxdrc pipeline.

Description

Control blank correction and normalization of the response variable.

Usage

toxdrc_normalization(
  blank.correction = FALSE,
  blank.label = "Blank",
  normalize.resp = FALSE,
  relative.label = 0
)

Arguments

Value

A named list containing normalization configuration for use in [runtoxdrc()].

See Also

[config_runtoxdrc], [runtoxdrc()], [blankcorrect()], [normalizeresponse()]

Examples

toxdrc_normalization(blank.correction = TRUE, relative.label = "Control")

#' Output configuration for for the runtoxdrc pipeline.

Description

Defines how [runtoxdrc()] output is returned.

Usage

toxdrc_output(
  condense = FALSE,
  sections = c("ID", "effectmeasure", "best_model_name", "effect")
)

Arguments

Value

A named list containing output configuration for use in [runtoxdrc()].

See Also

[config_runtoxdrc], [runtoxdrc()]

Examples

toxdrc_output()
toxdrc_output(condense = TRUE)

Set quality control options for the runtoxdrc pipeline.

Description

Control outlier detection, CV calculation, averaging of response variable, and testing for positive control effects.

Usage

toxdrc_qc(
  outlier.test = FALSE,
  cv.flag = TRUE,
  cvflag.lvl = 30,
  pctl.test = FALSE,
  pctl.lvl = 10,
  ref.label = "Control",
  pctl.label = 0,
  avg.resp = TRUE
)

Arguments

Value

A named list containing the quality control configuration for use in [runtoxdrc()].

See Also

[config_runtoxdrc], [runtoxdrc()], [pctl()], [removeoutliers()], [flagCV()]

Examples

toxdrc_qc(outlier.test = TRUE, cvflag.lvl = 20)

Toxicity configuration for for the runtoxdrc pipeline.

Description

Defines how toxicity is determined for model fitting.

Usage

toxdrc_toxicity(
  toxic.lvl = 0.7,
  toxic.type = c("relative", "absolute"),
  toxic.direction = c("below", "above"),
  comp.group = 0,
  target.group = NULL
)

Arguments

Value

A named list containing toxicity determination settings for use in [runtoxdrc()].

See Also

[config_runtoxdrc], [runtoxdrc()], [checktoxicity()]

Examples

toxdrc_toxicity(toxic.lvl = 0.5, toxic.direction = "above")

Example toxicity test data from a single experimental subset.

Description

A subset of data from a study using the RTgill-W1 assay (ISO 21115/OECD 249). Briefly, cells are exposed to a toxicant and the fluorescent signal is measured using 3 indicators.

Usage

toxresult

Format

## 'toxresult' A data frame with 1,080 rows and 7 columns:

TestID

Combination of Test_Number, Dye, Type, and Replicate

Test_Number

Identifying number of each effluent sample

Conc

Concentration of reference toxicant (3,4 dichloranaline). 0 is solvent control, "control" is a lab control

RFU

Fluoresence produced as determined by a plate reader

Dye

Three cell viability indicators; aB = alamarBlue, CFDA = 5-CFDA-AM, NR = Neutral Red

Type

Only spiked exists in this dataset; indicated a reference toxicant was added to the effluent.

Replicate

The experimental replicate; replication occured at a well-plate level.

/item ...

Details

Data collected as part of a study. Full dataset is available within a data repository: Salole, Jack; Wilson, Joanna; Taylor, Lisa, 2025, "RTgill-W1 Assay - Optimization and Effluent Testing", https://doi.org/10.5683/SP3/ES7GDM, Borealis, V2.

Source

https://doi.org/10.5683/SP3/ES7GDM