add_level: Fabricate data

Description

fabricate helps you simulate a dataset before you collect it. You can either start with your own data and add simulated variables to it (by passing data to fabricate()) or start from scratch by defining N. Create hierarchical data with multiple levels of data such as citizens within cities within states using add_level() or modify existing hierarchical data using modify_level(). You can use any R function to create each variable. Use cross_levels() and link_levels() to make more complex designs such as panel or cross-classified data.

Usage

add_level(N = NULL, ..., nest = TRUE)
fabricate(data = NULL, ..., N = NULL, ID_label = NULL)
modify_level(N = NULL, ...)
nest_level(N = NULL, ...)

Arguments

(optional) number of units to draw. If provided as fabricate(N = 5), this determines the number of units in the single-level data. If provided in add_level, e.g. fabricate(cities = add_level(N = 5)), N determines the number of units in a specific level of a hierarchical dataset.

...

Variable or level-generating arguments, such as my_var = rnorm(N). For fabricate, you may also pass add_level() or modify_level() arguments, which define a level of a multi-level dataset. See examples.

nest

(Default TRUE) Boolean determining whether data in an add_level() call will be nested under the current working data frame or create a separate hierarchy of levels. See our vignette for cross-classified, non-nested data for details.

data

(optional) user-provided data that forms the basis of the fabrication, e.g. you can add variables to existing data. Provide either N or data (N is the number of rows of the data if data is provided).

ID_label

(optional) variable name for ID variable, e.g. citizen_ID

Value

data.frame

Details

We also provide several built-in options to easily create variables, including draw_binary, draw_count, draw_likert, and intra-cluster correlated variables draw_binary_icc and draw_normal_icc

Examples

Run this code

# NOT RUN {

# Draw a single-level dataset with a covariate
building_df <- fabricate(
  N = 100,
  height_ft = runif(N, 300, 800)
)
head(building_df)

# Start with existing data instead
building_modified <- fabricate(
  data = building_df,
  rent = rnorm(N, mean = height_ft * 100, sd = height_ft * 30)
)

# Draw a two-level hierarchical dataset
# containing cities within regions
multi_level_df <- fabricate(
 regions = add_level(N = 5),
 cities = add_level(N = 2, pollution = rnorm(N, mean = 5)))
head(df)

# Start with existing data and add a nested level:
company_df <- fabricate(
 data = building_df,
 company_id = add_level(N=10, is_headquarters = sample(c(0, 1), N, replace=TRUE))
)

# Start with existing data and add variables to hierarchical data
# at levels which are already present in the existing data.
# Note: do not provide N when adding variables to an existing level
modified_multi_level_df <- fabricate(
  data = multi_level_df,
  regions = modify_level(watershed = sample(c(0, 1), N, replace = TRUE)),
  cities = modify_level(runoff = rnorm(N))
)

# fabricatr can also make panel or cross-classified data. For more
# information about syntax for this functionality please read our vignette
# or check documentation for \code{link_levels}:
cross_classified <- fabricate(
  primary_schools = add_level(N = 50, ps_quality = runif(N, 0, 10)),
  secondary_schools = add_level(N = 100, ss_quality = runif(N, 0, 10), nest=FALSE),
  students = link_levels(N = 2000,
                          by=join(ps_quality, ss_quality, rho = 0.5),
                          student_quality = ps_quality + 3*ss_quality + rnorm(N)))
# }