The Lalonde experimental dataset

Description

The Nationally Supported Work (NSW) experimental data set by Lalonde (1986).

References

LaLonde, R. J. (1986), “Evaluating the econometric evaluations of training programs with experimental data". The American Economic Review, pp. 604–620.

Dehejia, R., and Wahba, S. (1999), “Causal effects in nonexperimental studies: Reevaluating the evaluation of training programs", Journal of the American Statistical Association, 94(443), 1053–1062.

https://users.nber.org/~rdehejia/nswdata.html

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Completely Randomized Design (CRD)

Description

Generates an assignment under completely randomized design (CRD).

Usage

crd(data_frame, n_treat, treat_sizes, control = FALSE)

Arguments

Value

The original data frame augmented with the column of the treatment indicator.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R”.

Examples

# Consider N = 12, n1 = n2 = n3 = 4.
df_sample = data.frame(index = 1:12, x = c(20,30,40,40,50,60,20,30,40,40,50,60))
# Draw a random assignment from CRD.
fc = crd(data_frame = df_sample, n_treat = 3, treat_sizes = c(4,4,4))
# Get vector of treatment assignments.
Z_crd = fc$Treat

Model-based Effective Sample Size (ESS)

Description

Computes the model-based effective sample size (ESS) of a collection of assignments under a given set of potential outcomes.

Usage

ess_model(X_cov, assign_matrix, Y_mat, contrast = c(1, -1))

Arguments

Value

A vector of effective sample sizes for the given collection of assignments.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Examples

# Consider the Lalonde dataset.
# Get the full sample size.
N = nrow(Lalonde)
# Get the treatment group sizes.
n1 = floor(N/2)
n2 = N-n1
# Generate an SOM.
som_obs = som(n_treat = 2, treat_sizes = c(n1,n2),include_discard = FALSE,
method = 'SCOMARS', marginal_treat = rep((n2/N),N), control = FALSE)
# Generate a treatment assignment given som_obs.
f = fsm(data_frame = Lalonde, SOM = som_obs, s_function = 'Dopt', eps = 0.0001, 
ties = 'random', intercept = TRUE, standardize = TRUE, units_print = FALSE)
# Get assignment vector under the FSM.
Z_fsm_obs = f$data_frame_allocated$Treat
# Draw a random CRD.
Z_crd_obs = crd(data_frame = Lalonde, n_treat = 2, treat_sizes = c(n1, n2), 
control = FALSE)$Treat
Z_big = cbind(Z_crd_obs, Z_fsm_obs)
# Generate the potential outcomes.
Y_1 = 100 - Lalonde$Age + 6 * Lalonde$Education - 20 * Lalonde$Black + 
20 * Lalonde$Hispanic + 0.003 * Lalonde$Re75 + rnorm(N,0,4)
Y_1 = round(Y_1,2)
# Set unit level causal effect = tau = 0.
tau = 0
Y_2 = Y_1 + tau
# Get the matrix of potential outcomes.
Y_appended = cbind(Y_1, Y_2)
# Get the matrix of covariates.
X_cov = Lalonde[,-1]
ess = ess_model(X_cov = X_cov, assign_matrix = Z_big, Y_mat = Y_appended, contrast = c(1,-1))

Randomization-based Effective Sample Size (ESS)

Description

Computes the randomization-based effective sample size (ESS) of a collection of assignments under a given set of potential outcomes.

Usage

ess_rand(assign_array, Y_mat, contrast = c(1, -1))

Arguments

Value

A vector of effective sample sizes for the given collection of assignments.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Examples

# Consider N = 12, n1 = n2 = 6.
df_sample = data.frame(index = 1:12, x = c(20,30,40,40,50,60,20,30,40,40,50,60))
# Generate the potential outcomes.
Y_1 = 100 + (df_sample$x - mean(df_sample$x)) + rnorm(12, 0, 4)
Y_2 = Y_1 + 50
# Create matrix of potential outcomes.
Y_appended = cbind(Y_1, Y_2)
# Generate 100 assignments under CRD and the FSM.
Z_crd_iter = matrix(rep(0, 100 * 12), nrow = 100)
Z_fsm_iter = matrix(rep(0, 100 * 12), nrow = 100)
for(i in 1:100)
{
# Generate an assignment vector under CRD.
fc = crd(data_frame = df_sample, n_treat = 2, treat_sizes = c(6,6), control = FALSE)
Z_crd_iter[i,] = fc$Treat
# Generate an assignment vector under the FSM.
som_iter = som(data_frame = NULL, n_treat = 2, 
treat_sizes = c(6, 6),include_discard = FALSE,
method = 'SCOMARS', marginal_treat = rep((6/12), 12), control = FALSE)
f = fsm(data_frame = df_sample, SOM = som_iter, s_function = 'Dopt',eps = 0.0001, 
ties = 'random', intercept = TRUE, standardize = TRUE, units_print = FALSE)
Z_fsm_iter[i,] = f$data_frame_allocated$Treat
}
# Create a 3-dim array of assignments.
Z_array = array(0, dim = c(100, 12, 2))
Z_array[,,1] = Z_crd_iter
Z_array[,,2] = Z_fsm_iter
# Calculate the ESS.
ess_rand(assign_array = Z_array, Y_mat = Y_appended, contrast = c(1,-1))

