Package 'toxdrc'

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
IDcols	Character. Columns given as a vector used in the identification of data. These columns are preserved in the modified 'dataset' with the first non-blank value. These values should be identical within observations grouped by 'Conc'.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
blank_group	Character. Name of the 'Conc' level to calculate the correction value from.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
effect	Numeric. Dictates at the value beyond which observations are flagged as toxic. This value can be further customized; see see 'type' and 'direction'.
type	Character. Indicates if 'effect' is '"relative"' to 'reference group' or an '"absolute"' value. Defaults to relative.
direction	Character. Indicates if an effect occurs '"below"' or '"above"'. Defaults to below.
reference_group	Label used for reference group in 'Conc' column. Defaults to 0.
target_group	Optional. Limits the compairison to certain levels in 'Conc'.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	dataset A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
max_val	Numeric. The percent beyond which CV values are flagged. Defaults to 30.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe used to generate 'model'.
model	A drm model, generated by 'modelcomp()' or 'drm()'.
EDx	Numeric. The effective dose level to estimate. Defaults to 0.5.
interval	Character. Method for calculating confidence intervals of EDx. Choices: '"tfls"', '"fls"', '"delta"', '"none"'. Defaults to "tfls". See 'drc::ED()' for more information.
level	Numeric. Confidence level for the interval calculation. Defaults to 0.95.
type	Character. Indicates if EDx is '"absolute"' or '"relative"' to the curve. Defaults to absolute.
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.
EDargs.supplement	List. Optional user-supplied list of additional arguments compatible with 'drc::ED()'.
list_obj	Optional. List object used for integration with [runtoxdrc()].

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

dataset	A dataframe.
IDcols	Optional. Character. Columns given as a vector used in the identification of data. These columns are preserved in the modified 'dataset' with the first non-blank value. These values should be identical within observations grouped by 'Conc'.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
model_list	List. Model functions to be tested. Defaults to include '"LL.4"', '"LN.4"', '"W1.4"', '"W2.4"'. Most models from the drc package are compatible; use 'drc::getMeanFunctions()' for a more options. See details for formatting
metric	Character. Criterion used to select the best model. Choices are '"IC"', '"Res var"', '"Lack of fit"'. Defaults to "IC".
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
reference_group	Label used for the group values will be normalized to. Defaults to 0.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
reference_group	Label used for the true control level. Defaults to "Control".
positive_group	Label used for the positive control level. Defaults to 0.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
max_diff	Numeric. Percent difference of the response in the 'ref.label' and 'pctl.label' groups beyond which tests are flagged. Defaults to 10.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
list_obj	Optional. List object used for integration with [runtoxdrc()].
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.

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

dataset	A dataframe, containing the columns 'Conc' and 'Response'.
Conc	Bare (unquoted) column name in 'dataset' that groups the 'Response' variable.
Response	Bare (unquoted) column name in 'dataset' containing the response variable.
IDcols	Optional. Character. Columns given as a vector used in the identification of data. These columns are preserved in the modified 'dataset' with the first non-blank value. These values should be identical within observations grouped by 'Conc'.
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.
qc	Quality control and filtering options. See [toxdrc_qc()] for more detail and defaults.
normalization	Normalization options. See [toxdrc_normalization()] for more detail and defaults.
toxicity	Toxicity threshold and response-level options. See [toxdrc_toxicity()] for more detail and defaults.
modelling	Model selection, fitting criteria, and EDx calculation options. See [toxdrc_modelling()] for more detail and defaults.
output	Settings for output. See [toxdrc_output()] for more detail and defaults.

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

model.list	List. Model functions to be tested. Defaults to include '"LL.4"', '"LN.4"', '"W1.4"', '"W2.4"'. Most models from the drc package are compatible; use 'drc::getMeanFunctions()' for a more options. See [modelcomp()] for more information around formatting.
model.metric	Character. Criterion used to select the best model. Choices are '"IC"', '"Res var"', '"Lack of fit"'. Defaults to "IC".
EDx	Numeric. The effective dose level to estimate. Defaults to 0.5.
interval	Character. Method for calculating confidence intervals of EDx. Choices: '"tfls"', '"fls"', '"delta"', '"none"'. Defaults to "tfls". See 'drc::ED()' for more information.
level	Numeric. Confidence level for the interval calculation. Defaults to 0.95.
type	Character. Indicates if EDx is '"absolute"' or '"relative"' to the curve. Defaults to absolute.
quiet	Logical. Indicates if results should be hidden. Defaults to FALSE.
EDargs.supplement	List. Optional user-supplied list of additional arguments compatible with 'drc::ED()'.

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

blank.correction	Logical. Indicates if the response variable should be blank corrected. Defaults to FALSE.
blank.label	Character. Label used for the blank level. Defaults to "Blank".
normalize.resp	Logical. Indicates if response variable should be normalized to a given group. Defaults to FALSE.
relative.label	Label used for the group values will be normalized to. Defaults to 0.

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

condense	Logical. Indicates if the results should be summarized into a single dataframe. Defaults to TRUE.
sections	Character. Columns given as a vector that should be present in the summary. Defaults to 'c("ID", "effectmeasure", "best_model_name", "effect")'.

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

outlier.test	Logical. Indicates if outliers should be tested for and removed. Defaults to FALSE.
cv.flag	Logical. Indicates if groups of the response variable should be flagged if the CV exceeds 'cvflag.lvl'. Defaults to TRUE.
cvflag.lvl	Numeric. The percent beyond which CV values are flagged. Defaults to 30.
pctl.test	Logical. Indicates if positive control/solvent effects should be tested for. Defaults to FALSE.
pctl.lvl	Numeric. Percent difference of the response in the 'ref.label' and 'pctl.label' groups beyond which tests are flagged. Defaults to 10.
ref.label	Label used for the true control level. Defaults to "Control".
pctl.label	Label used for the positive control level. Defaults to 0.
avg.resp	Logical. Indicates if responses should be averaged within each group. Defaults to TRUE.

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

toxic.lvl	Numeric. Cutoff point to determine if modelling occurs. Defaults to 0.7.
toxic.type	Character. Indicates if 'effect' is '"relative"' to 'reference group' or an '"absolute"' value. Defaults to relative.
toxic.direction	Character. Indicates if an effect occurs '"below"' or '"above"'. Defaults to below.
comp.group	Label used for reference group.
target.group	Optional. Limits the compairison to certain exposure conditions.

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

---