GUTS: Fast Calculation of the Likelihood of a Stochastic Survival...

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Description

GUTS (General Unified Threshold model of Survival) is a stochastic survival model for ecotoxicology. The package allows for the definition of exposure and survival time series as well as parameter values, and the fast calculation of the survival probabilities as well as the logarithm of the corresponding likelihood.

The package implements the GUTS-SIC (also called GUTS-RED) variants that assume a one-compartment model with first-order toxicokinetics.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
guts_setup(C, Ct, y, yt, dist = "lognormal",
	model = "Proper", N = 1000, M = 10000)

guts_calc_loglikelihood(gobj, par, external_dist = NULL)

guts_calc_survivalprobs(gobj, par, external_dist = NULL)

guts_report_damage(gobj)

guts_report_sppe(gobj)

guts_report_squares(gobj)

Arguments

C

Numeric vector of concentrations. Vector must contain at least 2 values and be of the same length as Ct.

Ct

Numeric vector of concentration time points. Vector must contain at least 2 values and be of the same length as C. Time points must start at 0, and contain unique values in ascending order.

y

Integer vector (counts) of survivors. Vector must contain at least 2 values and be of the same length as yt. y must not be ascending.

yt

Numeric vector of survivor time points. Vector must contain at least 2 values and be of the same length as y. Time points must start at 0, and contain unique values in ascending order. Survivor information at time points later than the latest concentration time point will be disregarded (with a warning).

dist

Distribution as character, either “lognormal” (default), “loglogistic”, “external” or “delta”.

model

Model as character, either “Proper” (for full model, the default), “IT” (for individual tolerance), or “SD” (for stochastic death).

N

Integer. Thresholds sample length. Must be greater than 2.

M

Integer. Number of time grid points. Must be greater than 1.

gobj

GUTS object. The object to be updated (and used for the calculation).

par

Numeric vector of parameters. See details below.

external_dist

Numeric vector containing the distribution of individual thresholds. Only used if dist = 'external'. See details below.

Details

Functions

Use guts_setup to define (or alter) a GUTS object. Various checks are applied to the data. On success, a GUTS object will be created.

Use guts_calc_loglikelihood to calculate the survival probabilities and the corresponding loglikelihood for a given set of parameters. The function is very fast and can be used in routines for parameter estimation. The function returns the loglikelihood, however it also updates the fields par, S, D, SPPE, squares, zt and LL of the GUTS-object.

guts_calc_survivalprobs is a convenience wrapper that can be used for predictions; it returns the survival probabilities, however it also updates the fields par, S, D, SPPE, squares, zt and LL of the GUTS-object.

guts_report_damage returns a data.frame with time grid points and the damage for each of these. The function reports the damage that was calculated in the previous call to guts_calc_loglikelihood or guts_calc_survivalprobs.

guts_report_squares returns the sum of squares. The function reports the sum of squares that was calculated in the previous call to guts_calc_loglikelihood or guts_calc_survivalprobs.

guts_report_sppe returns the survival-probability prediction error (SPPE). The function reports the SPPE that was calculated in the previous call to guts_calc_loglikelihood or guts_calc_survivalprobs.

Models, Parameters, and Distributions

The GUTS package provides three model types:

The Proper GUTS model requires the following parameters par, while variants IT and SD are based on a reduced subset (as indicated in brackets). Parameter values in par must be ordered as listed here:

For model type “SD” (stochastic death), required parameters par[1:4] are kb, ke, kk and mn, which is the population-wide tolerance threshold. For backwards compatibility this model type can be initiated setting dist = "Delta" and model = "Proper". For model type “IT” (individual tolerance), required parameters par[1:2] are kb, ke, as well as respective distribution parameters (continued from par[3]). Parameter (kk) is set internally to infinity and must not be provided. For model type “Proper”, all parameters are needed. par[1:3] take kb, ke, kk, distribution parameters follow from par[4]).

For model types “Proper” and “IT” individual tolerance thresholds are created internally. Individual tolerances are drawn from the specified distribution dist:

For performance reasons the implemented distributions “lognormal” and “loglogistic” are approximated using importance sampling. The option “external” generally performance well, but might require a larger thresholds sample (i.e. length(external_dist) should be large).

The number of parameters is checked according to dist and model. Wrong number of parameters invoke an error, wrong parameter values (e.g., negative values) invoke a warning, and the loglikelihood is set to -Inf.

Field and Attribute Access

Fields and attributes of an object of class “GUTS” are read-only. To prevent accidental change of fields or attributes, replacement functions were rewritten throwing an error when used. Always use function guts_setup to create objects or modify fields on existing objects. Functions guts_calc_loglikelihood and guts_calc_survivalprobs update an object's fields par (parameters), D (damage), squares (sum of squares), SPPE (survival-probability prediction error), S (survival probabilities) and LL (the loglikelihood).

Value

guts_setup returns a list of class “GUTS” with the following fields:

C

Concentrations.

Ct

Concentration time points.

y

Survivors.

yt

Survivor time points.

dist

Distribution.

model

Model.

N

Sample length.

M

Time grid points.

par

Parameters.

S

Vector of survivor probabilities.

D

Vector of internal damage for each of the M time grid points.

squares

Sum of squares

SPPE

Survival-probability prediction error.

LL

The loglikelihood.

guts_calc_loglikelihood returns the loglikelihood.

guts_calc_survivalprobs returns the survival probabilities.

guts_report_damage returns the damage.

guts_report_squares returns the sum of squares.

guts_report_sppe returns the survival-probability prediction error (SPPE).

Note

The GUTS project web site can be found here: http://guts.r-forge.r-project.org. For questions and discussion, please subscribe to the mailing list there.

Author(s)

