Declare a reveal outcomes step

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

...	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.

Details

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.

Examples

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