SimControl-class: Class "SimControl"
In simFrame: Simulation Framework

Description Objects from the Class Slots Details Accessor and mutator methods Methods UML class diagram Author(s) References See Also Examples

Class for controlling how simulation runs are performed.

Objects can be created by calls of the form new("SimControl", ...) or SimControl(...).

contControl:: Object of class "OptContControl"; a control object for contamination, or NULL.
NAControl:: Object of class "OptNAControl"; a control object for inserting missing values, or NULL.
design:: Object of class "character" specifying variables (columns) to be used for splitting the data into domains. The simulations, including contamination and the insertion of missing values (unless SAE=TRUE), are then performed on every domain.
fun:: Object of class "function" to be applied in each simulation run.
dots:: Object of class "list" containing additional arguments to be passed to fun.
SAE:: Object of class "logical" indicating whether small area estimation will be used in the simulation experiment.

There are some requirements for fun. It must return a numeric vector, or a list with the two components values (a numeric vector) and add (additional results of any class, e.g., statistical models). Note that the latter is computationally slightly more expensive. A data.frame is passed to fun in every simulation run. The corresponding argument must be called x. If comparisons with the original data need to be made, e.g., for evaluating the quality of imputation methods, the function should have an argument called orig. If different domains are used in the simulation, the indices of the current domain can be passed to the function via an argument called domain.

For small area estimation, the following points have to be kept in mind. The design for splitting the data must be supplied and SAE must be set to TRUE. However, the data are not actually split into the specified domains. Instead, the whole data set (sample) is passed to fun. Also contamination and missing values are added to the whole data (sample). Last, but not least, the function must have a domain argument so that the current domain can be extracted from the whole data (sample).

In every simulation run, fun is evaluated using try. Hence no results are lost if computations fail in any of the simulation runs.

getContControl: signature(x = "SimControl"): get slot ContControl.
setContControl: signature(x = "SimControl"): set slot ContControl.
getNAControl: signature(x = "SimControl"): get slot NAControl.
setNAControl: signature(x = "SimControl"): set slot NAControl.
getDesign: signature(x = "SimControl"): get slot design.
setDesign: signature(x = "SimControl"): set slot design.
getFun: signature(x = "SimControl"): get slot fun.
setFun: signature(x = "SimControl"): set slot fun.
getDots: signature(x = "SimControl"): get slot dots.
setDots: signature(x = "SimControl"): set slot dots.
getSAE: signature(x = "SimControl"): get slot SAE.
setSAE: signature(x = "SimControl"): set slot SAE.

clusterRunSimulation: signature(cl = "ANY", x = "data.frame", setup = "missing", nrep = "numeric", control = "SimControl"): run a simulation experiment on a cluster.
clusterRunSimulation: signature(cl = "ANY", x = "data.frame", setup = "VirtualSampleControl", nrep = "missing", control = "SimControl"): run a simulation experiment on a cluster.
clusterRunSimulation: signature(cl = "ANY", x = "data.frame", setup = "SampleSetup", nrep = "missing", control = "SimControl"): run a simulation experiment on a cluster.
clusterRunSimulation: signature(cl = "ANY", x = "VirtualDataControl", setup = "missing", nrep = "numeric", control = "SimControl"): run a simulation experiment on a cluster.
clusterRunSimulation: signature(cl = "ANY", x = "VirtualDataControl", setup = "VirtualSampleControl", nrep = "numeric", control = "SimControl"): run a simulation experiment on a cluster.
head: signature(x = "SimControl"): currently returns the object itself.
runSimulation: signature(x = "data.frame", setup = "VirtualSampleControl", nrep = "missing", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "data.frame", setup = "SampleSetup", nrep = "missing", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "data.frame", setup = "missing", nrep = "numeric", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "data.frame", setup = "missing", nrep = "missing", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "VirtualDataControl", setup = "missing", nrep = "numeric", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "VirtualDataControl", setup = "missing", nrep = "missing", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "VirtualDataControl", setup = "VirtualSampleControl", nrep = "numeric", control = "SimControl"): run a simulation experiment.
runSimulation: signature(x = "VirtualDataControl", setup = "VirtualSampleControl", nrep = "missing", control = "SimControl"): run a simulation experiment.
show: signature(object = "SimControl"): print the object on the R console.
summary: signature(object = "SimControl"): currently returns the object itself.
tail: signature(x = "SimControl"): currently returns the object itself.

A slightly simplified UML class diagram of the framework can be found in Figure 1 of the package vignette An Object-Oriented Framework for Statistical Simulation: The R Package simFrame. Use vignette("simFrame-intro") to view this vignette.

Andreas Alfons

Alfons, A., Templ, M. and Filzmoser, P. (2010) An Object-Oriented Framework for Statistical Simulation: The R Package simFrame. Journal of Statistical Software, 37(3), 1–36. doi: 10.18637/jss.v037.i03.

runSimulation, "SimResults"

#### design-based simulation
set.seed(12345)  # for reproducibility
data(eusilcP)    # load data

## control objects for sampling and contamination
sc <- SampleControl(size = 500, k = 50)
cc <- DARContControl(target = "eqIncome", epsilon = 0.02,
    fun = function(x) x * 25)

## function for simulation runs
sim <- function(x) {
    c(mean = mean(x$eqIncome), trimmed = mean(x$eqIncome, 0.02))
}

## combine these to "SimControl" object and run simulation
ctrl <- SimControl(contControl = cc, fun = sim)
results <- runSimulation(eusilcP, sc, control = ctrl)

## explore results
head(results)
aggregate(results)
tv <- mean(eusilcP$eqIncome)  # true population mean
plot(results, true = tv)



#### model-based simulation
set.seed(12345)  # for reproducibility

## function for generating data
rgnorm <- function(n, means) {
    group <- sample(1:2, n, replace=TRUE)
    data.frame(group=group, value=rnorm(n) + means[group])
}

## control objects for data generation and contamination
means <- c(0, 0.25)
dc <- DataControl(size = 500, distribution = rgnorm,
    dots = list(means = means))
cc <- DCARContControl(target = "value",
    epsilon = 0.02, dots = list(mean = 15))

## function for simulation runs
sim <- function(x) {
    c(mean = mean(x$value),
        trimmed = mean(x$value, trim = 0.02),
        median = median(x$value))
}

## combine these to "SimControl" object and run simulation
ctrl <- SimControl(contControl = cc, design = "group", fun = sim)
results <- runSimulation(dc, nrep = 50, control = ctrl)

## explore results
head(results)
aggregate(results)
plot(results, true = means)