Carlo Albert carlo.albert@eawag.ch, Sören Vogel soeren.vogel@posteo.ch, Oliver Jakoby oliver.jakoby@rifcon.de, Alexander Singer alexander.singer@rifcon.de and Dirk Nickisch dirk.nickisch@rifcon.de

Maintainer: Oliver Jakoby oliver.jakoby@rifcon.de

References

Albert, C., Vogel, S., and Ashauer, R. (2016). Computationally efficient implementation of a novel algorithm for the General Unified Threshold Model of Survival (GUTS). PLOS Computational Biology, 12(6), e1004978. doi: 10.1371/journal.pcbi.1004978.

Jager, T., Albert, C., Preuss, T., and Ashauer, R. (2011). General Unified Threshold Model of Survival – a toxicokinetic toxicodynamic framework for ecotoxicology. Environmental Science \& Technology, 45(7), 2529–2540, doi: 10.1021/es103092a.

Ashauer, R., Albert, C., Augustine, S., Cedergreen, N., Charles, S., Ducrot, V., Focks, A., Gabsi, F., Gergs, A., Goussen, B., Jager, T., Kramer, N.I., Nyman, A.-M., Poulsen, V., Reichenberger, S., Schäfer, R.B., Van den Brink, P.J., Veltman, K., Vogel, S., Zimmer, E.I., Preuss, T.G. (2016) Modelling survival: exposure pattern, species sensitivity and uncertainty. Scientific Reports, 6, 1.

Jager, T., Ashauer, R. (2018). Modelling survival under chemical stress. A comprehensive guide to the GUTS framework. Leanpub: https://leanpub.com/guts_book, http://www.debtox.info/book_guts.html

EFSA PPR Panel (EFSA Panel on Plant Protection Products and their Residues), Ockleford, C., Adriaanse, P., Berny, P., Brock, T., Duquesne, S., Grilli, S., Hernandez-Jerez, A.F., Bennekou, S.H., Klein, M., Kuhl, T., Laskowski, R., Machera, K., Pelkonen, O., Pieper, S., Smith, R.H., Stemmer, M., Sundh, I., Tiktak, A., Topping, C.J., Wolterink, G., Cedergreen, N., Charles, S., Focks, A., Reed, M., Arena, M., Ippolito, A., Byers, H. and Teodorovic, I. (2018). Scientific Opinion on the state of the art of Toxicokinetic/Toxicodynamic (TKTD) effect models for regulatory risk assessment of pesticides for aquatic organisms. EFSA Journal, 16(8):5377, 188 pp. https://doi.org/10.2903/j.efsa.2018.5377

See Also

diazinon, GUTS-package and the package vignettes for examples on how to calibrate and project GUTS-models.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
data(diazinon)

# create GUTS object to calculate the Proper model 
#  using a log-normal distribution of tolerance thresholds  
gts.lognormal <- guts_setup(
  C = diazinon$C1, Ct = diazinon$Ct1,
  y = diazinon$y1, yt = diazinon$yt1, 
  dist = "lognormal", model = "Proper")

# calculate likelihood of Proper model using log-normal distribution
guts_calc_loglikelihood(  
  gts.lognormal, 
  c(0.051, 0.126, 1.618, 19.099, 6.495))
gts.lognormal  # show GUTS object

# repeating calculation above 
#  with threshold values from an external log-normal distribution. 
#  Note, we need to account for the different parametrisations
#  used in the GUTS-package and in rlnorm
sigma2 <- log( 1 + 6.495^2 / 19.099^2)
mu <- log(19.099) - 0.5 * sigma2
lognormal.thresholds <- rlnorm(1000, meanlog = mu, sdlog = sqrt(sigma2))
gts.external <- guts_setup(
  C = diazinon$C1, Ct = diazinon$Ct1,
  y = diazinon$y1, yt = diazinon$yt1, 
  dist = "external", model = "Proper")
guts_calc_loglikelihood(
  gts.external, 
  c(0.051, 0.126, 1.618), external_dist = lognormal.thresholds) 
# -> Results using external and internal distributions are comparable

# create GUTS object to calculate the Proper model 
#  using a log-logistic distribution of tolerance thresholds
gts.loglogistic <- guts_setup(
  C = diazinon$C1, Ct = diazinon$Ct1,
  y = diazinon$y1, yt = diazinon$yt1, 
  dist = "loglogistic", model = "Proper")
guts_calc_survivalprobs( # returning survival probabilities
  gts.loglogistic, 
  c(0.01, 0.2, 0.3, 3, 2)) 

str(guts_report_damage(gts.loglogistic)) # returning damage

# calculate survival probabilities with IT model 
#  using a log-logistic distribution of tolerance thresholds
guts_calc_survivalprobs(
  guts_setup(
  C = diazinon$C1, Ct = diazinon$Ct1,
  y = diazinon$y1, yt = diazinon$yt1, 
  dist = "loglogistic", model = "IT"), 
  c(0.01, 0.2, 3, 2)) 

# calculate survival probabilities with an SD model with a fixed tolerance threshold
guts_calc_survivalprobs(
  guts_setup(
  C = diazinon$C1, Ct = diazinon$Ct1,
  y = diazinon$y1, yt = diazinon$yt1, 
  dist = "loglogistic", model = "SD"), 
  c(0.01, 0.2, 0.3, 3))


## Not run: guts_calc_survivalprobs(gts.external, rep(.5, 3)) 
# Warning and no result, because no external distribution was specified

## Not run: guts_calc_survivalprobs(gts.loglogistic , 1:4 ) # Error.

## Not run: gts.loglogistic[["C"]] <- 1:3 # Error.

GUTS documentation built on July 5, 2019, 5:03 p.m.