jranke / mkin
1
#' Single First-Order kinetics
2
#'
3
#' Function describing exponential decline from a defined starting value.
4
#'
5
#' @family parent solutions
6
#' @param t Time.
7
#' @param parent_0 Starting value for the response variable at time zero.
8
#' @param k Kinetic rate constant.
9
#' @return The value of the response variable at time \code{t}.
10
#' @references 
11
#' FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
12
#'   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
13
#'   EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
14
#'   EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
15
#'   \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
16
#' FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence
17
#'   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
18
#'   EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
19
#'   Version 1.1, 18 December 2014
20
#'   \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
21
#' @examples
22
#'
23
#'   \dontrun{plot(function(x) SFO.solution(x, 100, 3), 0, 2)}
24
#'
25
#' @export
26
SFO.solution <- function(t, parent_0, k)
27
{
28 1
	parent = parent_0 * exp(-k * t)
29
}
30

31
#' First-Order Multi-Compartment kinetics
32
#' 
33
#' Function describing exponential decline from a defined starting value, with
34
#' a decreasing rate constant.
35
#' 
36
#' The form given here differs slightly from the original reference by
37
#' Gustafson and Holden (1990). The parameter \code{beta} corresponds to 1/beta
38
#' in the original equation.
39
#' 
40
#' @family parent solutions
41
#' @inherit SFO.solution 
42
#' @param alpha Shape parameter determined by coefficient of variation of rate
43
#'   constant values.
44
#' @param beta Location parameter.
45
#' @note The solution of the FOMC kinetic model reduces to the
46
#'   \code{\link{SFO.solution}} for large values of \code{alpha} and
47
#'   \code{beta} with \eqn{k = \frac{\beta}{\alpha}}{k = beta/alpha}.
48
#' @references 
49
#' FOCUS (2006) \dQuote{Guidance Document on Estimating Persistence
50
#'   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
51
#'   EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
52
#'   EC Document Reference Sanco/10058/2005 version 2.0, 434 pp,
53
#'   \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
54
#' 
55
#' FOCUS (2014) \dQuote{Generic guidance for Estimating Persistence
56
#'   and Degradation Kinetics from Environmental Fate Studies on Pesticides in
57
#'   EU Registration} Report of the FOCUS Work Group on Degradation Kinetics,
58
#'   Version 1.1, 18 December 2014
59
#'   \url{http://esdac.jrc.ec.europa.eu/projects/degradation-kinetics}
60
#'
61
#'   Gustafson DI and Holden LR (1990) Nonlinear pesticide dissipation in soil:
62
#'   A new model based on spatial variability. \emph{Environmental Science and
63
#'   Technology} \bold{24}, 1032-1038
64
#' @examples
65
#' 
66
#'   plot(function(x) FOMC.solution(x, 100, 10, 2), 0, 2, ylim = c(0, 100))
67
#' 
68
#' @export
69
FOMC.solution <- function(t, parent_0, alpha, beta)
70
{
71 1
	parent = parent_0 / (t/beta + 1)^alpha
72
}
73

