A random assignment procedure in which units are assigned as clusters and clusters are nested within blocks.

block_and_cluster_ra(block_var, clust_var, prob = NULL, prob_each = NULL,
m = NULL, block_m = NULL, block_m_each = NULL, block_prob = NULL,
block_prob_each = NULL, num_arms = NULL, condition_names = NULL,
check_inputs = TRUE)

## Arguments

block_var A vector of length N that indicates which block each unit belongs to. A vector of length N that indicates which cluster each unit belongs to. Use for a two-arm design in which either floor(N_clusters_block*prob) or ceiling(N_clusters_block*prob) clusters are assigned to treatment within each block. The probability of assignment to treatment is exactly prob because with probability 1-prob, floor(N_clusters_block*prob) clusters will be assigned to treatment and with probability prob, ceiling(N_clusters_block*prob) clusters will be assigned to treatment. prob must be a real number between 0 and 1 inclusive. (optional) Use for a multi-arm design in which the values of prob_each determine the probabilties of assignment to each treatment condition. prob_each must be a numeric vector giving the probability of assignment to each condition. All entries must be nonnegative real numbers between 0 and 1 inclusive and the total must sum to 1. Because of integer issues, the exact number of clusters assigned to each condition may differ (slightly) from assignment to assignment, but the overall probability of assignment is exactly prob_each. (optional) Use for a two-arm design in which the scalar m describes the fixed number of clusters assigned in each block. This number does not vary across blocks. Use for a two-arm design in which block_m describes the number of clusters to assign to treatment within each block. Note that in previous versions of randomizr, block_m behaved like block_m_each. Use for a multi-arm design in which the values of block_m_each determine the number of clusters assigned to each condition. block_m_each must be a matrix with the same number of rows as blocks and the same number of columns as treatment arms. Cell entries are the number of clusters to be assigned to each treatment arm within each block. The rows should respect the ordering of the blocks as determined by sort(unique(block_var)). The columns should be in the order of condition_names, if specified. Use for a two-arm design in which block_prob describes the probability of assignment to treatment within each block. Differs from prob in that the probability of assignment can vary across blocks. Use for a multi-arm design in which the values of block_prob_each determine the probabilties of assignment to each treatment condition. block_prob_each must be a matrix with the same number of rows as blocks and the same number of columns as treatment arms. Cell entries are the probabilites of assignment to treatment within each block. The rows should respect the ordering of the blocks as determined by sort(unique(block_var)). Use only if the probabilities of assignment should vary by block, otherwise use prob_each. Each row of block_prob_each must sum to 1. The number of treatment arms. If unspecified, num_arms will be determined from the other arguments. (optional) A character vector giving the names of the treatment groups. If unspecified, the treatment groups will be named 0 (for control) and 1 (for treatment) in a two-arm trial and T1, T2, T3, in a multi-arm trial. An execption is a two-group design in which num_arms is set to 2, in which case the condition names are T1 and T2, as in a multi-arm trial with two arms. (optional) logical. Defaults to TRUE.

## Value

A vector of length N that indicates the treatment condition of each unit.

## Examples

clust_var <- rep(letters, times=1:26)

block_var <- rep(NA, length(clust_var))
block_var[clust_var %in% letters[1:5]] <- "block_1"
block_var[clust_var %in% letters[6:10]] <- "block_2"
block_var[clust_var %in% letters[11:15]] <- "block_3"
block_var[clust_var %in% letters[16:20]] <- "block_4"
block_var[clust_var %in% letters[21:26]] <- "block_5"

table(block_var, clust_var)#>          clust_var
#> block_var  a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w
#>   block_1  1  2  3  4  5  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0
#>   block_2  0  0  0  0  0  6  7  8  9 10  0  0  0  0  0  0  0  0  0  0  0  0  0
#>   block_3  0  0  0  0  0  0  0  0  0  0 11 12 13 14 15  0  0  0  0  0  0  0  0
#>   block_4  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 16 17 18 19 20  0  0  0
#>   block_5  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0  0 21 22 23
#>          clust_var
#> block_var  x  y  z
#>   block_1  0  0  0
#>   block_2  0  0  0
#>   block_3  0  0  0
#>   block_4  0  0  0
#>   block_5 24 25 26
Z <- block_and_cluster_ra(block_var = block_var,
clust_var = clust_var)

table(Z, block_var)#>    block_var
#> Z   block_1 block_2 block_3 block_4 block_5
#>   0       8      16      24      37      72
#>   1       7      24      41      53      69table(Z, clust_var)#>    clust_var
#> Z    a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w  x  y
#>   0  0  0  3  0  5  6  0  0  0 10 11  0 13  0  0  0 17  0  0 20  0  0 23 24 25
#>   1  1  2  0  4  0  0  7  8  9  0  0 12  0 14 15 16  0 18 19  0 21 22  0  0  0
#>    clust_var
#> Z    z
#>   0  0
#>   1 26
Z <- block_and_cluster_ra(block_var = block_var,
clust_var = clust_var,
num_arms = 3)

table(Z, block_var)#>     block_var
#> Z    block_1 block_2 block_3 block_4 block_5
#>   T1       4      19      26      19      43
#>   T2       9      14      26      55      49
#>   T3       2       7      13      16      49table(Z, clust_var)#>     clust_var
#> Z     a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w  x  y
#>   T1  0  0  0  4  0  0  0  0  9 10  0 12  0 14  0  0  0  0 19  0 21 22  0  0  0
#>   T2  1  0  3  0  5  6  0  8  0  0 11  0  0  0 15  0 17 18  0 20  0  0 23  0  0
#>   T3  0  2  0  0  0  0  7  0  0  0  0  0 13  0  0 16  0  0  0  0  0  0  0 24 25
#>     clust_var
#> Z     z
#>   T1  0
#>   T2 26
#>   T3  0
Z <- block_and_cluster_ra(block_var = block_var,
clust_var = clust_var,
prob_each = c(.2, .5, .3))

block_m_each <- rbind(c(2, 3),
c(1, 4),
c(3, 2),
c(2, 3),
c(5, 1))

Z <- block_and_cluster_ra(block_var = block_var,
clust_var = clust_var,
block_m_each = block_m_each)

table(Z, block_var)#>    block_var
#> Z   block_1 block_2 block_3 block_4 block_5
#>   0       5       9      40      37     118
#>   1      10      31      25      53      23table(Z, clust_var)#>    clust_var
#> Z    a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p  q  r  s  t  u  v  w  x  y
#>   0  1  0  0  4  0  0  0  0  9  0  0 12 13  0 15  0  0 18 19  0 21 22  0 24 25
#>   1  0  2  3  0  5  6  7  8  0 10 11  0  0 14  0 16 17  0  0 20  0  0 23  0  0
#>    clust_var
#> Z    z
#>   0 26
#>   1  0