simecol-package           package:simecol           R Documentation

_G_e_n_e_r_a_l _I_n_f_o_r_m_a_t_i_o_n _a_b_o_u_t _t_h_e _s_i_m_e_c_o_l _P_a_c_k_a_g_e

_D_e_s_c_r_i_p_t_i_o_n:

     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:


        *  ordinary differential equation (ODE) models (class
           'odeModel'),

        *  grid-oriented individual-based models (class 'gridModel'),
           and

        *  particle diffusion-type models (class 'rwalkModel'),

        *  individual-based models (class 'indbasedModel'),

        *  other model types by deriving a user specified subclass from
           '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': a function or a 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 user
           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.

           Note that the 'observer'-mechanism works only with
           'iteration' solvers. It is generally not available 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 this is not
     recommended as 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.

_A_u_t_h_o_r(_s):

     Thomas Petzoldt thomas.petzoldt@tu-dresden.de

_R_e_f_e_r_e_n_c_e_s:

     Petzoldt, T and K. Rinke (2007) 'simecol': An Object-Oriented
     Framework for Ecological Modeling in R. _Journal of Statistical
     Software_, *22*(9). URL <URL: http://www.jstatsoft.org/v22/i09/>.

_S_e_e _A_l_s_o:

     'CA', 'chemostat', 'conway', 'diffusion', 'lv', 'lv3', 'upca'.

_E_x_a_m_p_l_e_s:

     ## (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) Define and run your own  simecol model ==========================

     lv <- new("odeModel", 
       main = function (time, init, parms) {
         with(as.list(c(init, parms)), {
           dn1 <-   k1 * N1 - k2 * N1 * N2
           dn2 <- - k3 * N2 + k2 * N1 * N2
           list(c(dn1, dn2))
         })
       },
       parms  = c(k1 = 0.2, k2 = 0.2, k3 = 0.2),
       times  = c(from = 0, to = 100, by = 0.5),
       init   = c(N1 = 0.5, N2 = 1),
       solver = "lsoda"
     )

     lv <- sim(lv)
     plot(lv)

     ## (3) The same in matrix notation; this allows generalization      ====
     ##     to multi-species interaction models with > 2 species.        ====

     LVPP <- new("odeModel",
       main = function(t, n, parms) {
         with(parms, {
           dn <- r * n  + n * (A %*% n)
           list(c(dn))
         })
       },
       parms = list(
         # growth/death rates
         r = c(k1 = 0.2, k3 = -0.2),
         # interaction matrix
         A = matrix(c(0.0, -0.2,
                      0.2,  0.0),
                      nrow = 2, ncol = 2, byrow=TRUE)
       ),
       times  = c(from = 0, to = 100, by = 0.5),
       init   = c(N1 = 0.5, N2 = 1),
       solver = "lsoda"
     )

     plot(sim(LVPP))

     ## (4) 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")

