windsimu: Simulate Datasets with User-Defined Patterns of...

In richmaparker/windsimu: Simulates Data with User-specified Patterns of Within-Individual Variation

Description

Function to create simulated dataset given user-defined parameters and data structure for growth curve model with optional random effect for L2 variance

Usage

windsimu(sample_size, var_names, x1_range, design_matrices, beta, alpha,
  gamma = NULL, distal_type = NULL, sigma2e_distal = NULL, sigma2u,
  log_sigma2e = TRUE, linear_sigma2e_attempts = 10, random_seed)

Arguments

sample_size	List of named vectors specifying sample size at level 2 (named n2) and level 1 (named n1).
var_names	List of named character vectors indicating names for intercept (x0) and time variable (x1), e.g. list(x0 = "cons", x1 = "age").
x1_range	Vector with min and max values for time variable (in that order: e.g. c(12, 23) to range from 12 to 23).
design_matrices	List of five named lists, with each of the latter relating to a design matrix. These five lists are x_A (corresponding to X matrix (fixed part) of model for mean of y), z_A (Z matrix (random part) of model for mean of y), x_B (X matrix (fixed part) of model for level 1 variance function), z_B (Z matrix (random part) of model for level 1 variance function) and x_C (X matrix (fixed part) for model of distal outcome). Each of the first four lists (i.e. x_A, z_A, x_B and z_B) to contain two named logical vectors (x0 for intercept, x1 for time), indicating whether each variable to be included in design matrices or not; TRUE indicates variable to be included, FALSE otherwise. The last list (x_C) to contain up to four named logical vectors indicating whether constant (x0), and u2j terms (x1, x2, x3) to be included in model for distal outcome or not. E.g. list(x_A = list(x0 = TRUE, x1 = TRUE), z_A = list(x0 = TRUE, x1 = TRUE), x_B = list(x0 = TRUE, x1 = TRUE), z_B = list(x0 = TRUE, x1 = FALSE)) for each variable in each design matrix, bar time variable excluded from z_B. Note if gamma = NULL, x_C is set to NULL (i.e. no need to include x_C in design_matrices if do not wish to simulate distal outcome).
beta	Vector containing coefficients of fixed effects for model for mean of y, in order of x0, x1.
alpha	Vector containing coefficients of fixed effects for level 1 variance function, in order of x0, x1.
gamma	Vector containing coefficients of fixed effects for model of distal outcome, in order of x0, x1, x2, x3. Defaults to NULL.
distal_type	Character vector specifying type for distal outcome: either "Continuous" or "Binary"; defaults to NULL, i.e. assumes no distal outcome required.
sigma2e_distal	Residual variance of distal outcome (applies when distal_type = "Continuous" only).
sigma2u	Level 2 covariance matrix. E.g. matrix(c(93, 12, 2.5, 12, 3.8, 0.8, 2.5, 0.8, 0.4), nrow = 3) would correspond to the following: sigma2u00 (93), sigma2u01 (12), sigma2u02 (2.5), sigma2u01 (12), sigma2u11 (3.8), sigma2u12 (0.8), sigma2u02 (2.5), sigma2u12 (0.8), sigma2u22 (0.4).
log_sigma2e	Logical vector indicating whether log link used for level 1 variance function (TRUE) or not (FALSE); defaults to TRUE.
linear_sigma2e_attempts	Numerical vector (one element) corresponding to maximum number of attempts made to generate non-negative sigma2e (only applicable when log_sigma2e = FALSE); defaults to 10.
random_seed	Numerical vector indicating value of random seed to be set at outset.

Value

List containing simulated dataset (as simu_dataframe), plus other relevant generated objects and user-defined parameters.

Examples

## Not run: 
library(windsimu)

## Level 2 random effect in level 1 variance function
## with this term also allowed to covary with random
## intercept & random slope in level 2 covariance matrix:
simu_u2j_covary <- windsimu(
  sample_size = list(n2 = 1000, n1 = 9),
  var_names = list(x0 = "cons", x1 = "age"),
  x1_range = c(-1, 1),
  design_matrices = list(
    x_A = list(x0 = TRUE, x1 = TRUE),
    z_A = list(x0 = TRUE, x1 = TRUE),
    x_B = list(x0 = TRUE, x1 = TRUE),
    z_B = list(x0 = TRUE, x1 = FALSE)
  ),
  beta = c(150, 6.5),
  alpha = c(-.95, 0.48),
  sigma2u =
    matrix(
      c(93, 12, 2.5,
        12, 3.8, 0.8,
        2.5, 0.8, 0.4),
      nrow = 3,
      ncol = 3,
      byrow = TRUE
    ),
  log_sigma2e = TRUE,
  linear_sigma2e_attempts = 10,
  random_seed = 1
)

