Skip to contents

Declare Data Strategy: Assignment

Usage

declare_assignment(..., handler = assignment_handler, label = NULL)

assignment_handler(data, ..., legacy = FALSE)

Arguments

...

arguments to be captured, and later passed to the handler

handler

a tidy-in, tidy-out function

label

a string describing the step

data

A data.frame.

legacy

Use the legacy randomizr functionality. This will be disabled in future; please use legacy = FALSE.

Value

A function that takes a data.frame as an argument and returns a data.frame with assignment columns appended.

Examples

# declare_assignment in use
## Two-arm randomized experiment
design <-
  declare_model(
    N = 500,
    X = rep(c(0, 1), each = N / 2),
    U = rnorm(N, sd = 0.25),
    potential_outcomes(Y ~ 0.2 * Z + X + U)
  ) +
  declare_inquiry(ATE = mean(Y_Z_1 - Y_Z_0)) +
  declare_sampling(S = complete_rs(N = N, n = 200)) +
  declare_assignment(Z = complete_ra(N = N, m = 100)) +
  declare_measurement(Y = reveal_outcomes(Y ~ Z)) +
  declare_estimator(Y ~ Z, inquiry = "ATE")
  
run_design(design)
#>   inquiry estimand estimator term  estimate  std.error statistic      p.value
#> 1     ATE      0.2 estimator    Z 0.3541076 0.07808441  4.534933 9.969412e-06
#>    conf.low conf.high  df outcome
#> 1 0.2001238 0.5080914 198       Y

# Set up population to assign
model <- declare_model(
  villages = add_level(
    N = 30, 
    N_households = sample(c(50:100), N, replace = TRUE)
  ),
  households = add_level(
    N = N_households, 
    N_members = sample(c(1, 2, 3, 4), N, 
                       prob = c(0.2, 0.3, 0.25, 0.25), replace = TRUE)
  ),
  individuals = add_level(
    N = N_members, 
    age = sample(18:90, N, replace = TRUE),
    gender = rbinom(n = N, size = 1, prob = .5)
  )
)

# Assignment procedures
## Complete random assignment
design <-
  model +
  declare_assignment(Z = complete_ra(N = N, m = 1000))
  
head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z
#> 1       01           51       0001         2        0001  75      0 0
#> 2       01           51       0001         2        0002  45      0 0
#> 3       01           51       0002         2        0003  80      1 0
#> 4       01           51       0002         2        0004  59      0 0
#> 5       01           51       0003         4        0005  80      0 0
#> 6       01           51       0003         4        0006  54      1 0

## Cluster random assignment
design <-
  model +
  declare_assignment(Z = cluster_ra(clusters = villages,
                                    n = 15))
                                    
head(draw_data(design))
#>   villages N_households households N_members individuals age gender  Z
#> 1       01           56       0001         4        0001  66      1 T6
#> 2       01           56       0001         4        0002  45      0 T6
#> 3       01           56       0001         4        0003  50      1 T6
#> 4       01           56       0001         4        0004  36      1 T6
#> 5       01           56       0002         2        0005  59      1 T6
#> 6       01           56       0002         2        0006  76      0 T6

## Block and cluster random assignment
design <-
  model +
  declare_assignment(Z  = block_and_cluster_ra(
    blocks = villages,
    clusters = households,
    block_m = rep(20, 30)
  ))

head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z
#> 1       01           92       0001         4        0001  57      0 0
#> 2       01           92       0001         4        0002  43      0 0
#> 3       01           92       0001         4        0003  29      1 0
#> 4       01           92       0001         4        0004  64      0 0
#> 5       01           92       0002         4        0005  59      1 0
#> 6       01           92       0002         4        0006  88      1 0

## Block random assignment
design <-
  model +
  declare_assignment(Z = block_ra(blocks = gender, m = 100))
  
head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z
#> 1       01           94       0001         4        0001  73      1 0
#> 2       01           94       0001         4        0002  26      1 0
#> 3       01           94       0001         4        0003  28      0 0
#> 4       01           94       0001         4        0004  49      1 0
#> 5       01           94       0002         1        0005  24      1 0
#> 6       01           94       0003         2        0006  57      1 0

## Block random assignment using probabilities
design <-
  model +
  declare_assignment(Z = block_ra(blocks = gender,
                                  block_prob = c(1 / 3, 2 / 3)))

head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z
#> 1       01           65       0001         4        0001  32      1 1
#> 2       01           65       0001         4        0002  64      1 1
#> 3       01           65       0001         4        0003  22      1 1
#> 4       01           65       0001         4        0004  81      0 0
#> 5       01           65       0002         2        0005  75      0 1
#> 6       01           65       0002         2        0006  73      1 1

## Factorial assignment
design <-
  model +
  declare_assignment(Z1 = complete_ra(N = N, m = 100),
                     Z2 = block_ra(blocks = Z1))

head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z1 Z2
#> 1       01           97       0001         4        0001  88      1  0  1
#> 2       01           97       0001         4        0002  76      1  0  1
#> 3       01           97       0001         4        0003  43      0  0  1
#> 4       01           97       0001         4        0004  58      0  0  1
#> 5       01           97       0002         2        0005  79      1  0  1
#> 6       01           97       0002         2        0006  52      0  0  0

## Assignment using functions outside of randomizr
design <-
  model +
  declare_assignment(Z = rbinom(n = N, size = 1, prob = 0.35))

head(draw_data(design))
#>   villages N_households households N_members individuals age gender Z
#> 1       01           57       0001         3        0001  21      0 0
#> 2       01           57       0001         3        0002  19      1 0
#> 3       01           57       0001         3        0003  65      1 0
#> 4       01           57       0002         1        0004  90      1 0
#> 5       01           57       0003         3        0005  89      0 0
#> 6       01           57       0003         3        0006  70      1 0