Finite Selection Model (FSM)

Description

Generates a randomized assignment of a group of units to multiple groups of pre-determined sizes using the Finite Selection Model (FSM).

Usage

fsm(
  data_frame,
  SOM,
  s_function = "Dopt",
  Q_initial = NULL,
  eps = 0.001,
  ties = "random",
  intercept = TRUE,
  standardize = TRUE,
  units_print = TRUE,
  index_col = TRUE,
  Pol_mat = NULL,
  w_pol = NULL
)

Arguments

Value

A list containing the following items.

data_frame_allocated: The original data frame augmented with the column of the treatment indicator.

som_appended: The SOM with augmented columns for the indices and covariate values for units selected.

som_split: som_appended, split by the levels of the treatment.

crit_print: The value of the objective function, at each stage of build up process. At each stage, the unit that maximizes the objective function is selected.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R”.

Morris, C. (1979), “A finite selection model for experimental design of the health insurance study”, Journal of Econometrics, 11(1), 43–61.

Morris, C., Hill, J. (2000), “The health insurance experiment: design using the finite selection model”, Public policy and statistics: case studies from RAND, Springer Science & Business Media, 29–53.

Examples

# Load the data.
df_sample = data.frame(index = 1:12, x = c(20,30,40,40,50,60,20,30,40,40,50,60))
# Generate an SOM with N = 12, n1 = n2 = 6.
som_sample = som(n_treat = 2, treat_sizes = c(6,6), method = 'SCOMARS', control = TRUE, 
marginal_treat = rep(6/12,12))
# Assign units given the SOM.
f = fsm(data_frame = df_sample, SOM = som_sample, s_function = 'Dopt', 
eps = 0.001, ties = 'random', intercept = TRUE, standardize = TRUE, units_print = TRUE, 
index_col = TRUE)

Batched FSM for sequential experiments

Description

Extension of the FSM to cases where units arrive sequentially in batches.

Usage

fsm_batch(
  data_frame,
  data_frame_past,
  t_ind,
  SOM,
  s_function = "Dopt",
  Q_initial = NULL,
  eps = 0.001,
  ties = "random",
  intercept = TRUE,
  index_col_past = TRUE,
  standardize = TRUE,
  units_print = TRUE,
  index_col = TRUE,
  Pol_mat = NULL,
  w_pol = NULL
)

Arguments

Value

A list containing the following items.

data_frame_allocated: The original data frame augmented with the column of the treatment indicator.

som_appended: The SOM with augmented columns for the indices and covariate values for units selected.

som_split: som_appended, split by the levels of the treatment.

data_frame_allocated_augmented: data frame combining data_frame_allocated and data_frame_past.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R'.

Examples

# Consider N=18, number of treatments = 2, n1 = n2 = 9, batch sizes = 6,6,6.
# Get data frame for the first batch.
df_sample_1 = data.frame(index = 1:6, age = c(20,30,40,40,50,60))
# Obtain SOM for all the 12 units.
som_gen = som(data_frame = NULL, n_treat = 2, treat_sizes = c(9,9), 
include_discard = FALSE, method = 'SCOMARS', marginal_treat = rep((9/18),18), control = FALSE)
# Assign the first batch.
f1 = fsm(data_frame = df_sample_1, SOM = som_gen[1:6,], s_function = 'Dopt', 
eps = 0.0001, ties = 'random', intercept = TRUE, standardize = TRUE, units_print = TRUE)
f1_app = f1$data_frame_allocated
# Get data frame for the second batch.
df_sample_2 = data.frame(index = 7:12, age = c(20,30,40,40,50,60))
# Assign the second batch.
f2 = fsm_batch(data_frame = df_sample_2, SOM = som_gen[7:12,], s_function = 'Dopt', 
eps = 0.0001, ties = 'random', intercept = TRUE, standardize = TRUE, units_print = TRUE,
data_frame_past = f1_app, t_ind = 'Treat', index_col_past = TRUE)
f2_app = f2$data_frame_allocated_augmented
# Get data frame for the third batch.
df_sample_3 = data.frame(index = 13:18, age = c(20,30,40,40,50,60))
# Assign the third batch.
f3 = fsm_batch(data_frame = df_sample_3, SOM = som_gen[13:18,], s_function = 'Dopt', 
eps = 0.0001, ties = 'random', intercept = TRUE, standardize = TRUE, units_print = TRUE,
data_frame_past = f2_app, t_ind = 'Treat', index_col_past = TRUE)
f3_app = f3$data_frame_allocated_augmented

