Piping operator

Description

This is the 'pipe operator' from the package 'magrittr'. Use it to chain all operations for the simulation together. See the original documentation for details: %>%.

Usage

lhs %>% rhs

Arguments

Aggregation function

Description

This function is intended to be used with sim_agg and not interactively. This is one implementation for aggregating data in a simulation set-up.

Usage

agg_all(groupVars = "idD")

Arguments

Details

This function follows the split-apply-combine idiom. Each data set is split by the defined variables. Then the variables within each subset are aggregated (reduced to one row). Logical variables are reduced by any; for characters and factors dummy variables are created and the aggregate is the mean of each dummy; and for numerics the mean (removing NAs).

See Also

sim_agg

Examples

sim_base() %>% sim_gen_x() %>% sim_gen_e() %>% sim_agg(agg_all())

as.data.frame method for sim_setup

Description

Use this method to get a single simulated data.frame out of a sim_setup object.

Usage

## S3 method for class 'sim_setup'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Autoplot method

Description

Use this function to produce plots for an object of class sim_setup and you like to have plots based on ggplot2. At this time it is a ggplot2 implementation which mimics the behavior of smoothScatter without all the options.

Usage

## S3 method for class 'sim_setup'
autoplot(object, x = "x", y = "y", ...)

Arguments

Examples

## Not run: 
autoplot(sim_base_lm())

## End(Not run)

Add id-variables to data

Description

Use this function to add id-variables to your data.

Usage

base_add_id(data, domainId)

Arguments

Construct data with id-variables

Description

This function constructs a data frame with grouping/id variables.

Usage

base_id(nDomains = 10, nUnits = 10)

base_id_temporal(nDomains = 10, nUnits = 10, nTime = 10)

Arguments

Value

Return a data.frame with variables idD as ID-variable for domains, and idU as ID-variable for units.

Examples

base_id(2, 2)
base_id(2, c(2, 3))

Compute variables in data

Description

This function is intended to be used with sim_comp_pop, sim_comp_sample or sim_comp_agg and not interactively. This is a wrapper around mutate

Usage

comp_var(...)

Arguments

See Also

sim_comp_pop, sim_comp_sample, sim_comp_agg

Examples

sim_base_lm() %>% sim_comp_pop(comp_var(yExp = exp(y)))

Generator functions

Description

These functions are intended to be used with sim_gen and not interactively. They are designed to draw random numbers according to the setting of grouping variables.

Usage

gen_norm(mean = 0, sd = 1, name = "e")

gen_v_norm(mean = 0, sd = 1, name = "v")

gen_v_sar(mean = 0, sd = 1, rho = 0.5, type = "rook", name)

gen_v_ar1(mean = 0, sd = 1, rho = 0.5, groupVar = "idD", timeVar = "idT", name)

gen_generic(generator, ..., groupVars = NULL, name)

Arguments

Details

gen_norm is used to draw random numbers from a normal distribution where all generated numbers are independent.

gen_v_norm and gen_v_sar will create an area-level random component. In the case of v_norm, the error component will be from a normal distribution and i.i.d. from an area-level perspective (all units in an area will have the same value, all areas are independent). v_sar will also be from a normal distribution, but the errors are correlated. The variance covariance matrix is constructed for a SAR(1) - spatial/simultanous autoregressive process. mvrnorm is used for the random number generation. gen_v_norm and gen_v_sar expect a variable idD in the data identifying the areas.

gen_generic can be used if your world is not normal. You can specify 'any' function as generator, like rnorm. Arguments in ... are matched by name or position. The first argument of generator is expected to be the number of random numbers (not necessarily named n) and need not to be specified.

See Also

sim_gen, sim_gen_x, sim_gen_e, sim_gen_ec, sim_gen_v, sim_gen_vc, cell2nb

Examples

sim_base() %>% sim_gen_x() %>% sim_gen_e() %>% sim_gen_v() %>% sim_gen(gen_v_sar(name = "vSP"))