74
#' Indeterminate order rate equation kinetics
75
#' 
76
#' Function describing exponential decline from a defined starting value, with
77
#' a concentration dependent rate constant.
78
#' 
79
#' @family parent solutions
80
#' @inherit SFO.solution 
81
#' @param k__iore Rate constant. Note that this depends on the concentration
82
#'   units used.
83
#' @param N Exponent describing the nonlinearity of the rate equation
84
#' @note The solution of the IORE kinetic model reduces to the
85
#'   \code{\link{SFO.solution}} if N = 1.  The parameters of the IORE model can
86
#'   be transformed to equivalent parameters of the FOMC mode - see the NAFTA
87
#'   guidance for details.
88
#' @references NAFTA Technical Working Group on Pesticides (not dated) Guidance
89
#'   for Evaluating and Calculating Degradation Kinetics in Environmental Media
90
#' @examples
91
#' 
92
#'   plot(function(x) IORE.solution(x, 100, 0.2, 1.3), 0, 2, ylim = c(0, 100))
93
#'   \dontrun{
94
#'     fit.fomc <- mkinfit("FOMC", FOCUS_2006_C, quiet = TRUE)
95
#'     fit.iore <- mkinfit("IORE", FOCUS_2006_C, quiet = TRUE)
96
#'     fit.iore.deS <- mkinfit("IORE", FOCUS_2006_C, solution_type = "deSolve", quiet = TRUE)
97
#' 
98
#'     print(data.frame(fit.fomc$par, fit.iore$par, fit.iore.deS$par, 
99
#'                      row.names = paste("model par", 1:4)))
100
#'     print(rbind(fomc = endpoints(fit.fomc)$distimes, iore = endpoints(fit.iore)$distimes, 
101
#'                 iore.deS = endpoints(fit.iore)$distimes))
102
#'   }
103
#' 
104
#' @export
105
IORE.solution <- function(t, parent_0, k__iore, N)
106
{
107 1
	parent = (parent_0^(1 - N) - (1 - N) * k__iore * t)^(1/(1 - N))
108
}
109

110
#' Double First-Order in Parallel kinetics
111
#' 
112
#' Function describing decline from a defined starting value using the sum of
113
#' two exponential decline functions.
114
#' 
115
#' @family parent solutions
116
#' @inherit SFO.solution 
117
#' @param t Time.
118
#' @param k1 First kinetic constant.
119
#' @param k2 Second kinetic constant.
120
#' @param g Fraction of the starting value declining according to the first
121
#'   kinetic constant.
122
#' @examples
123
#' 
124
#'   plot(function(x) DFOP.solution(x, 100, 5, 0.5, 0.3), 0, 4, ylim = c(0,100))
125
#' 
126
#' @export
127
DFOP.solution <- function(t, parent_0, k1, k2, g)
128
{
129 1
	parent = g * parent_0 * exp(-k1 * t) +
130 1
		 (1 - g) * parent_0 * exp(-k2 * t)
131
}
132

133
#' Hockey-Stick kinetics
134
#' 
135
#' Function describing two exponential decline functions with a break point
136
#' between them.
137
#' 
138
#' @family parent solutions
139
#' @inherit DFOP.solution 
140
#' @param tb Break point. Before this time, exponential decline according to
141
#'   \code{k1} is calculated, after this time, exponential decline proceeds
142
#'   according to \code{k2}.
143
#' @examples
144
#' 
145
#'   plot(function(x) HS.solution(x, 100, 2, 0.3, 0.5), 0, 2, ylim=c(0,100))
146
#' 
147
#' @export
148
HS.solution <- function(t, parent_0, k1, k2, tb)
149
{
150 1
	parent = ifelse(t <= tb, 
151 1
		parent_0 * exp(-k1 * t),
152 1
		parent_0 * exp(-k1 * tb) * exp(-k2 * (t - tb)))
153
}
154

155
#' Single First-Order Reversible Binding kinetics
156
#' 
157
#' Function describing the solution of the differential equations describing
158
#' the kinetic model with first-order terms for a two-way transfer from a free
159
#' to a bound fraction, and a first-order degradation term for the free
160
#' fraction.  The initial condition is a defined amount in the free fraction
161
#' and no substance in the bound fraction.
162
#' 
163
#' @family parent solutions
164
#' @inherit SFO.solution 
165
#' @param k_12 Kinetic constant describing transfer from free to bound.
166
#' @param k_21 Kinetic constant describing transfer from bound to free.
167
#' @param k_1output Kinetic constant describing degradation of the free
168
#'   fraction.
169
#' @return The value of the response variable, which is the sum of free and
170
#'   bound fractions at time \code{t}.
171
#' @examples
172
#' 
173
#'   \dontrun{plot(function(x) SFORB.solution(x, 100, 0.5, 2, 3), 0, 2)}
174
#' 
175
#' @export
176
SFORB.solution = function(t, parent_0, k_12, k_21, k_1output) {
177 1
  sqrt_exp = sqrt(1/4 * (k_12 + k_21 + k_1output)^2 + k_12 * k_21 - (k_12 + k_1output) * k_21)
178 1
  b1 = 0.5 * (k_12 + k_21 + k_1output) + sqrt_exp
179 1
  b2 = 0.5 * (k_12 + k_21 + k_1output) - sqrt_exp
180

181 1
  parent = parent_0 *
182 1
        (((k_12 + k_21 - b1)/(b2 - b1)) * exp(-b1 * t) +
183 1
        ((k_12 + k_21 - b2)/(b1 - b2)) * exp(-b2 * t))
184
}
185

