MOdelling tools for Reproduction and Survival data in Ecotoxicology

Description

Provides tools for the analysis of survival/reproduction toxicity test data in quantitative environmental risk assessment. It can be used to explore/visualize experimental data, and to get estimates of LC_{x} (X% Lethal Concentration) or, EC_{x} (X% Effective Concentration) by fitting exposure-response curves. The LC_{x}, EC_{x} and parameters of the curve are provided along with an indication of the uncertainty of the estimation. morse can also be used to get an estimation of the NEC (No Effect Concentration) by fitting a Toxico-Kinetic Toxico-Dynamic (TKTD) model (GUTS: General Unified Threshold model of Survival). Within the TKTD-GUTS approach, LC(x,t), EC(x,t) and MF(x,t) (x% Multiplication Factors aka Lethal Profiles) can be explored in proportion x and time t.

Details

Estimation procedures in morse can be used without a deep knowledge of their underlying probabilistic model or inference methods. Rather, they were designed to behave as well as possible without requiring a user to provide values for some obscure parameters. That said, morse models can also be used as a first step to tailor new models for more specific situations.

The package currently handles survival and reproduction data. Functions dedicated to survival (resp. reproduction) analysis start with a surv (resp. repro) prefix. morse provides a similar workflow in both cases:

1. create and validate a data set

2. explore a data set

3. plot a data set

4. fit a model on a data set and output the expected estimates

5. check goodness of fit with posterior preditive check plot (ppc)

More specifically, for survival data handles with TKTD 'GUTS' model, morse provides:

1. plot LC(x,t) and MF(x,t).

2. compute goodness-of-fit measures (PPC percent, NRMSE and SPPE)

Those steps are presented in more details in the "Tutorial" vignette, while a more formal description of the estimation procedures are provided in the vignette called "Models in morse package". Please refer to these documents for further introduction to the use of morse.

This reference manual is a detailed description of the functions exposed in the package.

Getting started The package uses the rjags package (Plummer, 2013), an R interface to the JAGS library for Bayesian model estimation. Note that the rjags package does not include a copy of the JAGS library: you need to install it separately. For instructions on downloading JAGS, see the home page at https://mcmc-jags.sourceforge.io. Once done, simply follow the steps described in the tutorial vignette.

Author(s)

Virgile Baudrot <virgile.baudrot@posteo.net>, Sandrine Charles <sandrine.charles@univ-lyon1.fr>, Marie Laure Delignette-Muller <marielaure.delignettemuller@vetagro-sup.fr>, Wandrille Duchemin <wandrille.duchemin@insa-lyon.fr>, Benoit Goussen <Benoit.Goussen@ibacon.com>, Guillaume Kon-Kam-king <guillaume.kon-kam-king@univ-lyon1.fr>, Christelle Lopes <christelle.lopes@univ-lyon1.fr>, Philippe Ruiz <philippe.ruiz@univ-lyon1.fr>, Alexander Singer, <Alexander.Singer@rifcon.de> Philippe Veber <philippe.veber@univ-lyon1.fr>

Maintainer: Philippe Veber <philippe.veber@univ-lyon1.fr>

References

Delignette-Muller, M.L., Ruiz P. and Veber P. (2017) Robust fit of toxicokinetic-toxicodynamic models using prior knowledge contained in the design of survival toxicity tests.

Delignette-Muller, M.L., Lopes, C., Veber, P. and Charles, S. (2014) Statistical handling of reproduction data for exposure-response modelling.

Forfait-Dubuc, C., Charles, S., Billoir, E. and Delignette-Muller, M.L. (2012) Survival data analyses in ecotoxicology: critical effect concentrations, methods and models. What should we use?

Plummer, M. (2013) JAGS Version 4.0.0 user manual. https://sourceforge.net/projects/mcmc-jags/files/Manuals/4.x/jags_user_manual.pdf/download

Baudrot, V., Preux, S., Ducrot, V., Pavé, A. and Charles, S. (2018) New insights to compare and choose TKTD models for survival based on an inter-laboratory study for Lymnaea stagnalis exposed to Cd.

EFSA PPR Scientific Opinion (2018) Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms https://www.efsa.europa.eu/en/efsajournal/pub/5377.

See Also

rjags, ggplot2

A simulated exposure profile with 11641 time points.

Description

Exposure profile of 11641 time points used for prediction.

Usage

data(FOCUSprofile)

Format

A data frame with 11641 observations on the following two variables:

time

A vector of class numeric.

conc

A vector of class numeric with exposure concentrations.

and

replicate

A vector of class factor.

Predict X% Lethal Concentration at the maximum time point (default).

Description

Predict median and 95% credible interval of the x% Lethal Concentration.

The function LCx, x% Lethal Concentration (LC_x), is use to compute the dose required to kill x% of the members of a tested population after a specified test duration (time_LCx) (default is the maximum time point of the experiment).

Mathematical definition of x% Lethal Concentration at time t, denoted LC(x,t), is:

S(LC(x,t), t) = S(0, t)*(1- x/100),

where S(LC(x,t), t) is the survival probability at concentration LC(x,t) at time t, and S(0,t) is the survival probability at no concentration (i.e. concentration is 0) at time t which reflect the background mortality h_b:

S(0, t) = exp(-hb* t).

In the function LCx, we use the median of S(0,t) to rescale the x% Lethal Concentration at time t.

Usage

LCx(object, ...)

## S3 method for class 'survFit'
LCx(object, X, time_LCx = NULL, conc_range = NULL, npoints = 100, ...)

Arguments

Details

When class of object is survFit, see LCx.survFit.

Value

returns an object of class LCx.

The function returns an object of class LCx, which is a list with the following information:

Predict the Multiplication Factor leading to x% of reduction in survival at a specific time.

Description

Generic method for MFx, a function denoted MF(x,t) for x% Multiplication Factor at time t.

The function MFx, x% Multiplication Factor at time t, (MF(x,t)), is used to compute the multiplication factor applied to the concentration exposure profile in order to reduce by x% (argument X) the survival probability at a specified test duration t (argument time_MFx) (default is the maximum time point of the experiment).

Mathematical definition of x% Multiplication Factor at time t (at the end of a time series T = \{0, \dots, t\}), denoted MF(x,t), is given by:

S(MF(x,t) * C_w(\tau \in T), t) = S( C_w(\tau \in T), t)*(1- x/100),

where C_w(\tau \in T) is the initial exposure profile without multiplication factor. And so the expression S(MF(x,t)* C_w(\tau \in T), t) is the survival probability after an exposure profile MF(x,t)* C_w(\tau \in T) at time t.