# Generic interface
set.seed(1)
dat1 <- sim(base_id() %>%
  sim_gen(gen_generic(rnorm, mean = 0, sd = 4, name = "e")))
set.seed(1)
dat2 <- sim(base_id() %>% sim_gen_e())
all.equal(dat1, dat2)

Plotting methods

Description

Use this function to produce plots for an object of class sim_setup.

Usage

## S3 method for class 'sim_setup'
plot(x, y, ...)

Arguments

See Also

autoplot

Sampling functions

Description

These functions are intended to be used with sim_sample and not interactively. They are wrappers around sample_frac and sample_n.

Usage

sample_fraction(size, replace = FALSE, weight = NULL, groupVars = NULL)

sample_number(size, replace = FALSE, weight = NULL, groupVars = NULL)

sample_numbers(size, replace = FALSE, groupVars = NULL)

sample_cluster_number(size, replace = FALSE, weight = NULL, groupVars)

sample_cluster_fraction(size, replace = FALSE, weight = NULL, groupVars)

Arguments

Details

sample_numbers is a vectorized version of sample_number.

sample_cluster_number and sample_cluster_fraction will sample clusters (all units in a cluster).

Examples

sim_base_lm() %>% sim_sample(sample_number(5))
sim_base_lm() %>% sim_sample(sample_fraction(0.5))
sim_base_lm() %>% sim_sample(sample_cluster_number(5, groupVars = "idD"))
sim_base_lm() %>% sim_sample(sample_cluster_fraction(0.5, groupVars = "idD"))

Show for sim_setup

Description

This is the documentation for the show methods in the package saeSim. In case you don't know, show is for S4-classes like print for S3. If you don't know what that means, don't bother, there is no reason to call show directly, however there is the need to document it.

Usage

## S4 method for signature 'sim_setup'
show(object)

## S4 method for signature 'summary.sim_setup'
show(object)

Arguments

Details

Will print the head of a sim_setup to the console, after converting it to a data.frame.

Start simulation

Description

This function will start the simulation. Use the printing method as long as you are testing the scenario.

Usage

sim(
  x,
  R = 1,
  path = NULL,
  overwrite = TRUE,
  ...,
  suffix = NULL,
  fileExt = ".csv",
  libs = NULL,
  exports = NULL
)

Arguments

Details

The package parallelMap is utilized as back-end for parallel computations.

Use the argument path to store the simulation results in a directory. This may be a good idea for long running simulations and for those using large data.frames. You can use sim_read_data to read them in. The return value will change to NULL in each run.

Value

The return value is a list. The elements are the results of each simulation run, typically of class data.frame. In case you specified path, each element is NULL.

Examples

setup <- sim_base_lm()
resultList <- sim(setup, R = 1)

# For parallel computations you may need to export objects
localFun <- function() cat("Hello World!")
comp_fun <- function(dat) {
  localFun()
  dat
}

res <- sim_base_lm() %>% 
  sim_comp_pop(comp_fun) %>% 
  sim(R = 2, 
      mode = "socket", cpus = 2,
      exports = "localFun")

str(res)

Aggregation component

Description

One of the components which can be added to a simulation set-up. Aggregating the data is a simulation component which can be used to aggregate the population or sample. The aggregation will simply be done after the sampling, if you haven't specified any sampling component, the population is aggregated (makes sense if you draw samples directly from the model).

Usage

sim_agg(simSetup, aggFun = agg_all())

Arguments

Details

Potentially you can define an aggFun yourself. Take care that it only has one argument, named dat, and returns the aggregated data as data.frame.

See Also

agg_all, sim_gen, sim_comp_pop, sim_sample, , sim_comp_sample

Examples

# Aggregating the population:
sim_base_lm() %>% sim_agg()

# Aggregating after sampling:
sim_base_lm() %>% sim_sample() %>% sim_agg()

# User aggFun:
sim_base_lm() %>% sim_agg(function(dat) dat[1, ])

Base component

Description

