Simulate               package:memisc               R Documentation

_S_i_m_u_l_a_t_i_o_n _E_x_p_e_r_i_m_e_n_t_s

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

     'Simulate' is a function to simplify simulation studies. It can be
     used to conduct Monte Carlo studies of statistical estimators,
     discrete event, and agent based simulations.

_U_s_a_g_e:

     Simulate(step,
         conditions = NULL,
         start = NULL,
         cleanup = NULL,
         ...,
         nsim = 1,
         seed = NULL,
         trace=0,
         keep.data=TRUE,
         keep.states=FALSE,
         keep.seed = !is.null(seed),
         restore.seed = !is.null(seed),
         bucket = default_bucket
         )
      
     # signal an interrupt condition
     interrupt(msg=NULL)

_A_r_g_u_m_e_n_t_s:

    step: an expression that produces simulation results for each
          replication; can be a function call, or a braced expression
          that ``returns'' a value like a function body. 

conditions: an optional data frame or object coerceable into a data
          frame. Each row of this data frame defines an experimental
          condition. 

   start: either NULL or an expression that computes starting values
          for 'step'. 

 cleanup: either NULL or an expression does some cleaning up after the
          exectution of all 'step's. 

     ...: other substitutions for 'step', held fixed in the simulation
          experiment

    nsim: an integer value; the number of replication in each
          experimental setting. If 'nsim' is infinite or NA, 'step' is
          replicated (in each setting) until either a user interrupt is
          signalled ('CTRL-C' is pressed) or 'interrupt' is called. 

    seed: either NULL or an integer value suitable for 'set.seed'. Note
          that the random state before the call to 'Simulate' is
          restored. 

   trace: an integer value determining the amount of information output
          during the simulation process. If 'trace' equals zero nothing
          is reported during the simulation run. Otherwise, the
          replication number is output for each multiple of 'trace'. 

keep.data: logical value; if TRUE, return values of the expression in
          'step' are collected into a data fame.

keep.states: logical value; if TRUE, a list of all variables defined in
          'step' (after execution of 'cleanup' if present) is returned.

keep.seed: logical value; if TRUE, the state of the random number
          generator is saved in an attribute "seed" of the return value
          of 'Simulate'. 

restore.seed: logical value; if TRUE, the state of the random number
          generator is restored after conducting the simulations. 

  bucket: a function that returns a 'bucket' object, in which
          simulation results are collected.

     msg: a character string, the message shown if an interrupt
          condition is signalled.

_D_e_t_a_i_l_s:

     'Simulate' calls or evaluates its first argument, 'step', or, if a
     'conditions' argument is given, 'nsim' times for each row of the
     'conditions' data frame.

     Before repeatingly evaluating 'step', the expression 'start', if
     present, is evaluated, which may be used to create starting values
     for a simulatation of to setup up the scenery for an agent-based
     simulation. _After_ repeatingly evaluating 'step', the expression
     'cleanup', if present, is evaluated.

     If 'restore.seed' is given, the state of the random generator is
     saved before conducting the simulation and restored afterwards.
     Therefore 'step', 'start', or 'cleanup' may call 'set.seed'
     without affecting the generation of random numbers after a call to
     'Simulate'.

     'interrupt' raises an interrupt condition, which acts like a user
     interrupt.

     Note that if an interrupt condition is signalled during a
     (replicated) evaluation of 'step' the results of previous
     replications are still saved and 'Simulate' jumps to the next
     condition of the simulation experiment (if there is any). That is,
     if a simulation is interrupted by the user because it takes too
     long, the results so far produced by the simulation are not lost.

     On the other hand, 'interrupt' can be used to determine at
     run-time how often 'step' is evaluated.

_V_a_l_u_e:

     A data frame that contains experimental conditions and simulation
     results.

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

     Normal.example <- function(mean=0,sd=1,n=10){
       x <- rnorm(n=n,mean=mean,sd=sd)
       c(
         Mean=mean(x),
         Median=median(x),
         Var=var(x)
       )
     }

     Normal.simres <- Simulate(
         Normal.example(mean,sd,n),
         expand.grid(
               mean=0,
               sd=c(1,10),
               n=c(10,100)
               ),
         nsim=200,
         trace=50)

     genTable(sd(Median)~sd+n,data=Normal.simres)

     expr.simres <- Simulate(
           median(rnorm(n,mean,sd)),
           expand.grid(
               n=c(10,100),
               mean=c(0,1),
               sd=c(1,10)
           ),
         nsim=200,
         trace=50
         )

     genTable(c(mean(result),sd(result))~sd+n+mean,data=expr.simres)

     ## Not run: 
     ## This takes a little bit longer
     lm.example <- function(a=0,b=1,n=101,xrange=c(-1,1),serr=1){
       x <- seq(from=xrange[1],to=xrange[2],length=n)
       y <- a + b*x + rnorm(n,sd=serr)
       lm.res <- lm(y~x)
       coef <- lm.res$coef
       names(coef) <- c("a","b")
       coef
     }

     lm.simres <- Simulate(
           lm.example(n=n,serr=serr),
           expand.grid(
           serr=c(0.1,1,10),
           n=c(11,101,501)
           ),
           nsim=200,
           trace=50
         )
     genTable(c(sd(a),sd(b))~serr+n,data=lm.simres)
     ## End(Not run)