This is a method to replace function MFx used on survFit object when computing issues happen. MFx_ode uses the deSolve library to improve robustness. However, time to compute may be longer.

The function MFx_ode, x% Multiplication Factor at time t, (MF(x,t)), is used to compute the multiplication factor applied to the concentration exposure profile in order to reduce by x% (argument X) the survival probability at a specified test duration t (argument time_MFx) (default is the maximum time point of the experiment).

Mathematical definition of x% Multiplication Factor at time t (at the end of a time series T = \{0, \dots, t\}), denoted MF(x,t), is given by:

S(MF(x,t) * C_w(\tau \in T), t) = S( C_w(\tau \in T), t)*(1- x/100),

where C_w(\tau \in T) is the initial exposure profile without multiplication factor. And so the expression S(MF(x,t)* C_w(\tau \in T), t) is the survival probability after an exposure profile MF(x,t)* C_w(\tau \in T) at time t.

Usage

MFx(object, ...)

## S3 method for class 'survFit'
MFx(
  object,
  data_predict,
  X = 50,
  time_MFx = NULL,
  MFx_range = c(0, 1000),
  mcmc_size = 1000,
  hb_value = TRUE,
  spaghetti = FALSE,
  accuracy = 0.01,
  quiet = FALSE,
  threshold_iter = 100,
  hb_valueFORCED = 0,
  ode = TRUE,
  interpolate_length = NULL,
  interpolate_method = "linear",
  ...
)

MFx_ode(object, ...)

## S3 method for class 'survFit'
MFx_ode(
  object,
  data_predict,
  X = 50,
  time_MFx = NULL,
  MFx_range = c(0, 1000),
  mcmc_size = 1000,
  hb_value = TRUE,
  spaghetti = FALSE,
  accuracy = 0.01,
  quiet = FALSE,
  threshold_iter = 100,
  hb_valueFORCED = 0,
  interpolate_length = NULL,
  interpolate_method = "linear",
  ...
)

Arguments

Details

When class of object is survFit, see MFx.survFit.

Value

returns an object of class MFx

The function returns an object of class MFx, which is a list with the following information:

The function returns an object of class MFx, which is a list with the following information:

Reproduction and survival data sets for Daphnia magna exposed to cadmium during 21 days

Description

Reproduction and survival data sets of chronic laboratory toxicity tests with Daphnia magna freshwater invertebrate exposed to five concentrations of cadmium during 21 days. Five concentrations were tested, with four replicates per concentration. Each replicate contained 10 organisms. Reproduction and survival were monitored at 10 time points.

Usage

data(cadmium1)

Format

A data frame with 200 observations of the following five variables:

replicate

A vector of class numeric with the replicate code (1 to 20).

conc

A vector of class numeric with the cadmium concentrations in \mu g.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

Nrepro

A vector of class integer with the number of offspring at each time point for each concentration and each replicate.

References

Billoir, E., Delhaye, H., Forfait, C., Clement, B., Triffault-Bouchet, G., Charles, S. and Delignette-Muller, M.L. (2012) Comparison of toxicity tests with different exposure time patterns: The added value of dynamic modelling in predictive ecotoxicology, Ecotoxicology and Environmental Safety, 75, 80-86.

Reproduction and survival data sets for Lymnaea stagnalis exposed to cadmium during 28 days

Description

Reproduction and survival data sets of chronic laboratory toxicity tests with snails (Lymnaea stagnalis) exposed to six concentrations of cadmium during 28 days. Six concentrations were tested, with six replicates per concentration. Each replicate contained five organisms. Reproduction and survival were monitored at 17 time points.

Usage

data(cadmium2)

Format

A data frame with 612 observations of the following five variables:

replicate

A vector of class numeric with the replicate code (1 to 36).

conc

A vector of class integer with the cadmium concentrations in \mu g.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

Nrepro

A vector of class integer with the number of clutches at each time point for each concentration and each replicate.

References

Ducrot, V., Askem, C., Azam, D., Brettschneider, D., Brown, R., Charles, S., Coke, M., Collinet, M., Delignette-Muller, M.L., Forfait-Dubuc, C., Holbech, H., Hutchinson, T., Jach, A., Kinnberg, K.L., Lacoste, C., Le Page, G., Matthiessen, P., Oehlmann, J., Rice, L., Roberts, E., Ruppert, K., Davis, J.E., Veauvy, C., Weltje, L., Wortham, R. and Lagadic, L. (2014) Development and validation of an OECD reproductive toxicity test guideline with the pond snail Lymnaea stagnalis (Mollusca, Gastropoda), Regulatory Toxicology and Pharmacology, 70(3), 605-14.

Charles, S., Ducrot, V., Azam, D., Benstead, R., Brettschneider, D., De Schamphelaere, K., Filipe Goncalves, S., Green, J.W., Holbech, H., Hutchinson, T.H., Faber, D., Laranjeiro, F., Matthiessen, P., Norrgren, L., Oehlmann, J., Reategui-Zirena, E., Seeland-Fremer, A., Teigeler, M., Thome, J.P., Tobor Kaplon, M., Weltje, L., Lagadic, L. (2016) Optimizing the design of a reproduction toxicity test with the pond snail Lymnaea stagnalis, Regulatory Toxicology and Pharmacology, vol. 81 pp.47-56.

Reproduction and survival data sets for Daphnia magna exposed to chlordan during 21 days

Description

Reproduction and survival data sets of chronic laboratory toxicity tests with Daphnia magna freshwater invertebrate exposed to six concentrations of one organochlorine insecticide (chlordan) during 21 days. Six concentrations were tested, with 10 replicates per concentration. Each replicate contained one organism. Reproduction and survival were monitored at 22 time points.

Usage

data(chlordan)

Format

A data frame with 1320 observations of the following five variables:

replicate

A vector of class numeric with the replicate code (1 to 60).

conc

A vector of class numeric with the chlordan concentrations in \mu g.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

Nrepro

A vector of class integer with the number of offspring at each time point for each concentration and each replicate.

References

Manar, R., Bessi, H. and Vasseur, P. (2009) Reproductive effects and bioaccumulation of chlordan in Daphnia magna, Environmental Toxicology and Chemistry, 28, 2150-2159.

Reproduction and survival data sets for Daphnia magna exposed to copper during 21 days

Description

Reproduction and survival data sets of chronic laboratory toxicity tests with Daphnia magna freshwater invertebrate exposed to five concentrations of copper during 21 days. Five concentrations were tested, with three replicates per concentration. Each replicate contained 20 organisms. Reproduction and survival were monitored at 16 time points.

Usage

data(copper)

Format

A data frame with 240 observations of the following five variables:

replicate

