Potential outcomes declarations indicate what outcomes would obtain for different possible values of assignment variables.
But realized outcomes need to be "revealed."
reveal_outcomes
generates these realized outcomes using information on
potential outcomes (for instance generated via declare_potential_outcomes
) and the relevant
assignment variables (for example created by declare_assignment
).
Revelation steps are usefully included after declaration of all assignments of conditions required to determine the realized outcome.
If a revelation is not declared, DeclareDesign will try to guess appropriate revelations. Explicit revelation is recommended however.
reveal_outcomes(..., handler = reveal_outcomes_handler, label = NULL) declare_reveal(..., handler = reveal_outcomes_handler, label = NULL) reveal_outcomes_handler( data = NULL, outcome_variables = Y, assignment_variables = Z, attrition_variables = NULL, ... )
... | 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 containing columns for assignment and potential outcomes. |
outcome_variables | The outcome prefix(es) of the potential outcomes. |
assignment_variables | Unquoted name(s) of the assignment variable(s). |
attrition_variables | Unquoted name of the attrition variable. |
This function was previously called declare_reveal
. You can still use either one.
reveal_outcomes
declares how outcomes should be realized.
A "revelation" uses the random assignment to pluck out the correct potential outcomes (Gerber and Green 2012, Chapter 2).
If you create a simple design (with assignment variable Z and outcome variable Y) with the + operator but omit a reveal declaration, DeclareDesign will attempt to insert a revelation step automatically.
If you have multiple outcomes to reveal or different names for the outcome or assignment variables, use reveal_outcomes
to customize which outcomes are revealed.
Revelation requires that every named outcome variable is a function of every named assignment variable within a step. Thus if multiple outcome variables depend on different assignment variables, multiple revelations are needed.
my_population <- declare_population(N = 100, noise = rnorm(N)) my_potential_outcomes <- declare_potential_outcomes( Y_Z_0 = noise, Y_Z_1 = noise + rnorm(N, mean = 2, sd = 2)) my_assignment <- declare_assignment(m = 50) my_reveal <- reveal_outcomes() design <- my_population + my_potential_outcomes + my_assignment + my_reveal design#> #> Design Summary #> #> Step 1 (population): declare_population(N = 100, noise = rnorm(N)) ------------- #> #> N = 100 #> #> Added variable: ID #> N_missing N_unique class #> 0 100 character #> #> Added variable: noise #> min median mean max sd N_missing N_unique #> -2.83 -0.2 -0.26 2.04 1.07 0 100 #> #> Step 2 (potential outcomes): declare_potential_outcomes(Y_Z_0 = noise, Y_Z_1 = noise + rnorm(N, mean = 2, sd = 2)) #> #> Added variable: Y_Z_0 #> min median mean max sd N_missing N_unique #> -2.83 -0.2 -0.26 2.04 1.07 0 100 #> #> Added variable: Y_Z_1 #> min median mean max sd N_missing N_unique #> -4.23 1.44 1.53 7.1 2.18 0 100 #> #> Step 3 (assignment): declare_assignment(m = 50) -------------------------------- #> #> Added variable: Z #> 0 1 #> 50 50 #> 0.50 0.50 #> #> Added variable: Z_cond_prob #> 0.5 #> 100 #> 1.00 #> #> Step 4 (reveal): reveal_outcomes() --------------------------------------------- #> #> Added variable: Y #> min median mean max sd N_missing N_unique #> -4.23 0.32 0.65 7.1 2.2 0 100 #># Here the + operator results in the same design being # created, because it automatically adds a reveal_outcomes step. design <- my_population + my_potential_outcomes + my_assignment # Declaring multiple assignment variables or multiple outcome variables population <- declare_population(N = 10) potentials_1 <- declare_potential_outcomes(Y1 ~ Z) potentials_2 <- declare_potential_outcomes(Y2 ~ 1 + 2*Z) potentials_3 <- declare_potential_outcomes(Y3 ~ 1 - X*Z, conditions = list(X = 0:1, Z = 0:1)) assignment_Z <- declare_assignment(assignment_variable = "Z") assignment_X <- declare_assignment(assignment_variable = "X") reveal_1 <- reveal_outcomes(outcome_variables = c("Y1", "Y2"), assignment_variables = "Z") reveal_2 <- reveal_outcomes(outcome_variables = "Y3", assignment_variables = c("X", "Z")) # Note here that the reveal cannot be done in one step, e.g. by using # reveal_outcomes(outcome_variables = c("Y1", "Y2", "Y3"), # assignment_variables = c("X","Z")) # The reason is that in each revelation all outcome variables should be a # function of all assignment variables. # reveal_outcomes can also be used to declare outcomes that include attrition population <- declare_population(N = 100, age = sample(18:95, N, replace = TRUE)) potential_outcomes_Y <- declare_potential_outcomes(Y ~ .25 * Z + .01 * age * Z) assignment <- declare_assignment(m = 25) potential_outcomes_attrition <- declare_potential_outcomes(R ~ rbinom(n = N, size = 1, prob = pnorm(Y_Z_0))) reveal_attrition <- reveal_outcomes(outcome_variables = "R") reveal_outcomes <- reveal_outcomes(outcome_variables = "Y", attrition_variables = "R") my_design <- population + potential_outcomes_Y + potential_outcomes_attrition + my_assignment + reveal_attrition + reveal_outcomes