Use the 'sim_base' functions to start a new sim_setup.

Usage

sim_base(data = base_id(100, 100))

Arguments

Examples

# Example for a linear model:
sim_base() %>% sim_gen_x() %>% sim_gen_e()

Preconfigured set-ups

Description

sim_base_lm() will start a linear model: One regressor, one error component. sim_base_lmm() will start a linear mixed model: One regressor, one error component and one random effect for the domain. sim_base_lmc() and sim_base_lmmc() add outlier contamination to the scenarios. Use these as a quick start, then you probably want to configure your own scenario.

Usage

sim_base_lm()

sim_base_lmm()

sim_base_lmc()

sim_base_lmmc()

Details

Additional information on the generated variables:

• nDomains: 100 domains

• nUnits: 100 in each domain

• x: is normally distributed with mean of 0 and sd of 4

• e: is normally distributed with mean of 0 and sd of 4

• v: is normally distributed with mean of 0 and sd of 1, it is a constant within domains

• e-cont: as e; probability of unit to be contaminated is 0.05; sd is then 150

• v-cont: as v; probability of area to be contaminated is 0.05; sd is then 40

• y = 100 + x + v + e

Examples

# The preconfigured set-ups:
sim_base_lm()
sim_base_lmm()
sim_base_lmc()
sim_base_lmmc()

Preconfigured computation components

Description

sim_comp_n and sim_comp_N will add the sample and population size in each domain respectively. sim_comp_popMean and sim_comp_popVar the population mean and variance of the variable y. The data is expected to have a variable idD identifying domains.

Usage

sim_comp_n(simSetup)

sim_comp_N(simSetup)

sim_comp_popMean(simSetup)

sim_comp_popVar(simSetup)

Arguments

Calculation component

Description

One of the components which can be added to a sim_setup. These functions can be used for adding new variables to the data.

Usage

sim_comp_pop(simSetup, fun = comp_var(), by = "")

sim_comp_sample(simSetup, fun = comp_var(), by = "")

sim_comp_agg(simSetup, fun = comp_var(), by = "")

Arguments

Details

Potentially you can define a function for computation yourself. Take care that it only has one argument, named dat, and returns a data.frame. Use comp_var for simple data manipulation. Functions added with sim_comp_pop are applied before sampling; sim_comp_sample after sampling. Functions added with sim_comp_agg after aggregation.

See Also

comp_var, sim_gen, sim_agg, sim_sample, sim_comp_N, sim_comp_n, sim_comp_popMean, sim_comp_popVar

Examples

# Standard behavior
sim_base() %>% sim_gen_x() %>% sim_comp_N()

# Custom data modifications
## Add predicted values of a linear model
library(saeSim)

comp_lm <- function(dat) {
  dat$linearPredictor <- predict(lm(y ~ x, data = dat))
  dat
}

sim_base_lm() %>% sim_comp_pop(comp_lm)

# or if applied after sampling
sim_base_lm() %>% sim_sample() %>% sim_comp_pop(comp_lm)

Generation component

Description

One of the components which can be added to a sim_setup.

Usage

sim_gen(simSetup, generator)

sim_gen_generic(simSetup, ...)

Arguments

Details

Potentially you can define a generator yourself. Take care that it has one argument, named dat, and returns a data.frame. sim_gen_generic is a shortcut to gen_generic.

See Also

gen_norm, gen_v_norm, gen_v_sar, sim_agg, , sim_comp_pop, sim_sample, sim_gen_x, sim_gen_e, sim_gen_v, sim_gen_vc, sim_gen_ec

Examples

# Data setup for a mixed model
sim_base() %>% sim_gen_x() %>% sim_gen_v() %>% sim_gen_e()
# Adding contamination in the model error
sim_base() %>% sim_gen_x() %>% sim_gen_v() %>% sim_gen_e() %>% sim_gen_ec()

# Simple user defined generator:
gen_myVar <- function(dat) {
  dat["myVar"] <- rnorm(nrow(dat))
  dat
}

