The Algorithm

Before we present the algorithm, we give a brief review of the GUTS model (see [4], for more explanation). The time-dependent stressor, C(t), is assumed to cause a time-dependent damage, D(t), which is described by the linear differential equation (1) Parameter k_e quantifies the slowest process that leads to the recovery of the organism, and we will henceforth refer to it as the dominant rate constant. The damage D(t) is the same, for all individuals. However, the individuals are assumed to have different thresholds, beyond which the damage increases their probability to die. Thus, the model combines two sources of stochasticity, at the individual and at the population level. At the individual level, death is considered a stochastic event, whose probability increases linearly with the damage, once it exceeds a certain threshold. At the population level, this threshold is assumed to vary stochastically over the whole population.

The hazard rate, h_z(t), of an individual with threshold z is determined by the formula (2) where k_k is called killing rate and h_b is the background mortality rate. The hazard rate, in turn, determines the individual’s probability to survive until time t, S_z(t), via the linear differential equation (3) Finally, each individual is assumed to draw its z from a distribution, f_θ(z), on the positive real axis. Hence, the parameter vector of the model reads as θ = (h_b, k_e, k_k, …), where the additional arguments are supposed to determine the distribution f_θ(z).

Typically, f_θ(z) is a member of a two-parameter family of distributions, such as the lognormal family. In these cases, GUTS has four toxicodynamic parameters, k_e, k_k, as well as the mean and the standard deviation determining the lognormal distribution. These are GUTS proper models. GUTS-SD and GUTS-IT are limiting cases of GUTS proper. In the first case, the standard deviation is zero, which means that all individuals have the same threshold given by the mean of the distribution. In the latter case, k_k is infinite, which means that individuals die immediately once their individual threshold is exceeded. Note that eq (2) may be viewed as a special case of Aalens additive model [28].

Combining eqs (2) and (3), we find that the probability, for an arbitrarily chosen member of the population, to survive until time t is given by the formula (4)

Let y = (y₀, y₁, …, y_n) denote a time series of survivors, counted at times (t₀ = 0, t₁, …, t_n), and set y_n+1 = 0. Then, the logarithm of the likelihood, f(y | θ), of the model output y given the parameters θ is, up to θ-independent terms, given by the formula (5) where we have set S_{θ, i} = S_θ(t_i) and S_{θ, n+1} = 0. The index n+1 refers to the time-point at infinity, where the survival probability is zero.

The calculation of the log-likelihood requires two nested numerical integrations (see eq (4)), and, therefore, requires introducing two large numbers, N and M. The former counts the number of sample or discretisation points on the threshold axis and the latter counts the number of discretisation points on the time axis. Our algorithm is of the order . It is based on the approximation (6) for an ordered sample z₁ < … < z_N from f_θ(z), and with D_l = D(τ_l) on a grid τ₀ < … < τ_M−1. The inner sum in the second line is restricted to all D_l, for which τ_l < t_i, and we have set Δτ = t_n/M. Furthermore, (7) and (8) where ♯ indicates counting the number of elements in the set, for 1 ≤ j ≤ N (set z_N+1 = ∞).

The algorithm for the calculation of eq (5) reads as follows:

1. Step 1: Draw N thresholds from f_θ(z) and order them z₁ < ⋯ < z_N.
2. Step 2: Refine the grid t₀ < … < t_n to a fine grid τ₀ < ⋯ < τ_M−1.
3. Step 3: Set i = 0.
4. Step 4: Solve eq (1), for t_i ≤ τ_l ≤ t_i+1, using equation (9) for s_k ≤ τ_l ≤ s_k+1. Here, we apply a linear interpolation, for C(t), between concentrations C_k, measured at time points s_k.
5. Step 5: Update eqs (7) and (8), for 1 ≤ j ≤ N. (This can be done in time , for each D_l).
6. Step 6: Calculate S_i using the recursion: (10) (11) (12) for j = N − 1, …, 1 and with S_{i, N} = e^{−k_k Δτ(E_N − F_N z_N)} and F_N = f_N, E_N = e_N. Then, (13)
7. Step 7: Increment i and go to step 4.
8. Step 8: Calculate the log-likelihood function according to eq (5).

