FSM (version 1.0.0)

fsm: 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

data_frame

A data frame containing a column of unit indices (optional) and covariates (or transformations thereof).

SOM

A selection order matrix.

s_function

Specifies a selection function, a string among 'constant', 'Dopt', 'Aopt', 'max pc', 'min pc', 'Dopt pc', 'max average', 'min average', 'Dopt average'. 'constant' selection function puts a constant value on every unselected unit. 'Dopt' use the D-optimality criteria based on the full set of covariates to select units. 'Aopt' uses the A-optimality criteria. 'max pc' (respectively, 'min pc') selects that unit that has the maximum (respectively, minimum) value of the first principal component. 'Dopt pc' uses the D-optimality criteria on the first principal component, 'max average' (respectively, 'min average') selects that unit that has the maximum (respectively, minimum) value of the simple average of the covariates. 'Dopt average' uses the D-optimality criteria on the simple average of the covariates.

Q_initial

A (optional) non-singular matrix (called 'initial matrix') that is added the \((X^T X)\) matrix of the choosing treatment group at any stage, when the \((X^T X)\) matrix of that treatment group at that stage is non-invertible. If FALSE, the \((X^T X)\) matrix for the full set of observations is used as the non-singular matrix. Applicable if s_function = 'Dopt' or 'Aopt'.

eps

Proportionality constant for Q_initial, the default value is 0.001.

ties

Specifies how to deal with ties in the values of the selection function. If ties = 'random', a unit is selected randomly from the set of candidate units. If ties = 'smallest', the unit that appears earlier in the data frame, i.e. the unit with the smallest index gets selected.

intercept

if TRUE, the design matrix of each treatment group includes a column of intercepts.

standardize

if TRUE, the columns of the \(X\) matrix other than the column for the intercept (if any), are standardized.

units_print

if TRUE, the function automatically prints the candidate units at each step of selection.

index_col

if TRUE, data_frame contains a column of unit indices.

Pol_mat

Policy matrix. Applicable only when s_function = 'Aopt'.

w_pol

A vector of policy weights. Applicable only when s_function = 'Aopt'.

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.

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<U+2013>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<U+2013>53.

Examples

# NOT RUN {
# 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)
# }