Simulate by Design

Lisa DeBruine

2019-12-29

Source: vignettes/sim_design.Rmd

The sim_design() function creates a dataset with a specific between- and within-subjects design.

Quick example

For example, the following creates a 2w*2b design with 100 observations in each cell. The between-subject factor is pet with two levels (cat and dog). The within-subject factor is time with two levels (day and night).

The data is sampled from a population where the mean for the cat_day cell is 10, the mean for the cat_night cell is 20, the mean for the dog_day cell is 15, and the mean for the dog_night cell is 25. All cells have a SD of 5 and all within-subject cells are correlated r = 0.5.

between <- list(pet = c(cat = "Cat Owners", 
                        dog = "Dog Owners"))
within <- list(time = c("morning", "noon", "evening", "night"))
mu <- data.frame(
  cat    = c(10, 12, 14, 16),
  dog    = c(10, 15, 20, 25),
  row.names = within$time
)
df <- sim_design(within, between, 
                 n = 100, mu = mu, sd = 5, r = .5,
                 empirical = TRUE, plot = TRUE)

Specification of design parameters

Factor and level names

Anonymous

If you don’t feel like naming your factors and levels, you can just put in a vector of levels. So you can make a quick 2w*3w*2b with the following code.

List of vectors

You can specify between-subject and within-subject factors as a list of vectors where the item names are the factor labels and the vectors are the level labels.

between <- list(
  pet = c("cat", "dog")
)
within <- list(
  time = c("day", "night")
)

df <- sim_design(within, between, mu = 1:4)

List of named vectors/lists

You can also specify factors as a list of named vectors or lists where the item names are the factor labels, the vector names are the level labels that are used in the data table, and the vector items are the long labels for a codebook or plot.

between <- list(
  pet = c(cat = "Is a cat person", dog = "Is a dog person")
)
within <- list(
  time = c(day = "Tested during the day", night = "Tested at night")
)
df <- sim_design(within, between, mu = 1:4)

Specifying N

You can specify the Ns for each between-subject cell as a single number, named list, or data frame.

Single number

You usually want to specify n as a single number. This is N per cell, not total sample size.

Named list

You can also specify n as a named list of Ns per between-subject cell.

Dataframe

Or as a data frame. You just need to get the row or column names right, but they don’t have to be in the right order.

You can specify the cells as row names or column names and check_design() will fix them. Since n has to be the same for each within-subject factor, you can specify n as a single column with any name.

n <- data.frame(n = c(10, 20, 30, 40),
                row.names = c("B1_C1", "B1_C2", "B2_C1", "B2_C2"))
design <- check_design(2, c(2,2), n = n, plot = FALSE)
str(design$n)
#> List of 4
#>  $ B1_C1: num 10
#>  $ B1_C2: num 20
#>  $ B2_C1: num 30
#>  $ B2_C2: num 40

Mu and SD

The specifications for mu and sd need both within-subect and between-subject cells. You can specify these as a single numbers, a vector, a named list of named vectors or a data frame.

Unnamed vector

An unnamed vector is a quick way to specify means and SDs, but the order relative to your between- and within-subject cells can be confusing.

Named list of named vectors

A named list of named vectors prevents confusion due to order. The levels of the between-subject factors are the list names and the levels of the within-subject factors are the vector names, but their order doesn’t matter.

Alternatively, you can specify them as data frames.

If you transpose the dataframe, this works out fine unless your within- and between-subject cells have identical names.

Correlations

If you have any within-subject factors, you need to set the correlation for each between-cell. Here, we only have two levels of one within-subject factor, so can only set one correlation per between-cell.

Upper right triangle

If you have more than 2 within-subject cells, you can specify each specific correlation in the upper right triangle of the correlation matrix as a vector.

Correlation matrix

You can also enter the correlation matrix from cor().

Empirical

If you set empirical = TRUE, you will get the exact means, SDs and correlations you specified. If you set empirical = FALSE or omit that argument, your data will be sampled from a population with those parameters, but your dataset will not have exactly those values (just on average).

between <- list(pet  = c("cat", "dog"))
within  <- list(time = c("day", "night"))
mu <- list(
  cat = c(day = 10, night = 20),
  dog = c(day = 30, night = 40)
)

sd <- list(
  cat = c(day = 5, night = 10),
  dog = c(day = 15, night = 20)
)

r <- list(cat = .5, dog = .6)

df <- sim_design(within, between, n = 100, 
                 mu = mu, sd = sd, r = r,
                 empirical = TRUE)

pet n var day night mean sd
cat 100 day 1.0 0.5 10 5
cat 100 night 0.5 1.0 20 10
dog 100 day 1.0 0.6 30 15
dog 100 night 0.6 1.0 40 20

More factors

Here is a 2w*3w*2b*2b example. When you have multiple within or between factors, you need to specify parameters by cell. Cell names are the level names, in the order they are listed in the within or between arguments, separated by underscores.

Foe example, if you have one within-subject factor of condition with levels con and inc, and another within-subject factor of version wiith levels easy, med, and hard, your cell lables will be: con_easy, inc_easy, con_med, inc_med, con_hard, and inc_hard.

If you have any characters in your level names except letters and numbers, they will be replaced by a full stop (e.g., my super-good level_name will become my.super.good.level.name).

You can set the correlation for each between-cell to a single number.

Or you can set the full correlation matrix with a vector or matrix. Since we have 6 within-cells, this is a 6x6 matrix or a vector of the upper right 15 values.

You can set long = TRUE to return the data frame in long format, which is usually easier for plotting.

df <- sim_design(within, between, n = 100, 
                 mu = mu, sd = 2, r = r, 
                 dv = c(rt = "Reaction Time"), long = TRUE)

Multiple datasets

You can simulate multiple datasets by setting the rep argument of sim_design() to a number greater than 1. This will return a nested data frame with one column called rep and another column called data, that contains each individual data frame. This method is ** much** faster than repeatedly calling sim_design(), which will check the syntax of your design each time.

The code below creates 5 data frames with a 2W*2B design.

The plot_design() function will plot each replication in a different facet.

You can access an individual data frame using df$data[[1]] or run the same function on each data frame using a pattern like below: