forked from kwonsang/CRE
-
Notifications
You must be signed in to change notification settings - Fork 5
/
cre.html
246 lines (202 loc) · 18.4 KB
/
cre.html
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><meta name="description" content="Performs the Causal Rule Ensemble on a data set with a response variable,
a treatment variable, and various features."><title>Causal rule ensemble — cre • CRE</title><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.2.2/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.2.2/bootstrap.bundle.min.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- bootstrap-toc --><script src="https://cdn.jsdelivr.net/gh/afeld/bootstrap-toc@v1.0.1/dist/bootstrap-toc.min.js" integrity="sha256-4veVQbu7//Lk5TSmc7YV48MxtMy98e26cf5MrgZYnwo=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- search --><script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.4.6/fuse.js" integrity="sha512-zv6Ywkjyktsohkbp9bb45V6tEMoWhzFzXis+LrMehmJZZSys19Yxf1dopHx7WzIKxr5tK2dVcYmaCk2uqdjF4A==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/0.38.0/autocomplete.jquery.min.js" integrity="sha512-GU9ayf+66Xx2TmpxqJpliWbT5PiGYxpaG8rfnBEk1LL8l1KGkRShhngwdXK1UgqhAzWpZHSiYPc09/NwDQIGyg==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/mark.min.js" integrity="sha512-5CYOlHXGh6QpOFA/TeTylKLWfB3ftPsde7AnmhuitiTX4K5SqCLBeKro6sPS8ilsz1Q4NRx3v8Ko2IBiszzdww==" crossorigin="anonymous"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Causal rule ensemble — cre"><meta property="og:description" content="Performs the Causal Rule Ensemble on a data set with a response variable,
a treatment variable, and various features."><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body>
<a href="#main" class="visually-hidden-focusable">Skip to contents</a>
<nav class="navbar fixed-top navbar-dark navbar-expand-lg bg-primary"><div class="container">
<a class="navbar-brand me-2" href="../index.html">CRE</a>
<small class="nav-text text-muted me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="">0.2.6</small>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div id="navbar" class="collapse navbar-collapse ms-3">
<ul class="navbar-nav me-auto"><li class="nav-item">
<a class="nav-link" href="../articles/CRE.html">Get started</a>
</li>
<li class="active nav-item">
<a class="nav-link" href="../reference/index.html">Reference</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle" data-bs-toggle="dropdown" role="button" aria-expanded="false" aria-haspopup="true" id="dropdown-articles">Articles</a>
<div class="dropdown-menu" aria-labelledby="dropdown-articles">
<h6 class="dropdown-header" data-toc-skip>Users</h6>
<div class="dropdown-divider"></div>
<h6 class="dropdown-header" data-toc-skip>Developers</h6>
<a class="dropdown-item" href="../articles/Contribution.html">Contribution</a>
<a class="dropdown-item" href="../articles/Testing-the-Package.html">Testing the CRE Package</a>
</div>
</li>
<li class="nav-item">
<a class="nav-link" href="../news/index.html">Changelog</a>
</li>
</ul><form class="form-inline my-2 my-lg-0" role="search">
<input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../search.json" id="search-input" placeholder="Search for" autocomplete="off"></form>
<ul class="navbar-nav"><li class="nav-item">
<a class="nav-link" href="https://github.com/NSAPH-Software/CRE/" aria-label="github">
<span class="fab fa fab fa-github fa-lg"></span>
</a>
</li>
</ul></div>
</div>
</nav><div class="container template-reference-topic">
<div class="row">
<main id="main" class="col-md-9"><div class="page-header">
<img src="" class="logo" alt=""><h1>Causal rule ensemble</h1>
<small class="dont-index">Source: <a href="https://github.com/NSAPH-Software/CRE/blob/HEAD/R/cre.R"><code>R/cre.R</code></a></small>
<div class="d-none name"><code>cre.Rd</code></div>
</div>
<div class="ref-description section level2">
<p>Performs the Causal Rule Ensemble on a data set with a response variable,
a treatment variable, and various features.</p>
</div>
<div class="section level2">
<h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">cre</span><span class="op">(</span><span class="va">y</span>, <span class="va">z</span>, <span class="va">X</span>, method_params <span class="op">=</span> <span class="cn">NULL</span>, hyper_params <span class="op">=</span> <span class="cn">NULL</span>, ite <span class="op">=</span> <span class="cn">NULL</span><span class="op">)</span></span></code></pre></div>
</div>
<div class="section level2">
<h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>
<dl><dt>y</dt>
<dd><p>An observed response vector.</p></dd>
<dt>z</dt>
<dd><p>A treatment vector.</p></dd>
<dt>X</dt>
<dd><p>A covariate matrix (or a data frame). Should be provided as
numerical values.</p></dd>
<dt>method_params</dt>
<dd><p>The list of parameters to define the models used,
including:</p><ul><li><p><em>Parameters for Honest Splitting</em></p><ul><li><p><em>ratio_dis</em>: The ratio of data delegated to rules discovery
(default: 0.5).</p></li>
</ul></li>
<li><p><em>Parameters for Discovery and Inference</em></p><ul><li><p><em>ite_method</em>: The method for ITE (pseudo-outcome) estimation
(default: <code>"aipw"</code>, options: <code>"aipw"</code> for Augmented Inverse
Probability Weighting, <code>"cf"</code> for Causal Forest, <code>"bart"</code> for
Causal Bayesian Additive Regression Trees, <code>"slearner"</code> for S-Learner,
<code>"tlearner"</code> for T-Learner, <code>"xlearner"</code> for X-Learner,
<code>"tpoisson"</code> for T-Learner with Poisson regression).</p></li>
<li><p><em>learner_ps</em>: The model for the propensity score estimation
(default: <code>"SL.xgboost"</code>, options: any SuperLearner prediction model
i.e., <code>"SL.lm"</code>, <code>"SL.svm"</code>, used only for <code>"aipw"</code>,
<code>"bart"</code>, <code>"cf"</code> ITE estimators).</p></li>
<li><p><em>learner_y</em>: The model for the outcome estimation
(default: <code>"SL.xgboost"</code>, options: any SuperLearner prediction model
i.e., <code>"SL.lm"</code>, <code>"SL.svm"</code>, used only for <code>"aipw"</code>,
<code>"slearner"</code>, <code>"tlearner"</code> and <code>"xlearner"</code> ITE
estimators).</p></li>
</ul></li>
</ul></dd>
<dt>hyper_params</dt>
<dd><p>The list of hyper parameters to fine-tune the method,
including:</p><ul><li><p><em>General hyper parameters</em></p><ul><li><p><em>intervention_vars</em>: Array with intervention-able covariates names used
for Rules Generation. Empty or null array means that all the covariates
are considered as intervention-able (default: <code>NULL</code>).</p></li>
<li><p><em>ntrees</em>: The number of decision trees for random forest (default: 20).</p></li>
<li><p><em>node_size</em>: Minimum size of the trees' terminal nodes (default: 20).</p></li>
<li><p><em>max_rules</em>: Maximum number of generated candidates rules (default: 50).</p></li>
<li><p><em>max_depth</em>: Maximum rules length (default: 3).</p></li>
<li><p><em>t_decay</em>: The decay threshold for rules pruning. Higher values will
carry out an aggressive pruning (default: 0.025).</p></li>
<li><p><em>t_ext</em>: The threshold to truncate too generic or too specific (extreme)
rules (default: 0.01, range: [0, 0.5)).</p></li>
<li><p><em>t_corr</em>: The threshold to define correlated rules (default: 1,
range: <code>[0,+inf)</code>).</p></li>
<li><p><em>stability_selection</em>: Method for stability selection for selecting the
rules. <code>"vanilla"</code> for stability selection, <code>"error_control"</code>
for stability selection with error control and <code>"no"</code> for no
stability selection (default: <code>"vanilla"</code>).</p></li>
<li><p><em>B</em>: Number of bootstrap samples for stability selection in rules
selection and uncertainty quantification in estimation (default: 20).</p></li>
<li><p><em>subsample</em>: Bootstrap ratio subsample for stability selection in rules
selection and uncertainty quantification in estimation (default: 0.5).</p></li>
</ul></li>
<li><p><em>Method specific hyper parameters</em></p><ul><li><p><em>offset</em>: Name of the covariate to use as offset (i.e., <code>"x1"</code>) for
T-Poisson ITE estimation. Use <code>NULL</code> if offset is not used (default:
<code>NULL</code>).</p></li>
<li><p><em>cutoff</em>: Threshold (percentage) defining the minimum cutoff value for
the stability scores for Stability Selection (default: 0.9).</p></li>
<li><p><em>pfer</em>: Upper bound for the per-family error rate (tolerated amount of
falsely selected rules) for Error Control Stability Selection (default: 1).</p></li>
</ul></li>
</ul></dd>
<dt>ite</dt>
<dd><p>The estimated ITE vector. If given both the ITE estimation steps
in Discovery and Inference are skipped (default: <code>NULL</code>).</p></dd>
</dl></div>
<div class="section level2">
<h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2>
<p>An S3 object composed by:</p>
<dl><dt>M</dt>
<dd><p>the number of Decision Rules extracted at each step,</p></dd>
<dt>CATE</dt>
<dd><p>the data.frame of Conditional Average Treatment Effect
decomposition estimates with corresponding uncertainty quantification,</p></dd>
<dt>method_params</dt>
<dd><p>the list of method parameters,</p></dd>
<dt>hyper_params</dt>
<dd><p>the list of hyper parameters,</p></dd>
<dt>rules</dt>
<dd><p>the list of rules (implicit form) decomposing the CATE.</p></dd>
</dl></div>
<div class="section level2">
<h2 id="note">Note<a class="anchor" aria-label="anchor" href="#note"></a></h2>
<ul><li><p>If <code>intervention_vars</code> are provided, it is important to note that the
individual treatment effect will still be computed using all covariates.</p></li>
</ul></div>
<div class="section level2">
<h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span></span></span>
<span class="r-in"><span><span class="co"># \donttest{</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/Random.html" class="external-link">set.seed</a></span><span class="op">(</span><span class="fl">123</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">dataset</span> <span class="op"><-</span> <span class="fu"><a href="generate_cre_dataset.html">generate_cre_dataset</a></span><span class="op">(</span>n <span class="op">=</span> <span class="fl">400</span>,</span></span>
<span class="r-in"><span> rho <span class="op">=</span> <span class="fl">0</span>,</span></span>
<span class="r-in"><span> n_rules <span class="op">=</span> <span class="fl">2</span>,</span></span>
<span class="r-in"><span> p <span class="op">=</span> <span class="fl">10</span>,</span></span>
<span class="r-in"><span> effect_size <span class="op">=</span> <span class="fl">2</span>,</span></span>
<span class="r-in"><span> binary_covariates <span class="op">=</span> <span class="cn">TRUE</span>,</span></span>
<span class="r-in"><span> binary_outcome <span class="op">=</span> <span class="cn">FALSE</span>,</span></span>
<span class="r-in"><span> confounding <span class="op">=</span> <span class="st">"no"</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">y</span> <span class="op"><-</span> <span class="va">dataset</span><span class="op">[[</span><span class="st">"y"</span><span class="op">]</span><span class="op">]</span></span></span>
<span class="r-in"><span><span class="va">z</span> <span class="op"><-</span> <span class="va">dataset</span><span class="op">[[</span><span class="st">"z"</span><span class="op">]</span><span class="op">]</span></span></span>
<span class="r-in"><span><span class="va">X</span> <span class="op"><-</span> <span class="va">dataset</span><span class="op">[[</span><span class="st">"X"</span><span class="op">]</span><span class="op">]</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="va">method_params</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span>ratio_dis <span class="op">=</span> <span class="fl">0.5</span>,</span></span>
<span class="r-in"><span> ite_method <span class="op">=</span><span class="st">"aipw"</span>,</span></span>
<span class="r-in"><span> learner_ps <span class="op">=</span> <span class="st">"SL.xgboost"</span>,</span></span>
<span class="r-in"><span> learner_y <span class="op">=</span> <span class="st">"SL.xgboost"</span><span class="op">)</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="va">hyper_params</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span>intervention_vars <span class="op">=</span> <span class="cn">NULL</span>,</span></span>
<span class="r-in"><span> offset <span class="op">=</span> <span class="cn">NULL</span>,</span></span>
<span class="r-in"><span> ntrees <span class="op">=</span> <span class="fl">20</span>,</span></span>
<span class="r-in"><span> node_size <span class="op">=</span> <span class="fl">20</span>,</span></span>
<span class="r-in"><span> max_rules <span class="op">=</span> <span class="fl">50</span>,</span></span>
<span class="r-in"><span> max_depth <span class="op">=</span> <span class="fl">3</span>,</span></span>
<span class="r-in"><span> t_decay <span class="op">=</span> <span class="fl">0.025</span>,</span></span>
<span class="r-in"><span> t_ext <span class="op">=</span> <span class="fl">0.025</span>,</span></span>
<span class="r-in"><span> t_corr <span class="op">=</span> <span class="fl">1</span>,</span></span>
<span class="r-in"><span> stability_selection <span class="op">=</span> <span class="st">"vanilla"</span>,</span></span>
<span class="r-in"><span> cutoff <span class="op">=</span> <span class="fl">0.6</span>,</span></span>
<span class="r-in"><span> pfer <span class="op">=</span> <span class="fl">1</span>,</span></span>
<span class="r-in"><span> B <span class="op">=</span> <span class="fl">20</span>,</span></span>
<span class="r-in"><span> subsample <span class="op">=</span> <span class="fl">0.5</span><span class="op">)</span></span></span>
<span class="r-in"><span></span></span>
<span class="r-in"><span><span class="va">cre_results</span> <span class="op"><-</span> <span class="fu">cre</span><span class="op">(</span><span class="va">y</span>, <span class="va">z</span>, <span class="va">X</span>, <span class="va">method_params</span>, <span class="va">hyper_params</span><span class="op">)</span></span></span>
<span class="r-msg co"><span class="r-pr">#></span> Loading required package: nnls</span>
<span class="r-msg co"><span class="r-pr">#></span> Registered S3 method overwritten by 'randomForest':</span>
<span class="r-msg co"><span class="r-pr">#></span> method from</span>
<span class="r-msg co"><span class="r-pr">#></span> plot.margin RRF </span>
<span class="r-in"><span><span class="co"># }</span></span></span>
<span class="r-in"><span></span></span>
</code></pre></div>
</div>
</main><aside class="col-md-3"><nav id="toc"><h2>On this page</h2>
</nav></aside></div>
<footer><div class="pkgdown-footer-left">
<p></p><p>Developed by Naeem Khoshnevis, Daniela Maria Garcia, Riccardo Cadei, Kwonsang Lee, Falco Joannes Bargagli Stoffi.</p>
</div>
<div class="pkgdown-footer-right">
<p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.7.</p>
</div>
</footer></div>
</body></html>