Love plot

Description

Generates a Love plot of Absolute Standardized Mean Differences (ASMD) or Target Absolute Standardized Differences (TASMD) between two groups under one or two designs.

Usage

love_plot(
  data_frame,
  index_col = TRUE,
  alloc1,
  alloc2 = NULL,
  imbalance = "TASMD",
  treat_lab = 1,
  vline = "",
  xupper = 1,
  mean_tar = NULL,
  sd_tar = NULL,
  denom = "target",
  legend_text = "FSM",
  legend_position = "topright"
)

Arguments

Value

Love plot of the ASMD/TASMD of the covariates.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Love, T. (2004), “Graphical display of covariate balance”, Presentation, See http://chrp.org/love/JSM2004RoundTableHandout.pdf, 1364.

Examples

# Consider the Lalonde dataset.
# Get the full sample size.
N = nrow(Lalonde)
# Get the treatment group sizes.
n1 = floor(N/2)
n2 = N-n1
# Generate an SOM.
som_obs = som(n_treat = 2, treat_sizes = c(n1,n2),include_discard = FALSE,
method = 'SCOMARS', marginal_treat = rep((n2/N),N), control = FALSE)
# Generate a treatment assignment given som_obs.
f = fsm(data_frame = Lalonde, SOM = som_obs, s_function = 'Dopt', eps = 0.0001, 
ties = 'random', intercept = TRUE, standardize = TRUE, units_print = FALSE)
# Get assignment vector under the FSM.
Z_fsm_obs = f$data_frame_allocated$Treat
# Draw a random CRD.
Z_crd_obs = crd(data_frame = Lalonde, n_treat = 2, treat_sizes = c(n1, n2), 
control = FALSE)$Treat
# Draw Love plot.
love_plot(data_frame = Lalonde, index_col = TRUE, alloc1 = Z_fsm_obs, alloc2 = Z_crd_obs, 
imbalance = 'TASMD', treat_lab = 1, mean_tar = NULL, sd_tar = NULL, denom = 'target',
vline = "", legend_text = c("FSM","CRD"), xupper = 0.15, legend_position = 'topright') 

Squares and two-way interactions of variables

Description

Generates squares and/or two-way interactions (pairwise products) of the columns of a data frame.

Usage

make_sq_inter(
  data_frame,
  is_square = TRUE,
  is_inter = TRUE,
  keep_marginal = TRUE
)

Arguments

Value

A data frame containing the squares and/or pairwise products of data_frame.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

Examples

# Consider a data frame with N = 12 units and 2 covariates.
data_frame_sample = data.frame(male = c(rep(1,6),rep(0,6)), 
age = c(20,30,40,40,50,60,20,30,40,40,50,60))
# Get a data frame with all possible squares and first order interactions.
make_sq_inter(data_frame = data_frame_sample, is_square = TRUE, 
is_inter = TRUE, keep_marginal = FALSE)

Fisher's randomization test for sharp null hypothesis.

Description

Performs Fisher's randomization test for sharp null hypotheses of the form H_0: c_1 Y_i(1) + c_2 Y_i(2) - \tau = 0, for a vector of contrasts (c_1, c_2).

Usage

perm_test(
  Y_obs,
  alloc_obs,
  alloc,
  contrast = c(1, -1),
  tau = 0,
  method = "marginal mean",
  alternative = "not equal"
)

Arguments

Value

A list containing the following items.

test_stat_obs: The observed value of the test statistic.

test_stat_iter: A vector of values of the test statistic across repeated randomizations.

p_value: p-value of the test.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Examples