186
#' Logistic kinetics
187
#' 
188
#' Function describing exponential decline from a defined starting value, with
189
#' an increasing rate constant, supposedly caused by microbial growth
190
#' 
191
#' @family parent solutions
192
#' @inherit SFO.solution 
193
#' @param kmax Maximum rate constant.
194
#' @param k0 Minimum rate constant effective at time zero.
195
#' @param r Growth rate of the increase in the rate constant.
196
#' @note The solution of the logistic model reduces to the
197
#'   \code{\link{SFO.solution}} if \code{k0} is equal to \code{kmax}.
198
#' @examples
199
#' 
200
#'   # Reproduce the plot on page 57 of FOCUS (2014)
201
#'   plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.2),
202
#'        from = 0, to = 100, ylim = c(0, 100),
203
#'        xlab = "Time", ylab = "Residue")
204
#'   plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.4),
205
#'        from = 0, to = 100, add = TRUE, lty = 2, col = 2)
206
#'   plot(function(x) logistic.solution(x, 100, 0.08, 0.0001, 0.8),
207
#'        from = 0, to = 100, add = TRUE, lty = 3, col = 3)
208
#'   plot(function(x) logistic.solution(x, 100, 0.08, 0.001, 0.2),
209
#'        from = 0, to = 100, add = TRUE, lty = 4, col = 4)
210
#'   plot(function(x) logistic.solution(x, 100, 0.08, 0.08, 0.2),
211
#'        from = 0, to = 100, add = TRUE, lty = 5, col = 5)
212
#'   legend("topright", inset = 0.05,
213
#'          legend = paste0("k0 = ", c(0.0001, 0.0001, 0.0001, 0.001, 0.08),
214
#'                          ", r = ", c(0.2, 0.4, 0.8, 0.2, 0.2)),
215
#'          lty = 1:5, col = 1:5)
216
#' 
217
#'   # Fit with synthetic data
218
#'   logistic <- mkinmod(parent = mkinsub("logistic"))
219
#' 
220
#'   sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120)
221
#'   parms_logistic <- c(kmax = 0.08, k0 = 0.0001, r = 0.2)
222
#'   d_logistic <- mkinpredict(logistic,
223
#'     parms_logistic, c(parent = 100),
224
#'     sampling_times)
225
#'   d_2_1 <- add_err(d_logistic,
226
#'     sdfunc = function(x) sigma_twocomp(x, 0.5, 0.07),
227
#'     n = 1, reps = 2, digits = 5, LOD = 0.1, seed = 123456)[[1]]
228
#' 
229
#'   m <- mkinfit("logistic", d_2_1, quiet = TRUE)
230
#'   plot_sep(m)
231
#'   summary(m)$bpar
232
#'   endpoints(m)$distimes
233
#' 
234
#' @export
235
logistic.solution <- function(t, parent_0, kmax, k0, r)
236
{
237 1
	parent = parent_0 * (kmax / (kmax - k0 + k0 * exp (r * t))) ^(kmax/r)
238
}

Read our documentation on viewing source code .

Loading