declare_reveal: Declare a reveal outcomes step
In DeclareDesign/ddoldversion: Declare and Diagnose Research Designs

Description Usage Arguments Details Examples

Potential outcomes declarations indicate what outcomes would obtain for different possible values of assignment variables. To reveal actual outcomes we combine assignments with potential outcomes. declare_reveal provides information on how this revelation should be implemented, identifying the relevant assignment variables (for example created by declare_assignment) and outcome variables. 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 though explicit revelation is recommended.

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.

declare_reveal 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 declare_reveal 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 <- declare_reveal()

design <- my_population +
  my_potential_outcomes +
  my_assignment +
  my_reveal

design

#  Here the + operator results in the same design being
#  created, because it automatically adds a declare_reveal 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     <- declare_reveal(outcome_variables = c("Y1", "Y2"), assignment_variables = "Z")
reveal_2     <- declare_reveal(outcome_variables = "Y3", assignment_variables = c("X", "Z"))

# Note here that the reveal cannot be done in one step, e.g. by using
# declare_reveal(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.

# declare_reveal 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 <- declare_reveal(outcome_variables = "R")
reveal_outcomes <- declare_reveal(outcome_variables = "Y", attrition_variables = "R")

my_design <- population + potential_outcomes_Y + potential_outcomes_attrition + 
  my_assignment + reveal_attrition + reveal_outcomes