# Consider N = 12, n1 = n2 = 6. 
# We test the sharp null of no treatment effect under CRD.
df_sample = data.frame(index = 1:12, x = c(20,30,40,40,50,60,20,30,40,40,50,60))
# True potential outcomes.
Y_1_true = 100 + (df_sample$x - mean(df_sample$x)) + rnorm(12, 0, 4)
Y_2_true = Y_1_true + 50
# Generate the realized assignment under CRD.
fc = crd(data_frame = df_sample, n_treat = 2, treat_sizes = c(6,6), control = FALSE)
Z_crd_obs = fc$Treat
# Get the observed outcomes
Y_obs = Y_1_true
Y_obs[Z_crd_obs == 2] = Y_2_true[Z_crd_obs == 2]
# Generate 1000 assignments under CRD.
Z_crd_iter = matrix(rep(0, 1000 * 12), nrow = 1000)
for(i in 1:1000)
{
fc = crd(data_frame = df_sample, n_treat = 2, treat_sizes = c(6,6), control = FALSE)
Z_crd_iter[i,] = fc$Treat
}
# Test for the sharp null H0: Y_i(1) = Y_i(0) for all i.
# Alternative: not H0 (two-sided test).
perm = perm_test(Y_obs = Y_obs, alloc_obs = Z_crd_obs, alloc = Z_crd_iter, 
contrast = c(1,-1), tau = 0, method = "marginal mean", alternative = 'not equal')
# Obtain the p-value.
perm$p_value

Selection Order Matrix (SOM)

Description

Generates a Selection Order Matrix (SOM) in a deterministic/random manner.

Usage

som(
  data_frame = NULL,
  n_treat,
  treat_sizes,
  include_discard = FALSE,
  method = "SCOMARS",
  control = FALSE,
  marginal_treat = NULL
)

Arguments

Value

A data frame containing the selection order of treatments, i.e. the labels of treatment groups at each stage of selection. If method = 'SCOMARS', the data frame contains an additional column of the conditional selection probabilities.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R”.

Morris, C. (1983), “Sequentially controlled Markovian random sampling (SCOMARS)”, Institute of Mathematical Statistics Bulletin,12(5), 237.

Examples

# Generate an SOM with N = 12, n1 = n2 = 6.
som_sample = som(data_frame = NULL, n_treat = 2, treat_sizes = c(6,6), include_discard = FALSE, 
method = 'SCOMARS', control = FALSE, marginal_treat = rep(6/12,12))

Target Absolute Standardized Mean Differences (TASMD)

Description

Computes the mean and standard deviation of Target Absolute Standardized Mean Differences (TASMD) of multiple covariates (or transformations thereof) in a treatment group relative to a target population or a target individual for a set of assignments under one or two designs.

Usage

tasmd_rand(
  data_frame,
  index_col = FALSE,
  alloc1,
  alloc2,
  treat_lab = 1,
  legend = c("CRD", "FSM"),
  mean_tar = NULL,
  sd_tar = NULL,
  denom = "target",
  roundoff = 3
)

Arguments

Value

A list containing the following items (if alloc1 and alloc2 are matrices)

tasmd_table: A matrix containing the means (standard deviations in parenthesis) of the TASMDs for the designs under consideration. If alloc1 or alloc2 is a vector, the TASMD of the corresponding assignment is returned.

tasmd_mean: A matrix containing the means of the TASMDs for the designs under consideration.

tasmd_sd: A matrix containing the standard deviations of the TASMDs for the designs under consideration.

If alloc1 and alloc2 are vectors, tasmd_rand produces a data frame of the corresponding TASMDs.

Author(s)

Ambarish Chattopadhyay, Carl N. Morris and Jose R. Zubizarreta.

References

Chattopadhyay, A., Morris, C. N., and Zubizarreta, J. R. (2020), “Randomized and Balanced Allocation of Units into Treatment Groups Using the Finite Selection Model for R".

Examples

# Consider the Lalonde dataset.
# Get the full sample size.
N = nrow(Lalonde)
# Get the treatment group sizes.
n1 = floor(N/2)
n2 = N-n1
# Generate an SOM.
som_obs = som(n_treat = 2, treat_sizes = c(n1,n2),include_discard = FALSE,
method = 'SCOMARS', marginal_treat = rep((n2/N),N), control = FALSE)
# Generate a treatment assignment given som_obs.
f = fsm(data_frame = Lalonde, SOM = som_obs, s_function = 'Dopt', eps = 0.0001, 
ties = 'random', intercept = TRUE, standardize = TRUE, units_print = FALSE)
# Get assignment vector under the FSM.
Z_fsm_obs = f$data_frame_allocated$Treat
# Draw a random CRD.
Z_crd_obs = crd(data_frame = Lalonde, n_treat = 2, treat_sizes = c(n1, n2), 
control = FALSE)$Treat
# Calculate the TASMD.
TASMD = tasmd_rand(data_frame = Lalonde, index_col = TRUE, alloc1 = Z_crd_obs, 
alloc2 = Z_fsm_obs, treat_lab = 1, mean_tar = NULL, sd_tar = NULL, 
denom = 'target', legend = c('CRD','FSM'), roundoff = 3)