A vector of class numeric with the replicate code (1 to 15).

conc

A vector of class numeric with the copper concentrations in \mu g.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

Nrepro

A vector of class integer with the number of offspring at each time point for each concentration and each replicate.

References

Billoir, E., Delignette-Muller, M.L., Pery, A.R.R. and Charles, S. (2008) A Bayesian Approach to Analyzing Ecotoxicological Data, Environmental Science & Technology, 42 (23), 8978-8984.

Survival data set for Daphnia magna exposed to dichromate during 21 days

Description

Survival data set of chronic laboratory toxicity tests with Daphnia magna freshwater invertebrate exposed to six concentrations of one oxidizing agent (potassium dichromate) during 21 days. Six concentrations were tested with one replicate of 50 organisms per concentration. Survival is monitored at 10 time points.

Usage

data(dichromate)

Format

A data frame with 60 observations on the following four variables:

replicate

A vector of class numeric with the replicate code (1).

conc

A vector of class numeric with dichromate concentrations in mg.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

References

Bedaux, J., Kooijman, SALM (1994) Statistical analysis of toxicity tests, based on hazard modeling, Environmental and Ecological Statistics, 1, 303-314.

Test in a well-formed argument to function 'survData' if the concentration is constant and different from NA for each replicate (each time-serie)

Description

Test in a well-formed argument to function 'survData' if the concentration is constant and different from NA for each replicate (each time-serie)

Usage

is_exposure_constant(x)

Arguments

Value

a boolean TRUE if concentration in replicate is constant, or FALSE if the concentration in at least one of the replicates is time-variable, and/or if NA occures.

Create a list giving data to use in Bayesian inference.

Description

Create a data set to analyse a survDataCstExp object.

Create a data set to analyse a survDataVarExp object.

Usage

modelData(x, ...)

## S3 method for class 'survDataCstExp'
modelData(x, model_type = NULL, ...)

## S3 method for class 'survDataVarExp'
modelData(x, model_type = NULL, extend_time = 100, ...)

Arguments

Value

A list for parameterization of priors for Bayesian inference.

A list for parameterization of priors for Bayesian inference.

A list for parameterization of priors for Bayesian inference.

Plotting method for LCx objects

Description

This is the generic plot S3 method for the LCx class. It plots the survival probability as a function of concentration.

Usage

## S3 method for class 'LCx'
plot(
  x,
  xlab = "Concentration",
  ylab = "Survival probability \n median and 95 CI",
  main = NULL,
  subtitle = NULL,
  ...
)

Arguments

Value

a plot of class ggplot

Plotting method for MFx objects

Description

This is the generic plot S3 method for the MFx class. It plots the survival probability as a function of the multiplication factor applied or as a function of time.

Usage

## S3 method for class 'MFx'
plot(
  x,
  x_variable = "MFx",
  xlab = NULL,
  ylab = "Survival probability \n median and 95 CI",
  main = NULL,
  log_scale = FALSE,
  ncol = 3,
  ...
)

Arguments

Value

a plot of class ggplot

Plotting method for reproData objects

Description

This is the generic plot S3 method for the reproData class. It plots the cumulated number of offspring as a function of time.

Usage

## S3 method for class 'reproData'
plot(
  x,
  xlab,
  ylab = "Cumulated Number of offspring",
  main = NULL,
  concentration = NULL,
  style = "ggplot",
  pool.replicate = FALSE,
  addlegend = FALSE,
  remove.someLabels = FALSE,
  ...
)

Arguments

Value

a plot of class ggplot

Note

When style = "generic", the function calls the generic function plot

When style = "ggplot", the function return an object of class gg and ggplot, see function ggplot

Plotting method for reproFitTT objects

Description

This is the generic plot S3 method for the reproFitTT class. It plots the concentration-effect fit under target time reproduction analysis.

Usage

## S3 method for class 'reproFitTT'
plot(
  x,
  xlab = "Concentration",
  ylab = "Nb of offspring per ind/day",
  main = NULL,
  fitcol = "orange",
  fitlty = 1,
  fitlwd = 1,
  spaghetti = FALSE,
  cicol = "orange",
  cilty = 2,
  cilwd = 1,
  ribcol = "grey70",
  addlegend = FALSE,
  log.scale = FALSE,
  style = "ggplot",
  ...
)

Arguments

Details

