bucket                package:memisc                R Documentation

_A_b_s_t_r_a_c_t _D_a_t_a _S_t_r_u_c_t_u_r_e_s _t_o _C_o_l_l_e_c_t _S_i_m_u_l_a_t_i_o_n _R_e_s_u_l_t_s

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

     Buckets (objects that inherit from S3 class "bucket") are abstract
     data structures that are internally used by function 'Simulate' to
     collect results from individual replications of a simulation
     study.

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

     # Generic functions used by 'Simulate'
     put_into(bucket,value)
     pour_out(bucket,...)

     # This generates a bucket that puts data
     # into a data frame
     default_bucket(size=1)

     ## S3 method for class 'default_bucket':
     put_into(bucket,value)
     ## S3 method for class 'default_bucket':
     pour_out(bucket,...)
     ## S3 method for class 'default_bucket':
     dim(x)
     ## S3 method for class 'default_bucket':
     as.matrix(x,...)
     ## S3 method for class 'default_bucket':
     as.data.frame(x,...)

     # This generates a bucket that puts data
     # into a text file.
     textfile_bucket(size=1,name=date())
     ## S3 method for class 'textfile_bucket':
     put_into(bucket,value)
     ## S3 method for class 'textfile_bucket':
     pour_out(bucket,...)
     ## S3 method for class 'textfile_bucket':
     dim(x)
     ## S3 method for class 'textfile_bucket':
     as.data.frame(x,...)
     ## S3 method for class 'textfile_bucket':
     as.matrix(x,...)

     ## S3 method for class 'bucket':
     print(x,...)
     ## S3 method for class 'bucket':
     x[i,...]

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

bucket,x,data: an object that inherits from class "bucket".

   value: a named list of results of a replication to put into the
          bucket.

    size: a numerical value, the number of rows by which to extend the
          bucket if it is full. This will be set by 'Simulate' either
          according to its 'nsim' argument or according to
          'getOption("Simulation.chunk.size")'

    name: a name for the textfile into which results are written.

       i: a numerical vector to select replication results from the
          bucket.

     ...: other arguments, ignored or passed to other methods.

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

     If a user wants to provide another class of buckets for collecting
     results for 'Simulate' (s)he needs to define a function that
     returns a bucket object, as 'default_bucket' and 'textfile_bucket'
     do; and to define methods of 'put_into', 'pour_out', 'dim',
     'as.data.frame', 'as.matrix' for the newly defined bucket class.

     The 'put_into' method should add a list of values to the bucket,
     the 'pour_out' method should close the bucket against further
     input and pour out in the data contained in the bucket into a
     fixed data structure. After 'pour_out', 'put_into' should fail.
     The 'default_bucket' method, e.g. puts the data into a data frame,
     the 'textfile_bucket' method closes the textfile into which data
     were written.

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

     The function 'default_bucket' returns an object of class
     '"default_bucket"', while function 'textfile_bucket' returns an
     object of class '"textfile_bucket"'.

     The methods for 'dim', 'as.data.frame', and 'as.matrix' give the
     usual return values, of the generic functions.

     'put_into' returns nothing. 'pour_out' returns the bucket.

_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)
       )
     }

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


     tempfile_bucket <- function(n)textfile_bucket(n,name=tempfile())

     Sim_textfile_bucket <- Simulate(
         Normal.example(mean,sd,n),
         expand.grid(
               mean=0,
               sd=c(1,10),
               n=c(10,100)
               ),
         nsim=200,
         bucket=tempfile_bucket
         )

     Sim_default_bucket
     Sim_default_bucket[1:10]

     Sim_textfile_bucket
     Sim_textfile_bucket[1:10]

     # Access of the textfile generated by 'textfile_bucket':
     Sim_textfile_bucket$name
     read.table(Sim_textfile_bucket$name,header=TRUE,nrow=10)