Depending on the threshold distribution, the above algorithm can be made more efficient through importance sampling. That is, instead of sampling from f_θ(z) we sample from distribution g_θ(z) and correct with weights: (14) The associated algorithm is then the same as above, except that we generate an ordered sample from g_θ(z) and replace expression by Furthermore, the vector of survival probabilities, S_i, has to be normalised through element-wise division by the first unnormalised element of the vector.

If f_θ(z) is the lognormal distribution, we recommend using a log-uniform distribution covering the highest probability region of f_θ(z), and replacing the sample by a grid. More precisely, we set , where {x_j} describes an equidistant grid on the interval [μ − 4σ, μ+4σ], where (15) with m and s², respectively, the mean and variance of the lognormal distribution. The weights become, up to an irrelevant θ-independent term, (16)

Implementation in the R Package GUTS

The GUTS algorithm is implemented in the R package GUTS [29, 30], current version 1.0.0). R [31] is an open source software environment for statistical computing that provides a wide range of procedures for data manipulation, data analysis, simulation, modelling and producing graphics. R packages are extensions contributed by members of the R community to add functionality to the R environment.

The R package GUTS is such an extension, and it contains a setup function and functions to calculate the survival probabilities and the associated logarithm of the likelihood, respectively. In order to achieve high speed, the actual engine for the calculation of the survival probabilities and the associated logarithm of the likelihood is written in C++ and exposed to R through the deployment of Rcpp [32, 33]. The engine cannot be called directly but through the use of two wrapper functions. The function for the calculation of the log-likelihood is typically used in a parameter estimation routine, while the function for the survival probabilities can be used to make predictions. Both functions update the GUTS object directly, but also return the logarithm of the likelihood or the vector of survival probabilities, respectively. The help file of the package contains a detailed description of the package functions, their arguments and use (R command help(“GUTS”)).

The R package GUTS allows for the realisation of two models, the full model (GUTS Proper) and the individual tolerance model (GUTS-IT). In addition, the stochastic death model (GUTS-SD) can be achieved through the use of the delta distribution with model GUTS Proper. If the thresholds are sampled from the lognormal distribution (the default) and the full model (GUTS Proper, also default) is applied, 5 parameters are required:

• hb: background mortality rate
• ke: dominant rate constant
• kk: killing rate
• mn: mean of the threshold distribution
• sd: standard deviation of the threshold distribution

For the delta distribution, no standard deviation must be provided, and for the model GUTS-IT, the killing rate must be omitted. The number of parameters is checked according to the distribution and model. A wrong number of parameters invokes an error. However, improper parameter values (e.g., negative values) invoke a warning resulting in the vector of parameters and the vector of survival probabilities being set to NA, and the logarithm of the likelihood being set to -Inf.

For testing and demonstration purposes, the package also provides a data set, “diazinon”. Pulsed toxicity tests with the freshwater crustacean Gammarus pulex and diazinon, an organophosphate insecticide, were carried out to measure survival through time under repeated pulsed exposure with variable recovery phases between pulses. Exposure concentrations were measured frequently and survival was observed daily. The dataset contains the results from three different experiments (exposure scenarios), where each experiment started off with 70 alive individuals. For more details see [34].