sim_base() %>% sim_gen_x() %>% sim_gen(gen_myVar)

# And a chi-sq(5) distributed 'random-effect':
sim_base() %>% sim_gen_generic(rchisq, df = 5, groupVars = "idD", name = "re")

Generation Component for contamination

Description

One of the components which can be added to a sim_setup. It is applied after functions added with sim_gen.

Usage

sim_gen_cont(simSetup, generator, nCont, type, areaVar = NULL, fixed = TRUE)

Arguments

See Also

sim_gen

Examples

sim_base_lm() %>% 
  sim_gen_cont(gen_norm(name = "e"), nCont = 0.05, type = "unit", areaVar = "idD") %>%
  as.data.frame

Preconfigured generation components

Description

These are some preconfigured generation components and all wrappers around sim_gen and sim_gen_cont.

Usage

sim_gen_x(simSetup, mean = 0, sd = 4, name = "x")

sim_gen_e(simSetup, mean = 0, sd = 4, name = "e")

sim_gen_ec(
  simSetup,
  mean = 0,
  sd = 150,
  name = "e",
  nCont = 0.05,
  type = "unit",
  areaVar = "idD",
  fixed = TRUE
)

sim_gen_v(simSetup, mean = 0, sd = 1, name = "v")

sim_gen_vc(
  simSetup,
  mean = 0,
  sd = 40,
  name = "v",
  nCont = 0.05,
  type = "area",
  areaVar = "idD",
  fixed = TRUE
)

Arguments

Details

x: fixed-effect component; e: model-error; ec: contaminated model error; v: random-effect (error constant for each domain); vc contaminated random-effect. Note that for contamination you are expected to add both, a non-contaminated component and a contaminated component.

Read in simulated data

Description

Functions to read in simulation data from folder. Can be csv or RData files.

Usage

sim_read_data(path, ..., returnList = FALSE)

sim_clear_data(path, ...)

sim_read_list(path)

sim_clear_list(path)

Arguments

Response component

Description

One of the components which can be added to a sim_setup.

Usage

sim_resp(simSetup, respFun)

sim_resp_eq(simSetup, ...)

Arguments

Details

Potentially you can define an respFun yourself. Take care that it only has one argument, named dat, and returns the a data.frame.

See Also

agg_all, sim_gen, sim_comp_pop, sim_sample, , sim_comp_sample

Examples

base_id() %>% sim_gen_x() %>% sim_gen_e() %>% sim_resp_eq(y = 100 + 2 * x + e)

Sampling component

Description

One of the components which can be added to a sim_setup. This component can be used to add a sampling mechanism to the simulation set-up. A sample will be drawn after the population is generated (sim_gen) and variables on the population are computed (sim_comp_pop).

Usage

sim_sample(simSetup, smplFun = sample_number(size = 5L, groupVars = "idD"))

Arguments

Details

Potentially you can define a smplFun yourself. Take care that it has one argument, named dat being the data as data.frame, and returns the sample as data.frame.

See Also

sample_number, sample_fraction

Examples

# Simple random sample - 5% sample:
sim_base_lm() %>% sim_sample(sample_fraction(0.05))

# Simple random sampling proportional to size - 5% in each domain:
sim_base_lm() %>% sim_sample(sample_fraction(0.05, groupVars = "idD"))

# User defined sampling function:
sample_mySampleFun <- function(dat) {
  dat[sample.int(nrow(dat), 10), ]
}

sim_base_lm() %>% sim_sample(sample_mySampleFun)

Add a name to a sim_setup

Description

Use this function to add a name to a sim_setup in case you are simulating different scenarios. This name will be added if you use the function sim for simulation

Usage

sim_simName(simSetup, name)

Arguments

Examples

sim_base_lm() %>% sim_simName("newName")

Summary for a sim_setup

Description

Reports a summary of the simulation setup.

Usage

## S4 method for signature 'sim_setup'
summary(object, ...)

Arguments

Examples

summary(sim_base_lm())