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'),

        *  non-spatial individual-based models or 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 'initialize'.

        *  'parms': a list (for 'gridModel's) or vector (all other
           pre-definded classes) with constant model parameters,

        *  'times': vector of time steps or a 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 version of 'approx' (see 'approxTime') are
           available.

        *  'solver': character string specifying the numerical
           algorithm used. Currently '"lsoda"' (from package
           'odesolve'), '"rk4"', '"euler"' and '"iterator"' are
           supported. It is possible to provide own algorithms
           (solvers). Please have a look at the code at the beginning
           of '"rk4"' or '"iterator"'.

        *  'out': this slot holds the simulation results after a
           simulation run as data frame or list (of matrices).

        *  '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'.

     '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.

     The following are sources of information on 'simecol':

       Home page          u <- "http://hhbio.wasser.tu-dresden.de/projects/simecol/"; browseURL(u)
       News               file.show(system.file("NEWS", package = "simecol"))
       Wish List          file.show(system.file("WISHLIST", package = "simecol"))
       Acknowledgements   file.show(system.file("THANKS", package = "simecol"))
       This File          package?simecol
       Help files as PDF  u <- "http://cran.r-project.org/doc/packages/simecol.pdf"; browseURL(u)

_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, K. Rinke (2007), 'simecol': An Object-Oriented
     Framework for Ecological Modeling in R. Journal of Statistical
     Software, submitted.

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

         ## -- binary examples -------------------------------
         data(lv)        # load basic Lotka-Volterra model

         ## Not run: fixParms(lv)
         parms(lv)
         main(lv)
         lv <- sim(lv)
         plot(lv)
         results <- out(lv)

         data(conway)    # Conway's game of life
         init(conway) <- matrix(0, 10, 10)
         ## Not run: fixInit(conway) # enter some "1"
         sim(conway, animate=TRUE, delay=10)
         
         ## -- sourcecode examples ----------------------------
         ## open the directory with all sourcecode examples
         ## Not run: 
         browseURL(paste(system.file(package="simecol"), "/examples", sep=""))
         
     ## End(Not run)

