Debian Codegraph @

man/plot.deSolve.Rd

raw
1 \name{plot.deSolve}
2 \alias{plot.deSolve}
3 \alias{plot.1D}
4 \alias{matplot.0D}
5 \alias{matplot.deSolve}
6 \alias{matplot.1D}
7 %\alias{matplot,deSolve-method}
8 \alias{hist.deSolve}
9 \alias{image.deSolve}
10 \alias{subset.deSolve}
11 \title{
12 Plot, Image and Histogram Method for deSolve Objects
13 }
14 \description{
15 Plot the output of numeric integration routines.
16 }
17 \usage{
18 \method{plot}{deSolve}(x, \dots, select = NULL, which = select, ask = NULL,
19 obs = NULL, obspar = list(), subset = NULL)
20 %% thpe: since 1.14 not anymore exported
21 %\method{matplot}{deSolve}(x, \dots, select = NULL, which = select,
22 % obs = NULL, obspar = list(), subset = NULL,
23 % legend = list(x = "topright"))
24 \method{hist}{deSolve}(x, select = 1:(ncol(x)-1), which = select, ask = NULL,
25 subset = NULL, \dots)
26 \method{image}{deSolve}(x, select = NULL, which = select, ask = NULL,
27 add.contour = FALSE, grid = NULL,
28 method = "image", legend = FALSE, subset = NULL, \dots)
29 \method{subset}{deSolve}(x, subset = NULL, select = NULL,
30 which = select, arr = FALSE, \dots)
31
32 plot.1D (x, \dots, select = NULL, which = select, ask = NULL,
33 obs = NULL, obspar = list(), grid = NULL,
34 xyswap = FALSE, delay = 0, vertical = FALSE, subset = NULL)
35
36 matplot.0D(x, \dots, select = NULL, which = select,
37 obs = NULL, obspar = list(), subset = NULL,
38 legend = list(x = "topright"))
39
40 matplot.1D(x, select = NULL, which = select, ask = NULL,
41 obs = NULL, obspar = list(), grid = NULL,
42 xyswap = FALSE, vertical = FALSE, subset = NULL, \dots)
43 }
44 \arguments{
45 \item{x }{an object of class \code{deSolve}, as returned by the
46 integrators, and to be plotted.
47
48 For \code{plot.deSolve}, it is allowed to pass several objects of class
49 \code{deSolve} after \code{x} (unnamed) - see second example.
50 }
51 \item{which }{the name(s) or the index to the variables that should be
52 plotted or selected. Default = all variables, except \code{time}.
53 For use with \code{matplot.0D} and \code{matplot.1D}, \code{which} or \code{select} can be a list,
54 with vectors, each referring to a separate y-axis.
55 }
56 \item{select }{which variable/columns to be selected. This is added for
57 consistency with the R-function \code{subset}.
58 }
59 \item{subset }{either a logical expression indicating elements or rows to keep in
60 \code{select}, or a vector of integers denoting the indices of the elements
61 over which to loop. Missing values are taken as \code{FALSE}
62 }
63 \item{ask }{logical; if \code{TRUE}, the user is \emph{ask}ed before
64 each plot, if \code{NULL} the user is only asked if more than one
65 page of plots is necessary and the current graphics device is set
66 interactive, see \code{\link{par}(ask)} and
67 \code{\link{dev.interactive}}.}
68 \item{add.contour }{if \code{TRUE}, will add contours to the image plot.}
69
70 \item{method }{the name of the plotting method to use, one of "image",
71 "filled.contour", "persp", "contour".}
72
73 \item{grid }{only for \code{image} plots and for \code{plot.1D}:
74 the 1-D grid as a vector (for output generated with \code{ode.1D}),
75 or the x- and y-grid, as a \code{list} (for output generated with
76 \code{ode.2D}).}
77
78 \item{xyswap }{if \code{TRUE}, then x-and y-values are swapped and the
79 y-axis is from top to bottom. Useful for drawing vertical profiles.}
80
81 \item{vertical }{if \code{TRUE}, then 1. x-and y-values are swapped, the
82 y-axis is from top to bottom, the x-axis is on top, margin 3 and the
83 main title gets the value of the x-axis.
84 Useful for drawing vertical profiles; see example 2.}
85
86 \item{delay }{adds a delay (in milliseconds) between consecutive plots
87 of \code{plot.1D} to enable animations.}
88
89 \item{obs }{a \code{data.frame} or \code{matrix} with "observed data" that
90 will be added as \code{points} to the plots. \code{obs} can also be a
91 \code{list} with multiple data.frames and/or matrices containing
92 observed data.
93
94 By default the first column of an observed data set should contain
95 the \code{time}-variable. The other columns contain the observed values
96 and they should have names that are known in \code{x}.
97
98 If the first column of \code{obs} consists of factors or characters (strings),
99 then it is assumed that the data are presented in long (database) format,
100 where the first three columns contain (name, time, value).
101
102 If \code{obs} is not \code{NULL} and \code{which} is \code{NULL},
103 then the variables, common to both \code{obs} and \code{x} will be plotted.
104 }
105 \item{obspar }{additional graphics arguments passed to \code{points}, for
106 plotting the observed data. If \code{obs} is a \code{list} containing multiple
107 observed data sets, then the graphics arguments can be a vector
108 or a list (e.g. for \code{xlim}, \code{ylim}), specifying each data set
109 separately.
110 }
111 \item{legend }{if \code{TRUE}, a color legend will be drawn on the right
112 of each image.
113 For use with \code{matplot.0D} and \code{matplot.1D}:
114 a \code{list} with arguments passed to R-function \link{legend}.
115 }
116 \item{arr }{if \code{TRUE}, and the output is from a 2-D or 3-D model,
117 an array will be returned with dimension =
118 c(dimension of selected variable, nrow(x)).
119 When \code{arr=TRUE} then only one variable can be selected.
120 When the output is from a 0-D or 1-D model, then this argument is ignored.
121 }
122 \item{\dots}{additional arguments.
123
124 The graphical arguments are passed to
125 \code{\link{plot.default}}, \code{\link{image}} or \code{\link{hist}}
126
127 For \code{plot.deSolve}, and \code{plot.1D}, the dots may contain other objects of class
128 \code{deSolve}, as returned by the integrators, and
129 to be plotted on the same graphs as \code{x} - see second example.
130 In this case, \code{x} and and these other objects should be compatible,
131 i.e. the column names should be the same.
132
133 For \code{plot.deSolve}, the arguments after \ldots must be matched exactly.
134 }
135 }
136
137 \value{
138
139 Function \code{subset} called with \code{arr = FALSE} will return a
140 matrix with up to as many rows as selected by \code{subset} and as
141 many columns as selected variables.
142
143 When \code{arr = TRUE} then an array will be outputted with dimensions
144 equal to the dimension of the selected variable, augmented with the number
145 of rows selected by \code{subset}. This means that the last dimension points
146 to \code{times}.
147
148 Function \code{subset} also has an attribute that contains the \code{times}
149 selected.
150
151 }
152
153 \details{
154 The number of panels per page is automatically determined up to 3 x 3
155 (\code{par(mfrow = c(3, 3))}). This default can be overwritten by
156 specifying user-defined settings for \code{mfrow} or \code{mfcol}.
157 Set \code{mfrow} equal to \code{NULL} to avoid the plotting function to
158 change user-defined \code{mfrow} or \code{mfcol} settings.
159
160 Other graphical parameters can be passed as well. Parameters are
161 vectorized, either according to the number of plots (\code{xlab},
162 \code{ylab}, \code{main}, \code{sub}, \code{xlim}, \code{ylim},
163 \code{log}, \code{asp}, \code{ann}, \code{axes}, \code{frame.plot},
164 \code{panel.first}, \code{panel.last}, \code{cex.lab},
165 \code{cex.axis}, \code{cex.main}) or according to the number of lines
166 within one plot (other parameters e.g. \code{col}, \code{lty},
167 \code{lwd} etc.) so it is possible to assign specific axis labels to
168 individual plots, resp. different plotting style. Plotting parameter
169 \code{ylim}, or \code{xlim} can also be a list to assign different
170 axis limits to individual plots.
171
172 Similarly, the graphical parameters for observed data, as passed by
173 \code{obspar} can be vectorized, according to the number of observed
174 data sets.
175
176 Image plots will only work for 1-D and 2-D variables, as solved with
177 \code{\link{ode.1D}} and \code{\link{ode.2D}}. In the first case, an
178 image with \code{times} as x- and the \code{grid} as y-axis will be
179 created. In the second case, an x-y plot will be created, for all
180 times. Unless \code{ask = FALSE}, the user will be asked to confirm
181 page changes. Via argument \code{mtext}, it is possible to label each
182 page in case of 2D output.
183
184 For images, it is possible to pass an argument
185 \code{method} which can take the values "image" (default),
186 "filled.contour", "contour" or "persp", in order to use the respective
187 plotting method.
188
189 \code{plot} and \code{matplot.0D} will always have \code{times} on the x-axis.
190 For problems solved with \code{ode.1D}, it may be more useful to use
191 \code{plot.1D} or \code{matplot.1D}
192 which will plot how spatial variables change with time. These plots will
193 have the \code{grid} on the x-axis.
194 }
195
196 \seealso{
197 \code{\link{deSolve}}, \code{\link{ode}}, \code{\link{print.deSolve}},
198
199 \code{\link[graphics]{hist}}
200 \code{\link[graphics]{image}}
201 \code{\link[graphics]{matplot}},
202 \code{\link[graphics]{plot}.default}
203 for the underlying functions from package \pkg{graphics},
204
205 \code{\link{ode.2D}}, for an example of using \code{subset} with
206 \code{arr = TRUE}.
207 }
208 \examples{
209 ## =======================================================================
210 ## Example 1. A Predator-Prey model with 4 species in matrix formulation
211 ## =======================================================================
212
213 LVmatrix <- function(t, n, parms) {
214 with(parms, {
215 dn <- r * n + n * (A \%*\% n)
216 return(list(c(dn)))
217 })
218 }
219 parms <- list(
220 r = c(r1 = 0.1, r2 = 0.1, r3 = -0.1, r4 = -0.1),
221 A = matrix(c(0.0, 0.0, -0.2, 0.01, # prey 1
222 0.0, 0.0, 0.02, -0.1, # prey 2
223 0.2, 0.02, 0.0, 0.0, # predator 1; prefers prey 1
224 0.01, 0.1, 0.0, 0.0), # predator 2; prefers prey 2
225 nrow = 4, ncol = 4, byrow=TRUE)
226 )
227 times <- seq(from = 0, to = 500, by = 0.1)
228 y <- c(prey1 = 1, prey2 = 1, pred1 = 2, pred2 = 2)
229
230 out <- ode(y, times, LVmatrix, parms)
231
232 ## Basic line plot
233 plot(out, type = "l")
234
235 ## User-specified axis labels
236 plot(out, type = "l", ylab = c("Prey 1", "Prey 2", "Pred 1", "Pred 2"),
237 xlab = "Time (d)", main = "Time Series")
238
239 ## Set user-defined mfrow
240 pm <- par (mfrow = c(2, 2))
241
242 ## "mfrow=NULL" keeps user-defined mfrow
243 plot(out, which = c("prey1", "pred2"), mfrow = NULL, type = "l", lwd = 2)
244
245 plot(out[,"prey1"], out[,"pred1"], xlab="prey1",
246 ylab = "pred1", type = "l", lwd = 2)
247 plot(out[,"prey2"], out[,"pred2"], xlab = "prey2",
248 ylab = "pred2", type = "l",lwd = 2)
249
250 ## restore graphics parameters
251 par ("mfrow" = pm)
252
253 ## Plot all in one figure, using matplot
254 matplot.0D(out, lwd = 2)
255
256 ## Split y-variables in two groups
257 matplot.0D(out, which = list(c(1,3), c(2,4)),
258 lty = c(1,2,1,2), col=c(4,4,5,5),
259 ylab = c("prey1,pred1", "prey2,pred2"))
260
261 ## =======================================================================
262 ## Example 2. Add second and third output, and observations
263 ## =======================================================================
264
265 # New runs with different parameter settings
266 parms2 <- parms
267 parms2$r[1] <- 0.2
268 out2 <- ode(y, times, LVmatrix, parms2)
269
270 # New runs with different parameter settings
271 parms3 <- parms
272 parms3$r[1] <- 0.05
273 out3 <- ode(y, times, LVmatrix, parms3)
274
275 # plot all three outputs
276 plot(out, out2, out3, type = "l",
277 ylab = c("Prey 1", "Prey 2", "Pred 1", "Pred 2"),
278 xlab = "Time (d)", main = c("Prey 1", "Prey 2", "Pred 1", "Pred 2"),
279 col = c("red", "blue", "darkred"))
280
281
282 ## 'observed' data
283 obs <- as.data.frame(out[out[,1] \%in\% seq(10, 500, by = 30), ])
284
285 plot(out, which = "prey1", type = "l", obs = obs,
286 obspar = list(pch = 18, cex = 2))
287
288 plot(out, type = "l", obs = obs, col = "red")
289
290 matplot.0D(out, which = c("prey1", "pred1"), type = "l", obs = obs)
291
292 ## second set of 'observed' data and two outputs
293 obs2 <- as.data.frame(out2[out2[,1] \%in\% seq(10, 500, by = 50), ])
294
295 ## manual xlim, log
296 plot(out, out2, type = "l", obs = list(obs, obs2), col = c("red", "blue"),
297 obspar = list(pch = 18:19, cex = 2, col = c("red", "blue")),
298 log = c("y", ""), which = c("prey1", "prey1"),
299 xlim = list(c(100, 500), c(0, 400)))
300
301 ## data in 'long' format
302 OBS <- data.frame(name = c(rep("prey1", 3), rep("prey2", 2)),
303 time = c(10, 100, 250, 10, 400),
304 value = c(0.05, 0.04, 0.7, 0.5, 1))
305 OBS
306 plot(out, obs = OBS, obspar = c(pch = 18, cex = 2))
307
308 # a subset only:
309 plot(out, subset = prey1 < 0.5, type = "p")
310
311 # Simple histogram
312 hist(out, col = "darkblue", breaks = 50)
313
314 hist(out, col = "darkblue", breaks = 50, subset = prey1<1 & prey2 < 1)
315
316 # different parameters per plot
317 hist(out, col = c("darkblue", "red", "orange", "black"),
318 breaks = c(10,50))
319
320 ## =======================================================================
321 ## The Aphid model from Soetaert and Herman, 2009.
322 ## A practical guide to ecological modelling.
323 ## Using R as a simulation platform. Springer.
324 ## =======================================================================
325
326 ## 1-D diffusion model
327
328 ## ================
329 ## Model equations
330 ## ================
331 Aphid <- function(t, APHIDS, parameters) {
332 deltax <- c (0.5*delx, rep(delx, numboxes - 1), 0.5*delx)
333 Flux <- -D * diff(c(0, APHIDS, 0))/deltax
334 dAPHIDS <- -diff(Flux)/delx + APHIDS * r
335 list(dAPHIDS, Flux = Flux)
336 }
337
338 ## ==================
339 ## Model application
340 ## ==================
341
342 ## the model parameters:
343 D <- 0.3 # m2/day diffusion rate
344 r <- 0.01 # /day net growth rate
345 delx <- 1 # m thickness of boxes
346 numboxes <- 60
347
348 ## distance of boxes on plant, m, 1 m intervals
349 Distance <- seq(from = 0.5, by = delx, length.out = numboxes)
350
351 ## Initial conditions, ind/m2
352 ## aphids present only on two central boxes
353 APHIDS <- rep(0, times = numboxes)
354 APHIDS[30:31] <- 1
355 state <- c(APHIDS = APHIDS) # initialise state variables
356
357 ## RUNNING the model:
358 times <- seq(0, 200, by = 1) # output wanted at these time intervals
359 out <- ode.1D(state, times, Aphid, parms = 0, nspec = 1, names = "Aphid")
360
361 image(out, grid = Distance, main = "Aphid model", ylab = "distance, m",
362 legend = TRUE)
363
364 ## restricting time
365 image(out, grid = Distance, main = "Aphid model", ylab = "distance, m",
366 legend = TRUE, subset = time < 100)
367
368 image(out, grid = Distance, main = "Aphid model", ylab = "distance, m",
369 method = "persp", border = NA, theta = 30)
370
371 FluxAphid <- subset(out, select = "Flux", subset = time < 50)
372
373 matplot.1D(out, type = "l", lwd = 2, xyswap = TRUE, lty = 1)
374
375 matplot.1D(out, type = "l", lwd = 2, xyswap = TRUE, lty = 1,
376 subset = time < 50)
377
378 matplot.1D(out, type = "l", lwd = 2, xyswap = TRUE, lty = 1,
379 subset = time \%in\% seq(0, 200, by = 10), col = "grey")
380
381 \dontrun{
382 plot(out, ask = FALSE, mfrow = c(1, 1))
383 plot.1D(out, ask = FALSE, type = "l", lwd = 2, xyswap = TRUE)
384 }
385
386 ## see help file for ode.2D for images of 2D variables
387 }
388
389 \keyword{ hplot }
390