The fitted curve represents the estimated reproduction rate at the target time as a function of the chemical compound concentration. The function plots 95% credible intervals for the estimated reproduction rate (by default the grey area around the fitted curve). Typically a good fit is expected to display a large overlap between the two types of intervals. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. It consists of the representation of simulated curves using parameter values sampled in the posterior distribution (10% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Note

When style = "generic", the function calls the generic function plot

When style = "ggplot", the function return an object of class ggplot, see function ggplot

Plotting method for survData objects

Description

This is the generic plot S3 method for the survData class. It plots the number of survivors as a function of time.

Usage

## S3 method for class 'survDataCstExp'
plot(
  x,
  xlab = "Time",
  ylab = "Number of survivors",
  main = NULL,
  concentration = NULL,
  style = "ggplot",
  pool.replicate = FALSE,
  addlegend = FALSE,
  remove.someLabels = FALSE,
  ...
)

Arguments

Value

a plot of class ggplot

Note

When style = "ggplot" (default), the function calls function ggplot and returns an object of class ggplot.

Plotting method for survDataVarExp objects

Description

This is the generic plot S3 method for the survDataVarC class. It plots the number of survivors as a function of time.

Usage

## S3 method for class 'survDataVarExp'
plot(
  x,
  xlab = "Time",
  ylab = "Number of survivors",
  main = NULL,
  one.plot = FALSE,
  facetting_level = NULL,
  ...
)

Arguments

Value

an object of class ggplot, see function ggplot

Plotting method for survFit objects

Description

This is the generic plot S3 method for the survFit. It plots the fit obtained for each concentration of chemical compound in the original dataset.

Usage

## S3 method for class 'survFitCstExp'
plot(
  x,
  xlab = "Time",
  ylab = "Survival probability",
  main = NULL,
  concentration = NULL,
  spaghetti = FALSE,
  one.plot = FALSE,
  adddata = TRUE,
  addlegend = FALSE,
  style = "ggplot",
  ...
)

Arguments

Details

The fitted curves represent the estimated survival probability as a function of time for each concentration. The black dots depict the observed survival probability at each time point. Note that since our model does not take inter-replicate variability into consideration, replicates are systematically pooled in this plot. The function plots both 95% credible intervals for the estimated survival probability (by default the grey area around the fitted curve) and 95% binomial confidence intervals for the observed survival probability (as black error bars if adddata = TRUE). Both types of intervals are taken at the same level. Typically a good fit is expected to display a large overlap between the two types of intervals. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (2% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Plotting method for survFitPredict objects

Description

This is the generic plot S3 method for the survFitPredict. It plots the predicted survival probability for each concentration of the chemical compound in the provided dataset.

Usage

## S3 method for class 'survFitPredict'
plot(
  x,
  xlab = "Time",
  ylab = "Survival probability",
  main = NULL,
  spaghetti = FALSE,
  one.plot = FALSE,
  mcmc_size = NULL,
  ...
)

Arguments

Details

The fitted curves represent the predicted survival probability as a function of time for each concentration. The function plots both the 95% credible band and the predicted survival probability over time. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (10% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Plotting method for survFitPredict_Nsurv objects.

Description

This is the generic plot S3 method for the survFitPredict_Nsurv. It plots the predicted survival probability for each concentration of the chemical compound in the provided dataset.

Usage

## S3 method for class 'survFitPredict_Nsurv'
plot(
  x,
  xlab = "Time",
  ylab = "Number of survivors",
  main = NULL,
  spaghetti = FALSE,
  one.plot = FALSE,
  mcmc_size = NULL,
  ...
)

Arguments

Details

The fitted curves represent the predicted survival probability as a function of time for each concentration. The function plots both the 95% credible band and the predicted survival probability over time. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (10% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Plotting method for survFitTKTD objects

Description

This is the generic plot S3 method for the survFitTKTD. It plots the fit obtained for each concentration of chemical compound in the original dataset.

Usage

## S3 method for class 'survFitTKTD'
plot(
  x,
  xlab = "Time",
  ylab = "Survival probablity",
  main = NULL,
  concentration = NULL,
  spaghetti = FALSE,
  one.plot = FALSE,
  adddata = FALSE,
  addlegend = FALSE,
  style = "ggplot",
  ...
)

Arguments

Details

The fitted curves represent the estimated survival probablity as a function of time for each concentration When adddata = TRUE the black dots depict the observed survival probablity at each time point. Note that since our model does not take inter-replicate variability into consideration, replicates are systematically pooled in this plot. The function plots both 95% credible intervals for the estimated survival probablity (by default the grey area around the fitted curve) and 95% binomial confidence intervals for the observed survival probablity (as black error bars if adddata = TRUE). Both types of intervals are taken at the same level. Typically a good fit is expected to display a large overlap between the two types of intervals. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (2% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Plotting method for survFitTT objects

Description

This is the generic plot S3 method for the survFitTT class. It plots concentration-response fit under target time survival analysis.

Usage

## S3 method for class 'survFitTT'
plot(
  x,
  xlab = "Concentration",
  ylab = "Survival probability",
  main = NULL,
  fitcol = "orange",
  fitlty = 1,
  fitlwd = 1,
  spaghetti = FALSE,
  cicol = "orange",
  cilty = 2,
  cilwd = 1,
  ribcol = "grey70",
  adddata = FALSE,
  addlegend = FALSE,
  log.scale = FALSE,
  style = "ggplot",
  ...
)

Arguments

Details

The fitted curve represents the estimated survival probability at the target time as a function of the concentration of chemical compound; When adddata = TRUE the black dots depict the observed survival probability at each tested concentration. Note that since our model does not take inter-replicate variability into consideration, replicates are systematically pooled in this plot. The function plots both 95% credible intervals for the estimated survival probability (by default the grey area around the fitted curve) and 95% binomial confidence intervals for the observed survival probability (as black segments if adddata = TRUE). Both types of intervals are taken at the same level. Typically a good fit is expected to display a large overlap between the two intervals. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (10% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Note

When style = "ggplot", the function calls function ggplot and returns an object of class ggplot.

Plotting method for survFit objects

Description

This is the generic plot S3 method for the survFit. It plots the fit obtained for each concentration profile in the original dataset.

Usage

## S3 method for class 'survFitVarExp'
plot(
  x,
  xlab = "Time",
  ylab = "Survival probability",
  main = NULL,
  spaghetti = FALSE,
  one.plot = FALSE,
  adddata = TRUE,
  mcmc_size = NULL,
  scales = "fixed",
  addConfInt = TRUE,
  ...
)

Arguments

Details

The fitted curves represent the estimated survival probability as a function of time for each concentration profile. The black dots depict the observed survival probability at each time point. Note that since our model does not take inter-replicate variability into consideration, replicates are systematically pooled in this plot. The function plots both 95% binomial credible intervals for the estimated survival probability (by default the grey area around the fitted curve) and 95% binomial confidence intervals for the observed survival probability (as black segments if adddata = TRUE). Both types of intervals are taken at the same level. Typically a good fit is expected to display a large overlap between the two types of intervals. If spaghetti = TRUE, the credible intervals are represented by two dotted lines limiting the credible band, and a spaghetti plot is added to this band. This spaghetti plot consists of the representation of simulated curves using parameter values sampled in the posterior distribution (10% of the MCMC chains are randomly taken for this sample).

Value

a plot of class ggplot

Plot dose-response from raw data

Description

Plots the response of the effect as a function of the concentration at a given target time.

Usage

plotDoseResponse(x, ...)

Arguments

Value

a plot of class ggplot

Plot dose-response from reproData objects

Description

This is the generic plotDoseResponse S3 method for the reproData class. It plots the number of offspring per individual-days as a function of concentration at a given target time.

Usage

## S3 method for class 'reproData'
plotDoseResponse(
  x,
  xlab = "Concentration",
  ylab = "Nb of offspring per ind.day",
  main = NULL,
  ylim = NULL,
  target.time = NULL,
  style = "ggplot",
  log.scale = FALSE,
  remove.someLabels = FALSE,
  axis = TRUE,
  addlegend = TRUE,
  ...
)

Arguments

Details

The function plots the observed values of the reproduction rate (number of reproduction outputs per individual-day) at a given time point as a function of concentration. The 95 % Poisson confidence interval is added to each reproduction rate. It is calculated using function pois.exact from package epitools. As replicates are not pooled in this plot, overlapped points are shifted on the x-axis to help the visualization of replicates.

Value

a plot of class ggplot

Note

When style = "generic", the function calls the generic function plot

When style = "ggplot", the function return an object of class ggplot, see function ggplot

See Also

pois.exact

Plot dose-response from survData objects

Description

This is the generic plotDoseResponse S3 method for the survData class. It plots the survival probability as a function of concentration at a given target time.

Usage

## S3 method for class 'survDataCstExp'
plotDoseResponse(
  x,
  xlab = "Concentration",
  ylab = "Survival probability",
  main = NULL,
  target.time = NULL,
  style = "ggplot",
  log.scale = FALSE,
  remove.someLabels = FALSE,
  addlegend = TRUE,
  ...
)

Arguments

Details

The function plots the observed values of the survival probability at a given time point as a function of concentration. The 95 % binomial confidence interval is added to each survival probability. It is calculated using function binom.test from package stats. Replicates are systematically pooled in this plot.

Value

a plot of class ggplot

Note

When style = "generic", the function calls the generic function plot

When style = "ggplot", the function return an object of class ggplot, see function ggplot

See Also

binom.test

Generic method to plot priors and posteriors.

Description

Plot priors and posteriors of a survFit object

Usage

plot_prior_post(x, ...)

Arguments

Value

an object of class plot_prior_post

Plot posteriors vs priors

Description

Plot posteriors vs priors of a survFit object

Usage

## S3 method for class 'survFit'
plot_prior_post(x, size_sample = 1000, EFSA_name = FALSE, ...)

Arguments

Value

a plot of class ggplot

References

EFSA PPR Scientific Opinion (2018) Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms https://www.efsa.europa.eu/en/efsajournal/pub/5377

Posterior predictive check plot

Description

Plots posterior predictive check for reproFitTT, survFitTT, survFitTKTD, survFitCstExp and survFitVarExp objects.

This is the generic ppc S3 method for the reproFitTT class. It plots the predicted values with 95% credible intervals versus the observed values.

This is the generic ppc S3 method for the survFitCstExp class. It plots the predicted values along with 95% credible intervals versus the observed values for survFit objects.

This is the generic ppc S3 method for the survFitPredict_Nsurv class. It plots the predicted values along with 95% credible intervals versus the observed values for survFitPredict_Nsurv objects.

This is the generic ppc S3 method for the survFitTKTD class. It plots the predicted values along with 95% credible intervals versus the observed values for survFitTKTD objects.

This is the generic ppc S3 method for the survFitTT class. It plots the predicted values with 95 % credible intervals versus the observed values for survFitTT objects.

This is the generic ppc S3 method for the survFitVarExp class. It plots the predicted values along with 95% credible intervals versus the observed values for survFit objects.

Usage

ppc(x, ...)

## S3 method for class 'reproFitTT'
ppc(
  x,
  style = "ggplot",
  xlab = "Observed Cumul. Nbr. of offspring",
  ylab = "Predicted Cumul. Nbr. of offspring",
  main = NULL,
  ...
)

## S3 method for class 'survFitCstExp'
ppc(x, style = "ggplot", main = NULL, ...)

## S3 method for class 'survFitPredict_Nsurv'
ppc(
  x,
  xlab = "Observed nb of survivors",
  ylab = "Predicted nb of survivors",
  main = NULL,
  ...
)

## S3 method for class 'survFitTKTD'
ppc(x, style = "ggplot", main = NULL, ...)

## S3 method for class 'survFitTT'
ppc(x, style = "ggplot", main = NULL, ...)

## S3 method for class 'survFitVarExp'
ppc(
  x,
  xlab = "Observed nb of survivors",
  ylab = "Predicted nb of survivors",
  main = NULL,
  ...
)

Arguments

Details

Depending on the class of the object x see their links. for class reproFitTT: ppc.reproFitTT ; for class survFitTT: ppc.survFitTT ; for class survFitTKTD: ppc.survFitTKTD ; for class survFitCstExp: ppc.survFitCstExp and for class survFitVarExp: ppc.survFitVarExp.

The coordinates of black points are the observed values of the cumulated number of reproduction outputs for a given concentration (X-scale) and the corresponding predicted values (Y-scale). 95% prediction intervals are added to each predicted value, colored in green if this interval contains the observed value and in red in the other case. As replicates are not pooled in this plot, overlapped points are shifted on the X-axis to help the visualization of replicates. The bisecting line (y = x) is added to the plot in order to see if each prediction interval contains each observed value. As replicates are shifted on the X-axis, this line may be represented by steps.

The black points show the observed number of survivors (pooled replicates, on X-axis) against the corresponding predicted number (Y-axis). Predictions come along with 95% prediction intervals, which are depicted in green when they contain the observed value and in red otherwise. Samples with equal observed value are shifted on the X-axis. For that reason, the bisecting line (y = x), is represented by steps when observed values are low. That way we ensure green intervals do intersect the bisecting line.

For survFitPredict_Nsurv object, PPC is based on times series simulated for each replicate. In addition, the black points show the observed number of survivors (on X-axis) against the corresponding predicted number (Y-axis). Predictions come along with 95% prediction intervals, which are depicted in green when they contain the observed value and in red otherwise.

The black points show the observed number of survivors (pooled replicates, on X-axis) against the corresponding predicted number (Y-axis). Predictions come along with 95% prediction intervals, which are depicted in green when they contain the observed value and in red otherwise. Samples with equal observed value are shifted on the X-axis. For that reason, the bisecting line (y = x), is represented by steps when observed values are low. That way we ensure green intervals do intersect the bisecting line.

The coordinates of black points are the observed values of the number of survivors (pooled replicates) for a given concentration (X-axis) and the corresponding predicted values (Y-axis). 95% prediction intervals are added to each predicted value, colored in green if this interval contains the observed value and in red otherwise. The bisecting line (y = x) is added to the plot in order to see if each prediction interval contains each observed value. As replicates are shifted on the x-axis, this line is represented by steps.

The black points show the observed number of survivors (on X-axis) against the corresponding predicted number (Y-axis). Predictions come along with 95% prediction intervals, which are depicted in green when they contain the observed value and in red otherwise.

Value

a plot of class ggplot

a plot of class ggplot

a plot of class ggplot

a plot of class ggplot

a plot of class ggplot

a plot of class ggplot

a plot of class ggplot

Predict method for survFit objects

Description

This is the generic predict S3 method for the survFit class. It provides simulation for "SD" or "IT" models under constant or time-variable exposure.

It provides the simulated number of survivors for "SD" or "IT" models under constant or time-variable exposure.

It provides the simulated number of survivors for "SD" or "IT" models under constant or time-variable exposure.

This is a method to replace function predict_Nsurv used on survFit object when computing issues happen. predict_nsurv_ode uses the deSolve library to improve robustness. However, time to compute may be longer.

Usage

## S3 method for class 'survFit'
predict(
  object,
  data_predict = NULL,
  spaghetti = FALSE,
  mcmc_size = NULL,
  hb_value = TRUE,
  ratio_no.NA = 0.95,
  hb_valueFORCED = NA,
  extend_time = 100,
  ...
)

predict_Nsurv(object, ...)

## S3 method for class 'survFit'
predict_Nsurv(
  object,
  data_predict = NULL,
  spaghetti = FALSE,
  mcmc_size = NULL,
  hb_value = TRUE,
  hb_valueFORCED = NA,
  extend_time = 100,
  ...
)

predict_Nsurv_ode(
  object,
  data_predict,
  spaghetti,
  mcmc_size,
  hb_value,
  hb_valueFORCED,
  extend_time,
  interpolate_length,
  interpolate_method,
  ...
)

## S3 method for class 'survFit'
predict_Nsurv_ode(
  object,
  data_predict = NULL,
  spaghetti = FALSE,
  mcmc_size = 1000,
  hb_value = TRUE,
  hb_valueFORCED = NA,
  extend_time = 100,
  interpolate_length = NULL,
  interpolate_method = "linear",
  ...
)

Arguments

Value

a list of data.frame with the quantiles of outputs in df_quantiles or all the MCMC chaines df_spaghetti

an object of class predict_Nsurv.

The function returns an object of class survFitPredict_Nsurv, which is a list with the two following data.frame:

an object of class predict_Nsurv_ode.

a list of data.frame with the quantiles of outputs in df_quantiles or all the MCMC chaines df_spaghetti

Checking goodness-of-fit method for survFitPredict and survFitPredict_Nsurv objects

Description

It returns measures of goodness-of-fit for predictions.

Provide various criteria for assessment of the model performance: (i) percentage of observation within the 95% credible interval of the Posterior Prediction Check (PPC), the Normalised Root Mean Square Error (NRMSE) and the Survival Probability Prediction Error (SPPE) as reccommended by the recent Scientific Opinion from EFSA (2018).

Usage

predict_Nsurv_check(object, ...)

## S3 method for class 'survFitPredict_Nsurv'
predict_Nsurv_check(object, ...)

Arguments

Value

return a list of data.frame.

The function return a list with three items:

@references EFSA PPR Scientific Opinion (2018) Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms https://www.efsa.europa.eu/en/efsajournal/pub/5377

Predict method for survFit objects

Description

This is a method to replace function predict used on survFit object when computing issues happen. predict_ode uses the deSolve library to improve robustness. However, time to compute may be longer.

Usage

predict_ode(object, ...)

Arguments

Value

an object of class predict_ode

Predict method for survFit objects

Description

This is the generic predict S3 method for the survFit class. It provides predicted survival rate for "SD" or "IT" models under constant or time-variable exposure.

Usage

## S3 method for class 'survFit'
predict_ode(
  object,
  data_predict = NULL,
  spaghetti = FALSE,
  mcmc_size = 1000,
  hb_value = TRUE,
  interpolate_length = 100,
  interpolate_method = "linear",
  hb_valueFORCED = NA,
  ...
)

Arguments

Value

a list of data.frame with the quantiles of outputs in df_quantiles or all the MCMC chaines df_spaghetti

Print msgTables objects

Description

Print in the REPL the msgTables

Usage

## S3 method for class 'msgTable'
print(x, ...)

Arguments

Value

Print in the REPL the msgTables

Print of reproFitTT object

Description

This is the generic print S3 method for the reproFitTT class. It prints the underlying JAGS model and some information on the Bayesian inference procedure.

Usage

## S3 method for class 'reproFitTT'
print(x, ...)

Arguments

Value

print the model text and the Jags Computing information

Print of survFit object

Description

This is the generic print S3 method for the survFitCstExp class. It prints the underlying JAGS model and some information on the Bayesian inference procedure.

Usage

## S3 method for class 'survFitCstExp'
print(x, ...)

Arguments

Value

print the model text and the Jags Computing information

Print of survFitTKTD object

Description

This is the generic print S3 method for the survFitTKTD class. It prints the underlying JAGS model and some information on the Bayesian inference procedure.

Usage

## S3 method for class 'survFitTKTD'
print(x, ...)

Arguments

Value

print the model text and the Jags Computing information

Print of survFitTT object

Description

This is the generic print S3 method for the survFitTT class. It prints the underlying JAGS model and some information on the Bayesian inference procedure.

Usage

## S3 method for class 'survFitTT'
print(x, ...)

Arguments

Value

print the model text and the Jags Computing information

Print of survFitVarExp object

Description

This is the generic print S3 method for the survFitVarExp class. It prints the underlying JAGS model and some information on the Bayesian inference procedure.

Usage

## S3 method for class 'survFitVarExp'
print(x, ...)

Arguments

Value

print the model text and the Jags Computing information

Density distribution of priors.

Description

Return a data.frame with prior density distributions of parameters used in object.

Usage

priors_distribution(object, ...)

Arguments

Details

When the object is of class survFit, see priors_distribution.survFit

Value

an object of class priors_distribution

Density distribution of priors from a survFit object.

Description

Return a data.frame with priors distribution of parameters used in object.

Usage

## S3 method for class 'survFit'
priors_distribution(object, size_sample = 1000, EFSA_name = FALSE, ...)

Arguments

Value

a data.frame with prio distribution.

References

EFSA PPR Scientific Opinion (2018) Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms https://www.efsa.europa.eu/en/efsajournal/pub/5377.

Create a list of scalars giving priors to use in Bayesian inference.

Description

Create a list of scalars giving priors to use in Bayesian inference.

Usage

priors_survData(x, model_type = NULL)

Arguments

Value

A list for parameterization of priors for Bayesian inference with JAGS.

Survival data set for Gammarus pulex exposed to propiconazole during four days

Description

Survival data set of chronic laboratory toxicity tests with Gammarus pulex freshwater invertebrate exposed to eight concentrations of one fungicide (propiconazole) during four days. Eight concentrations were tested with two replicates of 10 organisms per concentration. Survival is monitored at five time points.

Usage

data(propiconazole)

Format

A dataframe with 75 observations on the following four variables:

replicate

A vector of class factor with the replicate code (SC for the control and A1 to G2 for other profiles).

conc

A vector of class numeric with propiconazole concentrations in \mu mol.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

References

Nyman, A.-M., Schirmer, K., Ashauer, R., (2012) Toxicokinetic-toxicodynamic modelling of survival of Gammarus pulex in multiple pulse exposures to propiconazole: model assumptions, calibration data requirements and predictive power, Ecotoxicology, (21), 1828-1840.

Survival data set for Gammarus pulex exposed to propiconazole during 10 days with time-variable exposure concentration (non-standard pulsed toxicity experiments)

Description

Survival data set of laboratory toxicity tests with Gammarus pulex freshwater invertebrates exposed to several profiles of concentrations (time-variable concentration for each time series) of one fungicide (propiconazole) during 10 days.

Usage

data(propiconazole_pulse_exposure)

Format

A data frame with 74 observations on the following four variables:

replicate

A vector of class factor with the replicate code (varControl, varA, varB and varC).

conc

A vector of class numeric with propiconazole concentrations in \mu mol.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

References

Nyman, A.-M., Schirmer, K., Ashauer, R., (2012) Toxicokinetic-toxicodynamic modelling of survival of Gammarus pulex in multiple pulse exposures to propiconazole: model assumptions, calibration data requirements and predictive power, Ecotoxicology, (21), 1828-1840.

Survival data set for Gammarus pulex exposed to propiconazole during four days

Description

Survival data set of chronic laboratory toxicity tests with Gammarus pulex freshwater invertebrate exposed to eight concentrations of one fungicide (propiconazole) during four days. Eight concentrations were tested with two replicates of 10 organisms per concentration. Survival is monitored at five time points.

Usage

data(propiconazole_split)

Format

A dataframe with 75 observations on the following four variables:

replicate

A vector of class factor with the replicate code (SC for the control and A1 to G2 for other profiles).

conc

A vector of class numeric with propiconazole concentrations in \mu mol.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

References

Nyman, A.-M., Schirmer, K., Ashauer, R., (2012) Toxicokinetic-toxicodynamic modelling of survival of Gammarus pulex in multiple pulse exposures to propiconazole: model assumptions, calibration data requirements and predictive power, Ecotoxicology, (21), 1828-1840.

Creates a dataset for reproduction toxicity analysis

Description

This function creates a reproData object from experimental data provided as a data.frame. The resulting object can then be used for plotting and model fitting. The reproData class is a sub-class of survData, meaning that all functions and method available for survival analysis can be used with reproData objects.

Usage

reproData(x)

Arguments

Details

The x argument contains the experimental data, and should have the same structure than the argument of survData, plus a single additional column providing the total number of offspring observed since the last time point. The function fails if x does not meet the expected requirements. Please run reproDataCheck to ensure x is well-formed.

Note that experimental data with time-variable exposure are not supported.

Value

An object of class reproData.

Checks if an object can be used to perform reproduction toxicity data analysis

Description

The reproDataCheck function can be used to check if an object containing data from a reproduction toxicity assay meets the expectations of the function reproData.

Usage

reproDataCheck(data, diagnosis.plot = TRUE)

Arguments

Details

Since in morse' reproduction data sets are a special case of survival data sets, reproDataCheck performs the same verifications than survDataCheck plus additional ones that are specific to reproduction data.

Value

The function returns a data.frame similar to the one returned by survDataCheck, except that it may contain the following additional error ids:

• NreproInteger: column Nrepro contains values of class other than integer

• Nrepro0T0: Nrepro is not 0 at time 0 for each concentration and each replicate

• Nsurvt0Nreprotp1P: at a given time T, the number of alive individuals is null and the number of collected offspring is not null for the same replicate and the same concentration at time T+1

Note

If an error of type dataframeExpected or missingColumn is detected, the function reproDataCheck is stopped. When no error is detected the reproDataCheck function returns an empty dataframe.

See Also

reproData

Fits a Bayesian concentration-effect model for target-time reproduction analysis

Description

This function estimates the parameters of a concentration-effect model for target-time reproduction analysis using Bayesian inference. In this model the endpoint is the cumulated number of reproduction outputs over time, with potential mortality all along the experiment.

Usage

reproFitTT(
  data,
  stoc.part = "bestfit",
  target.time = NULL,
  ecx = c(5, 10, 20, 50),
  n.chains = 3,
  quiet = FALSE
)

Arguments

Details

Because some individuals may die during the observation period, the reproduction rate alone is not sufficient to account for the observed number of offspring at a given time point. In addition, we need the time individuals have stayed alive during this observation period. The reproFitTT function estimates the number of individual-days in an experiment between its start and the target time. This covariable is then used to estimate a relation between the chemical compound concentration and the reproduction rate per individual-day.

The reproFitTT function fits two models, one where inter-individual variability is neglected ("Poisson" model) and one where it is taken into account ("gamma-Poisson" model). When setting stoc.part to "bestfit", a model comparison procedure is used to choose between both. More details are presented in the vignette accompanying the package.

Value

The function returns an object of class reproFitTT which is a list of the following objects:

Summary of reproData object

Description

This is the generic summary S3 method for the reproData class. It provides information about the structure of the data set and the experimental design.

Usage

## S3 method for class 'reproData'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the same information than summary.survDataCstExp plus an additional one:

Summary of reproFitTT object

Description

This is the generic summary S3 method for the reproFitTT class. It shows the quantiles of priors and posteriors on parameters and the quantiles of the posterior on the ECx estimates.

Usage

## S3 method for class 'reproFitTT'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

Summary of survDataCstExp object

Description

The generic summary S3 method for the survDataCstExp class provides information about the structure of the data set and the experimental design.

Usage

## S3 method for class 'survDataCstExp'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

Summary of survDataVarExp object

Description

The generic summary S3 method for the survDataVarExp class provides information about the structure of the data set and the experimental design.

Usage

## S3 method for class 'survDataVarExp'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

Summary of survFit object

Description

This is the generic summary S3 method for the survFit class. It shows the quantiles of priors and posteriors on parameters.

Usage

## S3 method for class 'survFit'
summary(object, quiet = FALSE, EFSA_name = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

References

EFSA PPR Scientific Opinion (2018) Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms https://www.efsa.europa.eu/en/efsajournal/pub/5377.

Summary of survFitTKTD object

Description

This is the generic summary S3 methode for the survFitTKTD class. It shows the quantiles of priors and posteriors on parameters.

Usage

## S3 method for class 'survFitTKTD'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

Summary of survFitTT object

Description

This is the generic summary S3 method for the survFitTT class. It shows the quantiles of priors and posteriors on parameters and the quantiles of the posteriors on the LCx estimates.

Usage

## S3 method for class 'survFitTT'
summary(object, quiet = FALSE, ...)

Arguments

Value

The function returns a list with the following information:

Creates a data set for survival analysis

Description

This function creates a survData object from experimental data provided as a data.frame. The resulting object can then be used for plotting and model fitting. It can also be used to generate individual-time estimates.

The survDataCheck function can be used to check if an object containing survival data is formatted according to the expectations of the survData function.

Usage

survData(x)

survDataCheck(data, diagnosis.plot = FALSE)

Arguments

Details

Survival data sets can be under either constant or time-variable exposure profile. The resulting object, in addition to its survData class, inherits the class survDataCstExp or survDataVarExp respectively.

The x argument describes experimental results from a survival toxicity test. Each line of the data.frame corresponds to one experimental measurement, that is a number of alive individuals at a given concentration at a given time point and in a given replicate. Note that either the concentration or the number of alive individuals may be missing. The data set is inferred to be under constant exposure if the concentration is constant for each replicate and systematically available. The function survData fails if x does not meet the expected requirements. Please run survDataCheck to ensure x is well-formed.

Value

A dataframe of class survData and column replicate as factor.

The function returns a dataframe of class msgTable and data.frame with two columns: id and msg of character strings. When no error is detected the object is empty. Here is the list of possible error ids with their meaning:

Note

If an error of type dataframeExpected or missingColumn is detected, the function survDataCheck is stopped before looking for other errors.

See Also

survDataCheck

survData

Joins a concentration with a survival data set into an argument for 'survData' when the concentration varies over time

Description

This function joins two data sets, one for exposure measurements, the other for survival measurements, into a single dataframe that can be used with the survData function.

Usage

survData_join(x, y)

Arguments

Value

a dataframe suitable for 'survData'

Fits a TKTD model for survival analysis using Bayesian inference

Description

This function estimates the parameters of a TKTD model ('SD' or 'IT') for survival analysis using Bayesian inference. In this model, the survival rate of individuals is modeled as a function of the chemical compound concentration with a mechanistic description of the effects on survival over time.

Usage

survFit(
  data,
  model_type,
  quiet,
  n.chains,
  n.adapt,
  n.iter,
  n.warmup,
  thin.interval,
  limit.sampling,
  dic.compute,
  dic.type,
  hb_value,
  hb_valueFIXED,
  ...
)

## S3 method for class 'survDataCstExp'
survFit(
  data,
  model_type = NULL,
  quiet = FALSE,
  n.chains = 3,
  n.adapt = 3000,
  n.iter = NULL,
  n.warmup = NULL,
  thin.interval = NULL,
  limit.sampling = TRUE,
  dic.compute = FALSE,
  dic.type = "pD",
  hb_value = TRUE,
  hb_valueFIXED = NA,
  ...
)

## S3 method for class 'survDataVarExp'
survFit(
  data,
  model_type = NULL,
  quiet = FALSE,
  n.chains = 3,
  n.adapt = 1000,
  n.iter = NULL,
  n.warmup = NULL,
  thin.interval = NULL,
  limit.sampling = TRUE,
  dic.compute = FALSE,
  dic.type = "pD",
  hb_value = TRUE,
  hb_valueFIXED = NA,
  extend_time = 100,
  ...
)

Arguments

Details

The function survFit returns the parameter estimates of Toxicokinetic-toxicodynamic (TKTD) models SD for 'Stochastic Death' or IT fo 'Individual Tolerance'. TKTD models, and particularly the General Unified Threshold model of Survival (GUTS), provide a consistent process-based framework to analyse both time and concentration dependent datasets. In GUTS-SD, all organisms are assumed to have the same internal concentration threshold (denoted z), and, once exceeded, the instantaneous probability to die increases linearly with the internal concentration. In GUTS-IT, the threshold concentration is distributed among all the organisms, and once exceeded in one individual, this individual dies immediately.

When class of object is survDataCstExp, see survFit.survDataCstExp ; and for a survDataVarExp, see survFit.survDataVarExp.

Value

an object of class survFit

The function returns an object of class survFitCstExp, which is a list with the following information:

The function returns an object of class survFitVarExp, which is a list with the following information:

References

Jager, T., Albert, C., Preuss, T. G. and Ashauer, R. (2011) General unified threshold model of survival-a toxicokinetic-toxicodynamic framework for ecotoxicology, Environmental Science and Technology, 45, 2529-2540. 303-314.

Fits a TKTD for survival analysis using Bayesian inference for survDataTKTD object

Description

This function estimates the parameters of a TKTD model for survival analysis using Bayesian inference. In this model, the survival rate of individuals is modeled as a function of the chemical compound concentration with a mechanistic description of the effects on survival over time.

Usage

survFitTKTD(data, n.chains = 3, quiet = FALSE)

Arguments

Value

The function returns an object of class survFitTKTD, which is a list with the following information:

References

Delignette-Muller ML, Ruiz P and Veber P (2017). Robust fit of toxicokinetic-toxicodynamic models using prior knowledge contained in the design of survival toxicity tests.

Bedaux, J., Kooijman, SALM (1994) Statistical analysis of toxicity tests, based on hazard modeling, Environmental and Ecological Statistics, 1, 303-314.

Fits a Bayesian concentration-response model for target-time survival analysis

Description

Fits a Bayesian concentration-response model for target-time survival analysis

Usage

survFitTT(data, ...)

Arguments

Value

an object of class survFitTT

Fits a Bayesian concentration-response model for target-time survival analysis

Description

This function estimates the parameters of an concentration-response model for target-time survival analysis using Bayesian inference. In this model, the survival rate of individuals at a given time point (called target time) is modeled as a function of the chemical compound concentration. The actual number of surviving individuals is then modeled as a stochastic function of the survival rate. Details of the model are presented in the vignette accompanying the package.

Usage

## S3 method for class 'survDataCstExp'
survFitTT(
  data,
  target.time = NULL,
  lcx = c(5, 10, 20, 50),
  n.chains = 3,
  quiet = FALSE,
  ...
)

Arguments

Details

The function returns parameter estimates of the concentration-response model and estimates of the so-called LC_x, that is the concentration of chemical compound required to get an (1 - x/100) survival rate.

Value

The function returns an object of class survFitTT, which is a list with the following information:

Reproduction and survival data sets for Daphnia magna exposed to zinc during 21 days

Description

Reproduction and survival data sets of a chronic laboratory toxicity tests with Daphnia magna freshwater invertebrate exposed to four concentrations of zinc during 21 days. Four concentrations were tested with three replicates per concentration. Each replicate contained 20 organisms. Reproduction and survival were monitored at 15 time points.

Usage

data(zinc)

Format

A data frame with 180 observations on the following five variables:

replicate

A vector of class numeric with the replicate code (1 to 12).

conc

A vector of class numeric with zinc concentrations in mg.L^{-1}.

time

A vector of class integer with the time points (in days from the beginning of the experiment t = 0).

Nsurv

A vector of class integer with the number of alive individuals at each time point for each concentration and each replicate.

Nrepro

A vector of class integer with the number of offspring at each time point for each concentration and each replicate.

References

Billoir, E.,Delignette-Muller, M.L., Pery, A.R.R. and Charles S. (2008) A Bayesian Approach to Analyzing Ecotoxicological Data, Environmental Science & Technology, 42 (23), 8978-8984.