simecol-package {simecol} | R Documentation |
The simecol package is intended to give users (scientists and students) an interactive environment to implement, distribute, simulate and document ecological and other dynamic models without the need to write long simulation programs. For this purpose, an object oriented approach using the S4 class system is proposed, which should provide a consistent but still flexible and extensible way to implement simulation models of different types, namely:
odeModel
),
gridModel
), and
rwalkModel
),
indbasedModel
),
simObj
.
Each simulation model is implemented as S4 object (superclass simObj
)
with the following slots:
main = function(time, init, parms, ...)
: a function holding the
main equations of the model,
equations
: an optional non-nested list holding arbitrary
sub-equations (sub-models) of the
model. Sub-equations can be interdependent and can be called
directly from within main
or initfunc
.
parms
: a list (or vector for some classes) with
constant model parameters,
times
: vector of time steps or vector with three
named values from
, to
, by
specifying the
simulation time steps. The from-to-by form can be edited with
fixParms
.
init
: initial state (start values) of the
simulation. This is typically a named vector (state variables in
odeModel
s) or matrix (e.g. initial grid of
gridModel
s).
inputs
: time dependend or spatially resolved external
inputs can be specified as data frame or matrix (more efficient). It
is up to the user to evaluate the corresponding values within the
main
function. Performance optimized versions of
approx
(see approxTime
) are available.
solver
: character string specifying the numerical algorithm
used, e.g. "lsoda"
, "rk4"
or "euler"
from package
deSolve
). In addition, solvers from package
"ddesolve"
can also be used.
In contrast to "euler"
that can be used for difference equations
(i.e. main
returns derivatives), "iterator"
is intended for
models where main returns the new state (i.e for individual-based models).
It is also possible to reference own algorithms (solvers) that are defined
in the useer workspace or to assign solver functions directly.
observer
: optional slot which determines the data stored
during the simulation. A user-provided observer
function can also
be used to write logging information to the screen or to the hard-disk,
to perform run-time visualisation, or statistical analysis during the
simulation.observer
-mechanism works only with
iteration
solvers. It is generally not avalable for
odeModel
s.
out
: this slot holds the simulation results after a
simulation run as data frame (if the return value of main
is a vector)
or as list (otherwise). The type of data stored in out
can be
manipulated by providing a user-definded observer
function.
initfunc
: this slot can hold an optional function which is called
automatically when a new object is created by new
or when it
is re-initialized by initialize
or sim
.
simObj
model objects should be defined and created using the
common S4 mechanisms (new
).
In this way, a simObj
object may contain all data, which are
needed to run simulations simply by entering the model object
via source()
or data()
and then to run and plot the
model for example via plot(sim(obj))
.
Accessor functions (with names identical to the slot names) are
provided to get or set model parameters,
time steps, initial values, inputs, the solver, the main and
sub-equations or initfunc or to extract the model outputs.
It is also possible to modify the components of the simecol objects
directly, e.g. the model equations of a model lv
with
lv@main
, but there is no guarantee that this will work in a compatible
way in future versions.
Models of different type are provided as data and some more in source code (see directory examples).
The examples are intended as a starting point to
write your own simObj
objects and to distribute them to whomever you wish.
The package is supplemented with several utility functions
(e.g. seedfill
or neighbours
), which can
be used independently from simObj
objects.
Thomas Petzoldt thomas.petzoldt@tu-dresden.de
Petzoldt, T and K. Rinke (2007) simecol: An Object-Oriented Framework for Ecological Modeling in R. Journal of Statistical Software, 22(9). URL http://www.jstatsoft.org/v22/i09/.
CA
,
chemostat
,
conway
,
diffusion
,
lv
,
lv3
,
upca
.
## (1) Quick Start Examples ==================================================== data(lv) # load basic Lotka-Volterra model ## Not run: fixParms(lv) ## End(Not run) parms(lv) main(lv) lv <- sim(lv) plot(lv) results <- out(lv) ## Not run: data(conway) # Conway's game of life init(conway) <- matrix(0, 10, 10) times(conway) <- 1:100 fixInit(conway) # enter some "1" sim(conway, animate=TRUE, delay=100) ## End(Not run) ## (2) Additional Resources ==================================================== ## Not run: ## open the directory with source code of demo browseURL(paste(system.file(package="simecol"), "/demo", sep="")) ## run demo demo(jss) ## open the directory with R sourcecode examples browseURL(paste(system.file(package="simecol"), "/examples", sep="")) ## show package vignette with introductory article vignette("simecol-introduction") edit(vignette("simecol-introduction")) ## open the installation directory of simecol ## (NEWS, THANKS, FAQ, ToDo, WISHLIST, ...) browseURL(paste(system.file(package="simecol"), "/", sep="")) ## Open Project Homepage browseURL("http://www.simecol.de") ## End(Not run) ## How to cite package simecol in publications citation("simecol")