The R package GUTS is (like R) licensed under GPL-2 and freely available from CRAN (http://CRAN.R-project.org, users should employ the package installation routines available in R). The package also includes a manual page with detailed information about the functions and their arguments.

Read Data and Create GUTS Objects

After installing and loading all required packages, we read in data from experiments. For convenience, it is best to prepare a well-formatted text file and then use our wrapper function ga_read_list(). If, for instance, the data from [34] should be read in, the file must be formatted as follows:

The first line shows a comment, which is ignored when reading in. Each data line starts with a variable name (e.g., C1 for the first concentration vector) followed by a colon, the actual data separated by commas, and each data vector terminated by a newline. The C and y vectors denote, respectively, exposure concentrations [nmol/l] and survival counts. The Ct and yt vectors denote the time points at which these vectors are measured [day]. As our algorithm assumes a linear interpolation between concentrations, the values have been chosen such that pulses of approximately rectangular shape are achieved.

Having such a plain text file created in the working directory under the file name, say, Data_Gp_Diazinon.txt, it can then be read in:

However, for testing and demonstration purposes, the diazinon data is included in the R package GUTS. We can load this data directly and create a list of 3 GUTS objects:

Note, that all other arguments of the setup function (guts_setup()) already default to modelling GUTS-Proper (i.e., dist = “lognormal”, model = “Proper”, N = 1000, M = 10000) and are therefore omitted. However, for modelling GUTS-SD, set dist = “delta” and model = “Proper”, and for modelling GUTS-IT, set dist = “lognormal” and model = “IT”. In order to inspect the content of the first GUTS object in the list, use the print command, print(guts_objects[[1]]).

Bayesian Parameter Estimation

The parameter estimation is achieved through the use of an optimisation routine to find good starting parameters, and the use of a MCMC routine, for sampling the parameter posterior distribution. We define the evaluation function logposterior(), which is the sum of the log-likelihood and the log-prior:

We have chosen uniform priors, for all parameters, with lower bounds equal to zero. The upper bounds are assumed sufficiently large so that they do not affect the posterior significantly. As the posteriors of all parameters except k_k decay sufficiently fast, no upper bounds need to be specified, for those parameters. The posterior of parameter k_k, however, seems to exhibit a fat tail, which occasionally leads to divergent Markov chains. For this parameter, we specify a prior upper bound k_k < 30l/(day nmol) that is large enough to be practically indistinguishable from the IT regime k_k = ∞.

The function logposterior() takes a vector of parameters as its only argument. If the parameter vector lies outside the prior range, logposterior() returns -Inf; otherwise it applies a vector-wise calculation of the logarithm of the likelihood to the GUTS objects (sapply()) and returns the sum.

To find good starting parameters, we use an R implementation of the “Hooke-Jeeves derivative-free minimisation algorithm”. The optimiser hjkb() is included in the package dfoptim [35]. We then define a start vector as well as its lower and upper bounds needed during the optimisation.

Warnings invoked by the GUTS package functions can be inspected using the command warnings() (for their meaning, see the help file and section Implementation in the R Package GUTS). However, these warnings do not affect the optimisation and can, therefore, be safely ignored.

The result of the optimisation routine is inspected using the print function (for an in-depth description of the output consult the manual page of hjkb()):

Note that choosing reasonable parameter bounds can hardly be automatised and thus relies on the expert knowledge about common parameters, for the respective types of data and experiment. If expert knowledge suggest different parameters and bounds, the vectors above need to be adjusted [26].

The posterior parameter distribution is sampled using the robust adaptive Metropolis sampler implemented in the R package adaptMCMC [36] with the parameters from the optimisation serving as starting values. The function MCMC() automatically adapts the covariance of the jump distribution to achieve a user-defined acceptance rate (here: 0.4). As a starting value, for the covariance of the jump distribution, we simply use a diagonal one with 10% of the initial parameter values as standard deviations. In order to prevent degeneracy of the matrix (in case the optimiser returns zero, for certain parameters), the matrix is altered by adding a small positive number to the diagonal. Note that, although the R package GUTS is very fast, the MCMC may take some minutes depending on the number of iterations chosen (argument n of the function MCMC()) and the hardware used (on our testing MacBook Pro with a 4 core Intel i7 processor 50,000 iterations took about 3 minutes). Like in the optimisation routine, warnings can occur and can be ignored (see above).

Visualisation of the Posterior Distribution

After the MCMC has finished without errors, it is necessary to inspect the chains and check whether they have converged. Automatised checks are available (e.g., through using CODA [37]), however, here we create a plot from the chains of the parameters’ posterior marginals and check the chains visually (see Fig 1).

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 1. Chains of the parameters’ posterior marginals computed by the MCMC.

https://doi.org/10.1371/journal.pcbi.1004978.g001

After cutting off the first 10,000 sample points, the chains show a reasonable mixing and no signs of burn-in or the adaptation phase of the algorithm. We have chosen the function MCMC() from package adaptMCMC because it is largely self-tuning and therefore easy to use. An adaptation phase of 20,000 sample points seems to be sufficient in most cases. Nevertheless, it is important to keep in mind that MCMC() calls a stochastic algorithm, which may fail to adapt, even for the data set we are using. If that happens, running the algorithm a second time usually suffices. If not, the adaptation phase might have to be enlarged and the chain might have to be run for a longer time.

Next, we create a correlation plot, for the posterior parameter sample, computed by the MCMC. The parameters for our example co-vary as shown in Fig 2.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 2. Correlations between the parameter posterior samples computed by the MCMC.

https://doi.org/10.1371/journal.pcbi.1004978.g002

The strongest correlation is observed between the threshold mean (mn) and the dominant rate constant (k_e), which can be understood from eqs (1) and (2). Strong parameter correlations could be viewed as indicators of over-parametrised models, however the equations of GUTS represent our understanding of the processes determining survival under stress. As such the model parameters have a mechanistic interpretation, which would be partially lost if reducing the model. Furthermore, reducing GUTS to fewer parameters would introduce additional strong assumptions and so GUTS would loose its generality. For example, disposing of the threshold parameter would imply the assumption that any infinitely small dose of the stressor will result in an increased hazard rate (see also [4]). An important insight from Fig 2 is that survival predictions must account for the correlation between parameters to properly account for parametric uncertainty.

Quantification of Parameter Uncertainty

To compute the uncertainty of each of the parameters, we calculate adequate quantiles from the posterior samples. Together with the maximum of the posterior distribution, these quantiles are then tabulated.

To inspect the distribution and the uncertainty visually, we plot the densities of each of the parameters. Fig 3 shows the densities, and each plot contains a horizontal line indicating the uncertainty quantiles (the median is always added).

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 3. Densities and uncertainty (quantiles) of the parameter posteriors.

https://doi.org/10.1371/journal.pcbi.1004978.g003

Probabilistic Prediction and Validating the Model With New Data

After calibrating our model with real data, we use it for probabilistic predictions. We demonstrate how to make probabilistic predictions (without survival data) and how to validate these predictions against measured survival data. In both cases we use fictional (“fake”) data, for demonstration purposes.

The data must contain concentrations and concentration time points, but also the time points at which we want to make predictions. Furthermore, we need to specify the initial number of individuals (100, in our example). This number is set in the first element of the vector of survivor counts (y). Unless we have validation data, the remaining values are not needed and set to an arbitrary value (0, in our example).

We tabulate the predictions and save the result in the R list object tab_pred. We use the command head() to print the first 6 lines of the first table, however, all tables can be printed using print(tab_pred).

Finally, we create a prediction plot (see Fig 4). The plot shows the medians as well as the quantiles of the predicted survivor counts.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 4. Predictions for 2 fictional (“fake”) experimental setups.

https://doi.org/10.1371/journal.pcbi.1004978.g004

The prediction plots show the 95% probability bands and the medians, for the number of deaths that are predicted to occur in each observation window. If measured survivor data is present, it is also possible to add this information to the tables and plots, for validation. We modify our first fictional data set from above and add some (also fictional) survivor data. The tabulation now contains an additional column (“measured”), and the measured data (fictional data, in our example) is added to the plot as well (see Fig 5). Note that each single table can also be saved to text files using the command write.csv().

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 5. Comparison of a model forecast with fictional (“fake”) data.

https://doi.org/10.1371/journal.pcbi.1004978.g005

Example Code and Further Development

The complete code used throughout the presentation here is available with the paper (see S1 Script and S1 Data). We believe that the conciseness of our code and the application of our self-created wrapper functions make the procedures very easy to understand and to reproduce. However, with more expertise in R, users can easily alter our code and produce their own output. For instance, the plotting routines provided by the R package ggplot2 [38] are very powerful and allow for rich-featured ready-to-publish graphics. We also encourage users to try out different optimisation and inference routines.

Future development will focus on the implementation of more distributions as well as further performance improvements. Users of our R package GUTS are encouraged to provide ideas, feedback or feature requests to the authors and the R GUTS user community, or to contribute actively to further development as a co-developer. The best way to communicate is via the mailing list of the package (guts-users@lists.r-forge.r-project.org). The development home page of our R package GUTS can be found on R-Forge (https://r-forge.r-project.org/projects/guts/).