Learn R Programming

simFrame (version 0.5.4)

SimControl-class: Class "SimControl"

Description

Class for controlling how simulation runs are performed.

Arguments

Objects from the Class

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

Slots

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.

Accessor and mutator methods

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.

Methods

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.

UML class diagram

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.

Details

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.

References

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. 10.18637/jss.v037.i03.

See Also

runSimulation, "'>SimResults"

Examples

Run this code
# NOT RUN {
#### 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)
# }

Run the code above in your browser using DataLab