/
rvine_structure.html
355 lines (295 loc) · 18.7 KB
/
rvine_structure.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
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>R-vine structure — rvine_structure • rvinecopulib</title>
<!-- jquery -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- Bootstrap -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script>
<!-- bootstrap-toc -->
<link rel="stylesheet" href="../bootstrap-toc.css">
<script src="../bootstrap-toc.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" />
<!-- 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>
<!-- 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>
<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../pkgdown.js"></script>
<meta property="og:title" content="R-vine structure — rvine_structure" />
<meta property="og:description" content="R-vine structures are compressed representations encoding the tree structure
of the vine, i.e. the conditioned/conditioning variables of each edge. The
functions [cvine_structure()] or [dvine_structure()] give a simpler way
to construct C-vines (every tree is a star) and D-vines (every tree is a
path), respectively (see Examples)." />
<!-- 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 data-spy="scroll" data-target="#toc">
<div class="container template-reference-topic">
<header>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">
<a class="navbar-link" href="../index.html">rvinecopulib</a>
<span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">0.6.1.1.0</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="../index.html">
<span class="fas fa-home fa-lg"></span>
</a>
</li>
<li>
<a href="../reference/index.html">Reference</a>
</li>
<li>
<a href="../news/index.html">Changelog</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/vinecopulib/rvinecopulib/">
<span class="fab fa-github fa-lg"></span>
</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
</header>
<div class="row">
<div class="col-md-9 contents">
<div class="page-header">
<h1>R-vine structure</h1>
<small class="dont-index">Source: <a href='https://github.com/vinecopulib/rvinecopulib/blob/master/R/rvine_structure.R'><code>R/rvine_structure.R</code></a></small>
<div class="hidden name"><code>rvine_structure.Rd</code></div>
</div>
<div class="ref-description">
<p>R-vine structures are compressed representations encoding the tree structure
of the vine, i.e. the conditioned/conditioning variables of each edge. The
functions <code>[cvine_structure()]</code> or <code>[dvine_structure()]</code> give a simpler way
to construct C-vines (every tree is a star) and D-vines (every tree is a
path), respectively (see <em>Examples</em>).</p>
</div>
<pre class="usage"><span class='fu'>rvine_structure</span><span class='op'>(</span><span class='va'>order</span>, struct_array <span class='op'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/list.html'>list</a></span><span class='op'>(</span><span class='op'>)</span>, is_natural_order <span class='op'>=</span> <span class='cn'>FALSE</span><span class='op'>)</span>
<span class='fu'>cvine_structure</span><span class='op'>(</span><span class='va'>order</span>, trunc_lvl <span class='op'>=</span> <span class='cn'>Inf</span><span class='op'>)</span>
<span class='fu'>dvine_structure</span><span class='op'>(</span><span class='va'>order</span>, trunc_lvl <span class='op'>=</span> <span class='cn'>Inf</span><span class='op'>)</span>
<span class='fu'>rvine_matrix</span><span class='op'>(</span><span class='va'>matrix</span><span class='op'>)</span></pre>
<h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a>Arguments</h2>
<table class="ref-arguments">
<colgroup><col class="name" /><col class="desc" /></colgroup>
<tr>
<th>order</th>
<td><p>a vector of positive integers.</p></td>
</tr>
<tr>
<th>struct_array</th>
<td><p>a list of vectors of positive integers. The vectors
represent rows of the r-rvine structure and the number of elements have to
be compatible with the <code>order</code> vector. If empty, the model is 0-truncated.</p></td>
</tr>
<tr>
<th>is_natural_order</th>
<td><p>whether <code>struct_array</code> is assumed to be provided in
natural order already (a structure is in natural order if the anti-
diagonal is 1, .., d from bottom left to top right).</p></td>
</tr>
<tr>
<th>trunc_lvl</th>
<td><p>the truncation level</p></td>
</tr>
<tr>
<th>matrix</th>
<td><p>an R-vine matrix, see <em>Details</em>.</p></td>
</tr>
</table>
<h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>
<p>Either an <code>rvine_structure</code> or an <code>rvine_matrix</code>.</p>
<h2 class="hasAnchor" id="details"><a class="anchor" href="#details"></a>Details</h2>
<p>The R-vine structure is essentially a lower-triangular matrix/triangular
array, with a notation that differs from the one in the VineCopula package.
An example array is</p><pre>4 4 4 4
3 3 3
2 2
1
</pre>
<p>which encodes the following pair-copulas:</p>
<table class='table'>
<tr><td>tree</td><td>edge</td><td>pair-copulas</td></tr>
<tr><td>0</td><td>0</td><td><code>(1, 4)</code></td></tr>
<tr><td></td><td>1</td><td><code>(2, 4)</code></td></tr>
<tr><td></td><td>2</td><td><code>(3, 4)</code></td></tr>
<tr><td>1</td><td>0</td><td><code>(1, 3; 4)</code></td></tr>
<tr><td></td><td>1</td><td><code>(2, 3; 4)</code></td></tr>
<tr><td>2</td><td>0</td><td><code>(1, 2; 3, 4)</code></td></tr>
</table>
<p>An R-vine structure can be converted to an R-vine matrix using
<code><a href='as_rvine_structure.html'>as_rvine_matrix()</a></code>, which encodes the same model with a square matrix filled
with zeros. For instance, the matrix corresponding to the structure above is:</p><pre>4 4 4 4
3 3 3 0
2 2 0 0
1 0 0 0
</pre>
<p>Similarly, an R-vine matrix can be converted to an R-vine structure using
<code><a href='as_rvine_structure.html'>as_rvine_structure()</a></code>.</p>
<p>Denoting by <code>M[i, j]</code> the array entry in row <code>i</code> and column <code>j</code> (the
pair-copula index for edge <code>e</code> in tree <code>t</code> of a <code>d</code> dimensional vine is
<code>(M[d + 1 - e, e], M[t, e]; M[t - 1, e], ..., M[1, e])</code>. Less formally,</p><ol>
<li><p>Start with the counter-diagonal element of column <code>e</code> (first conditioned
variable).</p></li>
<li><p>Jump up to the element in row <code>t</code> (second conditioned variable).</p></li>
<li><p>Gather all entries further up in column <code>e</code> (conditioning set).</p></li>
</ol>
<p>Internally, the diagonal is stored separately from the off-diagonal elements,
which are stored as a triangular array. For instance, the off-diagonal
elements off the structure above are stored as</p><pre>4 4 4
3 3
2
</pre>
<p>for the structure above. The reason is that it allows for parsimonious
representations of truncated models. For instance, the 2-truncated model is
represented by the same diagonal and the following truncated triangular
array:</p><pre>4 4 4
3 3
</pre>
<p>A valid R-vine structure or matrix must satisfy several conditions which are
checked when <code>rvine_structure()</code>, <code>rvine_matrix()</code>, or some coercion methods
(see <code><a href='as_rvine_structure.html'>as_rvine_structure()</a></code> and <code>as_rvine_matrix(</code>) are called:</p><ol>
<li><p>It can only contain numbers between 1 and d (and additionally zeros for
R-vine matrices).</p></li>
<li><p>The anti-diagonal must contain the numbers 1, ..., d.</p></li>
<li><p>The anti-diagonal entry of a column must not be contained in any column
further to the right.</p></li>
<li><p>The entries of a column must be contained in all columns to the left.</p></li>
<li><p>The proximity condition must hold: For all t = 1, ..., d - 2 and e = 1,
..., d - t there must exist an index j > d, such that
<code>(M[t, e], {M[1, e], ..., M[t - 1, e]})</code> equals either
<code>(M[d + 1 - j, j], {M[1, j], ..., M[t - 1, j]})</code> or
<code>(M[t - 1, j], {M[d + 1 - j, j], M[1, j], ..., M[t - 2, j]})</code>.</p></li>
</ol>
<p>Condition 5 already implies conditions 2-4, but is more difficult to check by
hand.</p>
<h2 class="hasAnchor" id="see-also"><a class="anchor" href="#see-also"></a>See also</h2>
<div class='dont-index'><p><code><a href='as_rvine_structure.html'>as_rvine_structure()</a></code>, <code><a href='as_rvine_structure.html'>as_rvine_matrix()</a></code>,
<code><a href='plot.rvine_structure.html'>plot.rvine_structure()</a></code>, <code><a href='plot.rvine_structure.html'>plot.rvine_matrix()</a></code>,
<code><a href='rvine_structure_sim.html'>rvine_structure_sim()</a></code>, <code><a href='rvine_structure_sim.html'>rvine_matrix_sim()</a></code></p></div>
<h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
<pre class="examples"><div class='input'>
<span class='co'># R-vine structures can be constructed from the order vector and struct_array</span>
<span class='fu'>rvine_structure</span><span class='op'>(</span>order <span class='op'>=</span> <span class='fl'>1</span><span class='op'>:</span><span class='fl'>4</span>, struct_array <span class='op'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/list.html'>list</a></span><span class='op'>(</span>
<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>4</span>, <span class='fl'>4</span>, <span class='fl'>4</span><span class='op'>)</span>,
<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>3</span>, <span class='fl'>3</span><span class='op'>)</span>,
<span class='fl'>2</span>
<span class='op'>)</span><span class='op'>)</span>
</div><div class='output co'>#> 4-dimensional R-vine structure ('rvine_structure')
#> 4 4 4 4
#> 3 3 3
#> 2 2
#> 1 </div><div class='input'>
<span class='co'># R-vine matrices can be constructed from standard matrices</span>
<span class='va'>mat</span> <span class='op'><-</span> <span class='fu'><a href='https://rdrr.io/r/base/matrix.html'>matrix</a></span><span class='op'>(</span><span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>4</span>, <span class='fl'>3</span>, <span class='fl'>2</span>, <span class='fl'>1</span>, <span class='fl'>4</span>, <span class='fl'>3</span>, <span class='fl'>2</span>, <span class='fl'>0</span>, <span class='fl'>4</span>, <span class='fl'>3</span>, <span class='fl'>0</span>, <span class='fl'>0</span>, <span class='fl'>4</span>, <span class='fl'>0</span>, <span class='fl'>0</span>, <span class='fl'>0</span><span class='op'>)</span>, <span class='fl'>4</span>, <span class='fl'>4</span><span class='op'>)</span>
<span class='fu'>rvine_matrix</span><span class='op'>(</span><span class='va'>mat</span><span class='op'>)</span>
</div><div class='output co'>#> 4-dimensional R-vine matrix ('rvine_matrix')
#> 4 4 4 4
#> 3 3 3
#> 2 2
#> 1 </div><div class='input'>
<span class='co'># coerce to R-vine structure</span>
<span class='fu'><a href='https://rdrr.io/r/utils/str.html'>str</a></span><span class='op'>(</span><span class='fu'><a href='as_rvine_structure.html'>as_rvine_structure</a></span><span class='op'>(</span><span class='va'>mat</span><span class='op'>)</span><span class='op'>)</span>
</div><div class='output co'>#> List of 4
#> $ order : num [1:4] 1 2 3 4
#> $ struct_array:List of 3
#> ..$ : int [1:3] 4 4 4
#> ..$ : int [1:2] 3 3
#> ..$ : int 2
#> $ d : Named num 4
#> ..- attr(*, "names")= chr "dim"
#> $ trunc_lvl : Named num 3
#> ..- attr(*, "names")= chr "trunc_lvl"
#> - attr(*, "class")= chr [1:2] "rvine_structure" "list"</div><div class='input'>
<span class='co'># truncate and construct the R-vine matrix</span>
<span class='va'>mat</span><span class='op'>[</span><span class='fl'>3</span>, <span class='fl'>1</span><span class='op'>]</span> <span class='op'><-</span> <span class='fl'>0</span>
<span class='fu'>rvine_matrix</span><span class='op'>(</span><span class='va'>mat</span><span class='op'>)</span>
</div><div class='output co'>#> 4-dimensional R-vine matrix ('rvine_matrix'), 2-truncated
#> 4 4 4 4
#> 3 3 3
#> 2
#> 1 </div><div class='input'>
<span class='co'># or use directly the R-vine structure constructor</span>
<span class='fu'>rvine_structure</span><span class='op'>(</span>order <span class='op'>=</span> <span class='fl'>1</span><span class='op'>:</span><span class='fl'>4</span>, struct_array <span class='op'>=</span> <span class='fu'><a href='https://rdrr.io/r/base/list.html'>list</a></span><span class='op'>(</span>
<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>4</span>, <span class='fl'>4</span>, <span class='fl'>4</span><span class='op'>)</span>,
<span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>3</span>, <span class='fl'>3</span><span class='op'>)</span>
<span class='op'>)</span><span class='op'>)</span>
</div><div class='output co'>#> 4-dimensional R-vine structure ('rvine_structure'), 2-truncated
#> 4 4 4 4
#> 3 3 3
#> 2
#> 1 </div><div class='input'>
<span class='co'># throws an error</span>
<span class='va'>mat</span><span class='op'>[</span><span class='fl'>3</span>, <span class='fl'>1</span><span class='op'>]</span> <span class='op'><-</span> <span class='fl'>5</span>
<span class='kw'><a href='https://rdrr.io/r/base/try.html'>try</a></span><span class='op'>(</span><span class='fu'>rvine_matrix</span><span class='op'>(</span><span class='va'>mat</span><span class='op'>)</span><span class='op'>)</span>
</div><div class='output co'>#> Error in rvine_matrix_check_cpp(matrix) :
#> not a valid R-vine array: the upper left triangle can only contain numbers between 1 and d (number of variables).</div><div class='input'>
<span class='co'># C-vine structure</span>
<span class='va'>cvine</span> <span class='op'><-</span> <span class='fu'>cvine_structure</span><span class='op'>(</span><span class='fl'>1</span><span class='op'>:</span><span class='fl'>5</span><span class='op'>)</span>
<span class='va'>cvine</span>
</div><div class='output co'>#> 5-dimensional R-vine structure ('rvine_structure')
#> 5 5 5 5 5
#> 4 4 4 4
#> 3 3 3
#> 2 2
#> 1 </div><div class='input'><span class='fu'><a href='https://rdrr.io/r/graphics/plot.default.html'>plot</a></span><span class='op'>(</span><span class='va'>cvine</span><span class='op'>)</span>
</div><div class='img'><img src='rvine_structure-1.png' alt='' width='700' height='433' /></div><div class='input'>
<span class='co'># D-vine structure</span>
<span class='va'>dvine</span> <span class='op'><-</span> <span class='fu'>dvine_structure</span><span class='op'>(</span><span class='fu'><a href='https://rdrr.io/r/base/c.html'>c</a></span><span class='op'>(</span><span class='fl'>1</span>, <span class='fl'>4</span>, <span class='fl'>2</span>, <span class='fl'>3</span>, <span class='fl'>5</span><span class='op'>)</span><span class='op'>)</span>
<span class='va'>dvine</span>
</div><div class='output co'>#> 5-dimensional R-vine structure ('rvine_structure')
#> 4 2 3 5 5
#> 2 3 5 3
#> 3 5 2
#> 5 4
#> 1 </div><div class='input'><span class='fu'><a href='https://rdrr.io/r/graphics/plot.default.html'>plot</a></span><span class='op'>(</span><span class='va'>dvine</span><span class='op'>)</span>
</div><div class='img'><img src='rvine_structure-2.png' alt='' width='700' height='433' /></div><div class='input'>
</div></pre>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
<nav id="toc" data-toggle="toc" class="sticky-top">
<h2 data-toc-skip>Contents</h2>
</nav>
</div>
</div>
<footer>
<div class="copyright">
<p>Developed by Thomas Nagler, Thibault Vatter.</p>
</div>
<div class="pkgdown">
<p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> 1.6.1.</p>
</div>
</footer>
</div>
</body>
</html>