## inspect structure of returned object:
str(simu_u2j_covary)

## export simulated dataset (to current working directory) as .dta:
library(haven)
write_dta(simu_u2j_covary$simu_dataframe, "simu_u2j_covary.dta", version = 14)

## Level 2 random effect in level 1 variance function
## but covariance of this term set to 0 in level 2 covariance matrix:
simu_u2j_no_covary <- windsimu(
  sample_size = list(n2 = 1000, n1 = 9),
  var_names = list(x0 = "cons", x1 = "age"),
  x1_range = c(-1, 1),
  design_matrices = list(
    x_A = list(x0 = TRUE, x1 = TRUE),
    z_A = list(x0 = TRUE, x1 = TRUE),
    x_B = list(x0 = TRUE, x1 = TRUE),
    z_B = list(x0 = TRUE, x1 = FALSE)
  ),
  beta = c(150, 6.5),
  alpha = c(-.95, 0.48),
  sigma2u =
    matrix(
      c(93, 12, 0,
        12, 3.8, 0,
        0, 0, 0.4),
      nrow = 3,
      ncol = 3,
      byrow = TRUE
    ),
  log_sigma2e = TRUE,
  linear_sigma2e_attempts = 10,
  random_seed = 1
)


## No additional level 2 random effect:
simu_no_u2j <- windsimu(
  sample_size = list(n2 = 1000, n1 = 9),
  var_names = list(x0 = "cons", x1 = "age"),
  x1_range = c(-1, 1),
  design_matrices = list(
    x_A = list(x0 = TRUE, x1 = TRUE),
    z_A = list(x0 = TRUE, x1 = TRUE),
    x_B = list(x0 = TRUE, x1 = TRUE),
    z_B = list(x0 = FALSE, x1 = FALSE)
  ),
    beta = c(150, 6.5),
    alpha = c(-.95, 0.48),
    sigma2u =
      matrix(
        c(93, 12,
          12, 3.8),
        nrow = 2,
        ncol = 2,
        byrow = TRUE
      ),
    log_sigma2e = TRUE,
    linear_sigma2e_attempts = 10,
    random_seed = 1
  )


## No log link for level 1 variance function.
## Note age uncentred (level 1 variance function more likely
## to stay positive); also note linear_sigma2e_attempts:
simu_u2j_covary_linearL1varfun <- windsimu(
  sample_size = list(n2 = 1000, n1 = 9),
  var_names = list(x0 = "cons", x1 = "age"),
  x1_range = c(11.25, 13.25),
  design_matrices = list(
    x_A = list(x0 = TRUE, x1 = TRUE),
    z_A = list(x0 = TRUE, x1 = TRUE),
    x_B = list(x0 = TRUE, x1 = TRUE),
    z_B = list(x0 = TRUE, x1 = FALSE)
  ),
  beta = c(150, 6.5),
  alpha = c(-.95, 0.48),
  sigma2u =
    matrix(
      c(93, 12, 2.5,
        12, 3.8, 0.8,
        2.5, 0.8, 0.4),
      nrow = 3,
      ncol = 3,
      byrow = TRUE
    ),
  log_sigma2e = FALSE,
  linear_sigma2e_attempts = 100,
  random_seed = 1
)

## As simu_u2j_covary (above), but with distal outcome;
## note x_C in design_matrices, and gamma:
simu_u2j_covary_distal <- windsimu(
  sample_size = list(n2 = 1000, n1 = 9),
  var_names = list(x0 = "cons", x1 = "age"),
  x1_range = c(-1, 1),
  design_matrices = list(
    x_A = list(x0 = TRUE, x1 = TRUE),
    z_A = list(x0 = TRUE, x1 = TRUE),
    x_B = list(x0 = TRUE, x1 = TRUE),
    z_B = list(x0 = TRUE, x1 = FALSE),
    x_C = list(x0 = TRUE, x1 = TRUE, x2 = TRUE, x3 = TRUE)
  ),
  beta = c(150, 6.5),
  alpha = c(-.95, 0.48),
  gamma = c(0.5, 0.2, 0.7, 1.4),
  distal_type = "Continuous",
  sigma2e_distal = 1,
  sigma2u =
    matrix(
      c(93, 12, 2.5,
        12, 3.8, 0.8,
        2.5, 0.8, 0.4),
      nrow = 3,
      ncol = 3,
      byrow = TRUE
    ),
  log_sigma2e = TRUE,
  linear_sigma2e_attempts = 10,
  random_seed = 1
)

## End(Not run)

richmaparker/windsimu documentation built on May 29, 2019, 8:08 a.m.