declare_estimand: Declare Estimand

Description Usage Arguments Details Value Examples

Description

Declares estimands which are the subjects of inquiry and can be estimated by an estimator

Usage

1
2
3
declare_estimand(..., handler = estimand_handler, label = "my_estimand")

estimand_handler(data, ..., subset = NULL, coefficients = FALSE, label)

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

subset

a subset expression

coefficients

TRUE/FALSE

Details

For the default diagnosands, the return value of the handler should have 'estimand_label' and 'estimand' columns.

If coefficients is TRUE, the names of ... will be returned in a 'coefficients' column, and 'estimand_label' will contain the step label. This can be used as an additional dimension for use in diagnosis.

Value

a function that accepts a data.frame as an argument and returns a data.frame containing the value of the estimand.

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
########################################################
# Default handler

my_estimand_ATE <- declare_estimand(ATE = mean(Y_Z_1 - Y_Z_0))

my_estimand_ATT <- declare_estimand(ATT = mean(Y_Z_1 - Y_Z_0), subset=Z==1)

# You can also use different coefficients from an model-based estimator for
# two estimands, with a slightly different syntax

# Name your estimands the coefficient name they get in your
# estimator, and set `coefficients = TRUE`

my_estimand_regression <- declare_estimand(
  `(Intercept)` = mean(Y_Z_0),
  `Z` = mean(Y_Z_1 - Y_Z_0),
  coefficients = TRUE,
  label="TrueRegressionParams"
)

########################################################
# Custom random assignment functions

my_estimand_function <- function(data, label) {
  ret <- with(data, median(Y_Z_1 - Y_Z_0))
  data.frame(estimand_label=label,
             estimand=ret,
             time=Sys.time(),
             stringsAsFactors=FALSE)
}
my_estimand_custom <- declare_estimand(handler = my_estimand_function, label = "medianTE")

########################################################
# Using with estimators


# First, set up the rest of a design for use below
set.seed(42)

design_stub <- declare_design(
  pop=declare_population(N = 100, X = rnorm(N)),
  po=declare_potential_outcomes(Y ~ (.25 + X) * Z + rnorm(N)),
  assn=declare_assignment(m = 50),
  reveal=declare_reveal()
)

# Get example data to compute estimands on
dat <- draw_data(design_stub)

# ----------
# 1. Single estimand
# ----------

# Use the default estimand setup to
# declare an average treatment effect estimand

my_estimand_ATE(dat)

my_estimator <- declare_estimator(Y ~ Z, estimand = my_estimand_ATE, label="estimator")

design_def <- insert_step(design_stub, my_estimand_ATE, before="assn")
design_def <- insert_step(design_def, my_estimator, after="reveal")

run_design(design_def)

# ----------
# 2. Multiple estimands
# ----------

# You can also specify multiple estimands at a time

# With multiple estimands, you can use one estimator for both...
my_estimator_two <- declare_estimator(Y ~ Z, estimand = c(my_estimand_ATE, my_estimand_ATT))

design_two <- insert_step(design_stub, my_estimand_ATE, before="assn")
design_two <- insert_step(design_two, my_estimand_ATT, after="assn")
design_two <- insert_step(design_two, my_estimator_two, after="reveal")

run_design(design_two)


# For the model based estimator, specify the estimand as usual,
# but also set `coefficients = TRUE`
my_estimator_double <- declare_estimator(
  Y ~ Z,
  estimand = my_estimand_regression,
  model = lm,
  coefficients = TRUE
)

design_double <- insert_step(design_stub, my_estimand_regression, after="po")
design_double <- insert_step(design_double, my_estimator_double, after="reveal")

run_design(design_double)

# ----------
# 3. Custom estimands
# ----------


my_estimand_custom(dat)

# Can also use custom estimator
my_estimator_function <- function(data){
  data.frame(est = with(data, median(Y)))
}
my_estimator_custom <-
  declare_estimator(handler = tidy_estimator(my_estimator_function),
                    estimand = my_estimand_custom)

design_cust <- insert_step(design_stub, my_estimand_custom, before="assn")
design_cust <- insert_step(design_cust, my_estimator_custom, after="reveal")

run_design(design_cust)

graemeblair/DeclareDesign documentation built on May 8, 2018, 1:24 p.m.