declare_estimand: Declare estimand

Description Usage Arguments Details Value Examples

Description

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

Usage

1
2
3
4
5
declare_estimand(..., handler = estimand_handler, label = "estimand")

declare_estimands(..., handler = estimand_handler, label = "estimand")

estimand_handler(data, ..., subset = NULL, term = 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

term

TRUE/FALSE

Details

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

If term is TRUE, the names of ... will be returned in a 'term' 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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# Set up a design stub for use in examples:

my_population  <- declare_population(N = 100, X = rnorm(N))
my_potential_outcomes  <- declare_potential_outcomes(
  Y ~ (.25 + X) * Z + rnorm(N))
my_assignment  <- declare_assignment(m = 50)
design_stub <- my_population + my_potential_outcomes + my_assignment + 
  declare_reveal()

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

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

# Declare an average treatment effect (ATE) estimand

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

# or a conditional estimand

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

# Add estimands to a design along with estimators that reference them

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

design_one <- design_stub + my_estimand_ATE + my_estimator

get_estimands(design_one)

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

# You can also specify multiple estimands for a single estimator 

# 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 <- design_stub + my_estimand_ATE + 
  my_estimand_ATT + my_estimator_two

get_estimands(design_two)

# ----------
# 3. Paired estimands / estimators from a single model
# ----------

# For convenience you can also declare multiple estimands
# simultaneously and connect these to the corresponding 
# terms for estimates used in the mode. 

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

estimands_regression <- declare_estimand(
  `(Intercept)` = mean(Y_Z_0),
  `Z` = mean(Y_Z_1 - Y_Z_0),
  term = TRUE,
  label="Regression_Estimands"
)

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

design_regression <- design_stub + estimands_regression +
  estimators_regression

run_design(design_regression)

# ----------
# 4. Custom estimand function
# ----------

# You can declare more complex estimands by defining custom
# estimand functions:

estimand_function <- function(data, label) {
  ret <- with(data, median(Y_Z_1 - Y_Z_0))
  data.frame(estimand_label = label,
             estimand = ret,
             stringsAsFactors = FALSE)
}

estimand_custom <- declare_estimand(handler = estimand_function,
  label = "medianTE")

estimand_custom(dat)

# Use with custom estimators
estimator_function <- function(data){
  data.frame(estimate = with(data, median(Y)))
}
estimator_custom <-
  declare_estimator(handler = tidy_estimator(estimator_function),
                    estimand = estimand_custom)

design_custom <- design_stub + estimand_custom +
  estimator_custom

run_design(design_custom)

# ----------
# 5. Batch estimands and estimators
# ----------

# You can declare a group of estimands with distinct labels
# in one go and link them manually to a group of estimators.
# In this case you can add a \code{term} argument to the 
# custom estimators to identify them.

f1 <- function(data) {
  data.frame(estimand_label = c("control", "ate"),
             estimand = with(data, c(mean(Y_Z_0), mean(Y_Z_1 - Y_Z_0))),
             stringsAsFactors = FALSE)
}
estimands <- declare_estimand(handler = f1)

f2 <- function(data) data.frame(estimate = with(data,
                            c(mean(Y[Z == 0]),
                            mean(Y[Z == 1]) - mean(Y[Z == 0]))),
                            term = 1:2)

estimators <- declare_estimator(handler = tidy_estimator(f2), 
                            estimand = c("control", "ate"), label = "custom")
                            
design      <- design_stub + estimands + estimators

diagnose_design(design, sims = 20,
                diagnosands = declare_diagnosands(
                select = c(mean_estimate, mean_estimand)))

graemeblair/DeclareDesign documentation built on Aug. 9, 2018, 12:38 p.m.