DeclareDesign (version 0.18.0)

declare_reveal: Declare a reveal outcomes step

Description

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.

Usage

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

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.

Examples

Run this code
# NOT RUN {
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

# }

Run the code above in your browser using DataCamp Workspace