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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>rsdmx quickstart guide</title>
<script type="text/javascript">
window.onload = function() {
var imgs = document.getElementsByTagName('img'), i, img;
for (i = 0; i < imgs.length; i++) {
img = imgs[i];
// center an image if it is the only element of its parent
if (img.parentElement.childElementCount === 1)
img.parentElement.style.textAlign = 'center';
}
};
</script>
<!-- Styles for R syntax highlighter -->
<style type="text/css">
pre .operator,
pre .paren {
color: rgb(104, 118, 135)
}
pre .literal {
color: #990073
}
pre .number {
color: #099;
}
pre .comment {
color: #998;
font-style: italic
}
pre .keyword {
color: #900;
font-weight: bold
}
pre .identifier {
color: rgb(0, 0, 0);
}
pre .string {
color: #d14;
}
</style>
<!-- R syntax highlighter -->
<script type="text/javascript">
var hljs=new function(){function m(p){return p.replace(/&/gm,"&").replace(/</gm,"<")}function f(r,q,p){return RegExp(q,"m"+(r.cI?"i":"")+(p?"g":""))}function b(r){for(var p=0;p<r.childNodes.length;p++){var q=r.childNodes[p];if(q.nodeName=="CODE"){return q}if(!(q.nodeType==3&&q.nodeValue.match(/\s+/))){break}}}function h(t,s){var p="";for(var r=0;r<t.childNodes.length;r++){if(t.childNodes[r].nodeType==3){var q=t.childNodes[r].nodeValue;if(s){q=q.replace(/\n/g,"")}p+=q}else{if(t.childNodes[r].nodeName=="BR"){p+="\n"}else{p+=h(t.childNodes[r])}}}if(/MSIE [678]/.test(navigator.userAgent)){p=p.replace(/\r/g,"\n")}return p}function a(s){var r=s.className.split(/\s+/);r=r.concat(s.parentNode.className.split(/\s+/));for(var q=0;q<r.length;q++){var p=r[q].replace(/^language-/,"");if(e[p]){return p}}}function c(q){var p=[];(function(s,t){for(var r=0;r<s.childNodes.length;r++){if(s.childNodes[r].nodeType==3){t+=s.childNodes[r].nodeValue.length}else{if(s.childNodes[r].nodeName=="BR"){t+=1}else{if(s.childNodes[r].nodeType==1){p.push({event:"start",offset:t,node:s.childNodes[r]});t=arguments.callee(s.childNodes[r],t);p.push({event:"stop",offset:t,node:s.childNodes[r]})}}}}return t})(q,0);return p}function k(y,w,x){var q=0;var z="";var s=[];function u(){if(y.length&&w.length){if(y[0].offset!=w[0].offset){return(y[0].offset<w[0].offset)?y:w}else{return w[0].event=="start"?y:w}}else{return y.length?y:w}}function t(D){var A="<"+D.nodeName.toLowerCase();for(var B=0;B<D.attributes.length;B++){var C=D.attributes[B];A+=" "+C.nodeName.toLowerCase();if(C.value!==undefined&&C.value!==false&&C.value!==null){A+='="'+m(C.value)+'"'}}return A+">"}while(y.length||w.length){var v=u().splice(0,1)[0];z+=m(x.substr(q,v.offset-q));q=v.offset;if(v.event=="start"){z+=t(v.node);s.push(v.node)}else{if(v.event=="stop"){var p,r=s.length;do{r--;p=s[r];z+=("</"+p.nodeName.toLowerCase()+">")}while(p!=v.node);s.splice(r,1);while(r<s.length){z+=t(s[r]);r++}}}}return z+m(x.substr(q))}function j(){function q(x,y,v){if(x.compiled){return}var u;var s=[];if(x.k){x.lR=f(y,x.l||hljs.IR,true);for(var w in x.k){if(!x.k.hasOwnProperty(w)){continue}if(x.k[w] instanceof Object){u=x.k[w]}else{u=x.k;w="keyword"}for(var r in u){if(!u.hasOwnProperty(r)){continue}x.k[r]=[w,u[r]];s.push(r)}}}if(!v){if(x.bWK){x.b="\\b("+s.join("|")+")\\s"}x.bR=f(y,x.b?x.b:"\\B|\\b");if(!x.e&&!x.eW){x.e="\\B|\\b"}if(x.e){x.eR=f(y,x.e)}}if(x.i){x.iR=f(y,x.i)}if(x.r===undefined){x.r=1}if(!x.c){x.c=[]}x.compiled=true;for(var t=0;t<x.c.length;t++){if(x.c[t]=="self"){x.c[t]=x}q(x.c[t],y,false)}if(x.starts){q(x.starts,y,false)}}for(var p in e){if(!e.hasOwnProperty(p)){continue}q(e[p].dM,e[p],true)}}function d(B,C){if(!j.called){j();j.called=true}function q(r,M){for(var L=0;L<M.c.length;L++){if((M.c[L].bR.exec(r)||[null])[0]==r){return M.c[L]}}}function v(L,r){if(D[L].e&&D[L].eR.test(r)){return 1}if(D[L].eW){var M=v(L-1,r);return M?M+1:0}return 0}function w(r,L){return L.i&&L.iR.test(r)}function K(N,O){var M=[];for(var L=0;L<N.c.length;L++){M.push(N.c[L].b)}var r=D.length-1;do{if(D[r].e){M.push(D[r].e)}r--}while(D[r+1].eW);if(N.i){M.push(N.i)}return f(O,M.join("|"),true)}function p(M,L){var N=D[D.length-1];if(!N.t){N.t=K(N,E)}N.t.lastIndex=L;var r=N.t.exec(M);return r?[M.substr(L,r.index-L),r[0],false]:[M.substr(L),"",true]}function z(N,r){var L=E.cI?r[0].toLowerCase():r[0];var M=N.k[L];if(M&&M instanceof Array){return M}return false}function F(L,P){L=m(L);if(!P.k){return L}var r="";var O=0;P.lR.lastIndex=0;var M=P.lR.exec(L);while(M){r+=L.substr(O,M.index-O);var N=z(P,M);if(N){x+=N[1];r+='<span class="'+N[0]+'">'+M[0]+"</span>"}else{r+=M[0]}O=P.lR.lastIndex;M=P.lR.exec(L)}return r+L.substr(O,L.length-O)}function J(L,M){if(M.sL&&e[M.sL]){var r=d(M.sL,L);x+=r.keyword_count;return r.value}else{return F(L,M)}}function I(M,r){var L=M.cN?'<span class="'+M.cN+'">':"";if(M.rB){y+=L;M.buffer=""}else{if(M.eB){y+=m(r)+L;M.buffer=""}else{y+=L;M.buffer=r}}D.push(M);A+=M.r}function G(N,M,Q){var R=D[D.length-1];if(Q){y+=J(R.buffer+N,R);return false}var P=q(M,R);if(P){y+=J(R.buffer+N,R);I(P,M);return P.rB}var L=v(D.length-1,M);if(L){var O=R.cN?"</span>":"";if(R.rE){y+=J(R.buffer+N,R)+O}else{if(R.eE){y+=J(R.buffer+N,R)+O+m(M)}else{y+=J(R.buffer+N+M,R)+O}}while(L>1){O=D[D.length-2].cN?"</span>":"";y+=O;L--;D.length--}var r=D[D.length-1];D.length--;D[D.length-1].buffer="";if(r.starts){I(r.starts,"")}return R.rE}if(w(M,R)){throw"Illegal"}}var E=e[B];var D=[E.dM];var A=0;var x=0;var y="";try{var s,u=0;E.dM.buffer="";do{s=p(C,u);var t=G(s[0],s[1],s[2]);u+=s[0].length;if(!t){u+=s[1].length}}while(!s[2]);if(D.length>1){throw"Illegal"}return{r:A,keyword_count:x,value:y}}catch(H){if(H=="Illegal"){return{r:0,keyword_count:0,value:m(C)}}else{throw H}}}function g(t){var p={keyword_count:0,r:0,value:m(t)};var r=p;for(var q in e){if(!e.hasOwnProperty(q)){continue}var s=d(q,t);s.language=q;if(s.keyword_count+s.r>r.keyword_count+r.r){r=s}if(s.keyword_count+s.r>p.keyword_count+p.r){r=p;p=s}}if(r.language){p.second_best=r}return p}function i(r,q,p){if(q){r=r.replace(/^((<[^>]+>|\t)+)/gm,function(t,w,v,u){return w.replace(/\t/g,q)})}if(p){r=r.replace(/\n/g,"<br>")}return r}function n(t,w,r){var x=h(t,r);var v=a(t);var y,s;if(v){y=d(v,x)}else{return}var q=c(t);if(q.length){s=document.createElement("pre");s.innerHTML=y.value;y.value=k(q,c(s),x)}y.value=i(y.value,w,r);var u=t.className;if(!u.match("(\\s|^)(language-)?"+v+"(\\s|$)")){u=u?(u+" "+v):v}if(/MSIE [678]/.test(navigator.userAgent)&&t.tagName=="CODE"&&t.parentNode.tagName=="PRE"){s=t.parentNode;var p=document.createElement("div");p.innerHTML="<pre><code>"+y.value+"</code></pre>";t=p.firstChild.firstChild;p.firstChild.cN=s.cN;s.parentNode.replaceChild(p.firstChild,s)}else{t.innerHTML=y.value}t.className=u;t.result={language:v,kw:y.keyword_count,re:y.r};if(y.second_best){t.second_best={language:y.second_best.language,kw:y.second_best.keyword_count,re:y.second_best.r}}}function o(){if(o.called){return}o.called=true;var r=document.getElementsByTagName("pre");for(var p=0;p<r.length;p++){var q=b(r[p]);if(q){n(q,hljs.tabReplace)}}}function l(){if(window.addEventListener){window.addEventListener("DOMContentLoaded",o,false);window.addEventListener("load",o,false)}else{if(window.attachEvent){window.attachEvent("onload",o)}else{window.onload=o}}}var e={};this.LANGUAGES=e;this.highlight=d;this.highlightAuto=g;this.fixMarkup=i;this.highlightBlock=n;this.initHighlighting=o;this.initHighlightingOnLoad=l;this.IR="[a-zA-Z][a-zA-Z0-9_]*";this.UIR="[a-zA-Z_][a-zA-Z0-9_]*";this.NR="\\b\\d+(\\.\\d+)?";this.CNR="\\b(0[xX][a-fA-F0-9]+|(\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)";this.BNR="\\b(0b[01]+)";this.RSR="!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|\\.|-|-=|/|/=|:|;|<|<<|<<=|<=|=|==|===|>|>=|>>|>>=|>>>|>>>=|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~";this.ER="(?![\\s\\S])";this.BE={b:"\\\\.",r:0};this.ASM={cN:"string",b:"'",e:"'",i:"\\n",c:[this.BE],r:0};this.QSM={cN:"string",b:'"',e:'"',i:"\\n",c:[this.BE],r:0};this.CLCM={cN:"comment",b:"//",e:"$"};this.CBLCLM={cN:"comment",b:"/\\*",e:"\\*/"};this.HCM={cN:"comment",b:"#",e:"$"};this.NM={cN:"number",b:this.NR,r:0};this.CNM={cN:"number",b:this.CNR,r:0};this.BNM={cN:"number",b:this.BNR,r:0};this.inherit=function(r,s){var p={};for(var q in r){p[q]=r[q]}if(s){for(var q in s){p[q]=s[q]}}return p}}();hljs.LANGUAGES.cpp=function(){var a={keyword:{"false":1,"int":1,"float":1,"while":1,"private":1,"char":1,"catch":1,"export":1,virtual:1,operator:2,sizeof:2,dynamic_cast:2,typedef:2,const_cast:2,"const":1,struct:1,"for":1,static_cast:2,union:1,namespace:1,unsigned:1,"long":1,"throw":1,"volatile":2,"static":1,"protected":1,bool:1,template:1,mutable:1,"if":1,"public":1,friend:2,"do":1,"return":1,"goto":1,auto:1,"void":2,"enum":1,"else":1,"break":1,"new":1,extern:1,using:1,"true":1,"class":1,asm:1,"case":1,typeid:1,"short":1,reinterpret_cast:2,"default":1,"double":1,register:1,explicit:1,signed:1,typename:1,"try":1,"this":1,"switch":1,"continue":1,wchar_t:1,inline:1,"delete":1,alignof:1,char16_t:1,char32_t:1,constexpr:1,decltype:1,noexcept:1,nullptr:1,static_assert:1,thread_local:1,restrict:1,_Bool:1,complex:1},built_in:{std:1,string:1,cin:1,cout:1,cerr:1,clog:1,stringstream:1,istringstream:1,ostringstream:1,auto_ptr:1,deque:1,list:1,queue:1,stack:1,vector:1,map:1,set:1,bitset:1,multiset:1,multimap:1,unordered_set:1,unordered_map:1,unordered_multiset:1,unordered_multimap:1,array:1,shared_ptr:1}};return{dM:{k:a,i:"</",c:[hljs.CLCM,hljs.CBLCLM,hljs.QSM,{cN:"string",b:"'\\\\?.",e:"'",i:"."},{cN:"number",b:"\\b(\\d+(\\.\\d*)?|\\.\\d+)(u|U|l|L|ul|UL|f|F)"},hljs.CNM,{cN:"preprocessor",b:"#",e:"$"},{cN:"stl_container",b:"\\b(deque|list|queue|stack|vector|map|set|bitset|multiset|multimap|unordered_map|unordered_set|unordered_multiset|unordered_multimap|array)\\s*<",e:">",k:a,r:10,c:["self"]}]}}}();hljs.LANGUAGES.r={dM:{c:[hljs.HCM,{cN:"number",b:"\\b0[xX][0-9a-fA-F]+[Li]?\\b",e:hljs.IMMEDIATE_RE,r:0},{cN:"number",b:"\\b\\d+(?:[eE][+\\-]?\\d*)?L\\b",e:hljs.IMMEDIATE_RE,r:0},{cN:"number",b:"\\b\\d+\\.(?!\\d)(?:i\\b)?",e:hljs.IMMEDIATE_RE,r:1},{cN:"number",b:"\\b\\d+(?:\\.\\d*)?(?:[eE][+\\-]?\\d*)?i?\\b",e:hljs.IMMEDIATE_RE,r:0},{cN:"number",b:"\\.\\d+(?:[eE][+\\-]?\\d*)?i?\\b",e:hljs.IMMEDIATE_RE,r:1},{cN:"keyword",b:"(?:tryCatch|library|setGeneric|setGroupGeneric)\\b",e:hljs.IMMEDIATE_RE,r:10},{cN:"keyword",b:"\\.\\.\\.",e:hljs.IMMEDIATE_RE,r:10},{cN:"keyword",b:"\\.\\.\\d+(?![\\w.])",e:hljs.IMMEDIATE_RE,r:10},{cN:"keyword",b:"\\b(?:function)",e:hljs.IMMEDIATE_RE,r:2},{cN:"keyword",b:"(?:if|in|break|next|repeat|else|for|return|switch|while|try|stop|warning|require|attach|detach|source|setMethod|setClass)\\b",e:hljs.IMMEDIATE_RE,r:1},{cN:"literal",b:"(?:NA|NA_integer_|NA_real_|NA_character_|NA_complex_)\\b",e:hljs.IMMEDIATE_RE,r:10},{cN:"literal",b:"(?:NULL|TRUE|FALSE|T|F|Inf|NaN)\\b",e:hljs.IMMEDIATE_RE,r:1},{cN:"identifier",b:"[a-zA-Z.][a-zA-Z0-9._]*\\b",e:hljs.IMMEDIATE_RE,r:0},{cN:"operator",b:"<\\-(?!\\s*\\d)",e:hljs.IMMEDIATE_RE,r:2},{cN:"operator",b:"\\->|<\\-",e:hljs.IMMEDIATE_RE,r:1},{cN:"operator",b:"%%|~",e:hljs.IMMEDIATE_RE},{cN:"operator",b:">=|<=|==|!=|\\|\\||&&|=|\\+|\\-|\\*|/|\\^|>|<|!|&|\\||\\$|:",e:hljs.IMMEDIATE_RE,r:0},{cN:"operator",b:"%",e:"%",i:"\\n",r:1},{cN:"identifier",b:"`",e:"`",r:0},{cN:"string",b:'"',e:'"',c:[hljs.BE],r:0},{cN:"string",b:"'",e:"'",c:[hljs.BE],r:0},{cN:"paren",b:"[[({\\])}]",e:hljs.IMMEDIATE_RE,r:0}]}};
hljs.initHighlightingOnLoad();
</script>
<style type="text/css">
body, td {
font-family: sans-serif;
background-color: white;
font-size: 13px;
}
body {
max-width: 800px;
margin: auto;
padding: 1em;
line-height: 20px;
}
tt, code, pre {
font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace;
}
h1 {
font-size:2.2em;
}
h2 {
font-size:1.8em;
}
h3 {
font-size:1.4em;
}
h4 {
font-size:1.0em;
}
h5 {
font-size:0.9em;
}
h6 {
font-size:0.8em;
}
a:visited {
color: rgb(50%, 0%, 50%);
}
pre, img {
max-width: 100%;
}
pre {
overflow-x: auto;
}
pre code {
display: block; padding: 0.5em;
}
code {
font-size: 92%;
border: 1px solid #ccc;
}
code[class] {
background-color: #F8F8F8;
}
table, td, th {
border: none;
}
blockquote {
color:#666666;
margin:0;
padding-left: 1em;
border-left: 0.5em #EEE solid;
}
hr {
height: 0px;
border-bottom: none;
border-top-width: thin;
border-top-style: dotted;
border-top-color: #999999;
}
@media print {
* {
background: transparent !important;
color: black !important;
filter:none !important;
-ms-filter: none !important;
}
body {
font-size:12pt;
max-width:100%;
}
a, a:visited {
text-decoration: underline;
}
hr {
visibility: hidden;
page-break-before: always;
}
pre, blockquote {
padding-right: 1em;
page-break-inside: avoid;
}
tr, img {
page-break-inside: avoid;
}
img {
max-width: 100% !important;
}
@page :left {
margin: 15mm 20mm 15mm 10mm;
}
@page :right {
margin: 15mm 10mm 15mm 20mm;
}
p, h2, h3 {
orphans: 3; widows: 3;
}
h2, h3 {
page-break-after: avoid;
}
}
</style>
</head>
<body>
<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{rsdmx quickstart guide}
-->
<h1>rsdmx quickstart guide</h1>
<p>The goal of this document is to get you up and running with rsdmx as quickly as possible.</p>
<p><code>rsdmx</code> provides a set of classes and methods to read data and metadata documents exchanged through the Statistical Data and Metadata Exchange (SDMX) framework.</p>
<h2>SDMX - a short introduction</h2>
<p>The SDMX framework provides two sets of standard specifications to facilitate the exchange of statistical data:</p>
<ul>
<li>standard formats</li>
<li>web-service specifications</li>
</ul>
<p>SDMX allows to disseminate both <strong>data</strong> (a dataset) and <strong>metadata</strong> (the description of the dataset).</p>
<p>For this, the SDMX standard provides various types of <em>documents</em>, also known as <em>messages</em>. Hence there will be:</p>
<ul>
<li><strong>data</strong> SDMX-ML <em>documents</em>. The two main <em>document</em> types are the <code>Generic</code> and <code>Compact</code> ones. The latter aims to provide a more compact XML document. They are other data <em>document</em> types derivating from the ones previously mentioned.</li>
<li><strong>metadata</strong> SDMX-ML <em>documents</em>. The main metadata <em>document</em> is known a <code>Data Structure Definition</code> (DSD). As its name indicates, it <em>describes</em> the structure and organization of a dataset, and will generally include all the master/reference data used to characterize a dataset. The 2 main types of metadata are (1) the <code>concepts</code>, which correspond to the <em>dimensions</em> and/or <em>attributes</em> of the dataset, and (2) the <code>codelists</code> which inventory the possible values to be used in the representation of <em>dimensions</em> and <em>attributes</em>.</li>
</ul>
<p>For more information about the SDMX standards, you can visit the <a href="http://sdmx.org/">SDMX website</a>, or this <a href="https://webgate.ec.europa.eu/fpfis/mwikis/sdmx/index.php/SDMX">introduction by EUROSTAT</a>.</p>
<h2>How to deal with SDMX in R</h2>
<p><a href="https://cran.r-project.org/package=rsdmx">rsdmx</a> offers a low-level set of tools to read <strong>data</strong> and <strong>metadata</strong> in the SDMX-ML format. Its strategy is to make it very easy for the user. For this, a unique function named <code>readSDMX</code> has to be used, whatever it is a <code>data</code> or <code>metadata</code> document, or if it is <code>local</code> or <code>remote</code> datasource.</p>
<p>What <code>rsdmx</code> does support:</p>
<ul>
<li><p>a SDMX format abstraction library, with focus on the the main SDMX standard XML format (SDMX-ML), and the support of the three format standard versions (<code>1.0</code>, <code>2.0</code>, <code>2.1</code>)</p></li>
<li><p>an interface to SDMX web-services for a list of well-known data providers, such as OECD, EUROSTAT, ECB, UN FAO, UN ILO, etc (a list that should grow in a near future!). See it <a href="https://github.com/opensdmx/rsdmx/blob/master/vignettes/quickstart.Rmd#using-the-helper-approach">in action</a>!</p></li>
</ul>
<p>Let's see then how to use <code>rsdmx</code>!</p>
<h2>Install rsdmx</h2>
<p><code>rsdmx</code> can be installed from CRAN or from its development repository hosted in Github. For the latter, you will need the <code>devtools</code> package and run:</p>
<pre><code class="r">devtools::install_github("opensdmx/rsdmx")
</code></pre>
<h2>Load rsdmx</h2>
<p>To load rsdmx in R, do the following:</p>
<pre><code class="r">library(rsdmx)
</code></pre>
<h2>Read dataset documents</h2>
<p>This section will introduce you on how to read SDMX <em>dataset</em> documents, either from <em>remote</em> datasources, or from <em>local</em> SDMX files.</p>
<h3>Read <em>remote</em> datasets</h3>
<h4>using the <em>raw</em> approach (specifying the complete request URL)</h4>
<p>The following code snipet shows you how to read a dataset from a remote data source, taking as example the <a href="http://stats.oecd.org">OECD StatExtracts portal</a>: <a href="http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/MIG/TOT../OECD?startTime=2000&endTime=2011">http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/MIG/TOT../OECD?startTime=2000&endTime=2011</a></p>
<pre><code class="r">myUrl <- "http://stats.oecd.org/restsdmx/sdmx.ashx/GetData/MIG/TOT../OECD?startTime=2000&endTime=2011"
dataset <- readSDMX(myUrl)
stats <- as.data.frame(dataset)
</code></pre>
<p>You can try it out with other datasources, such as from the <a href="http://ec.europa.eu/eurostat/web/sdmx-web-services/rest-sdmx-2.1"><strong>EUROSTAT portal</strong></a>: <a href="http://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/cdh_e_fos/..PC.FOS1.BE/?startperiod=2005&endPeriod=2011">http://ec.europa.eu/eurostat/SDMX/diss-web/rest/data/cdh_e_fos/..PC.FOS1.BE/?startperiod=2005&endPeriod=2011</a></p>
<p>The online rsdmx documentation also provides a list of data providers, either from international or national institutions, and <a href="https://github.com/opensdmx/rsdmx/wiki#read-remote-datasets">more request examples</a>.</p>
<h4>using the <em>helper</em> approach</h4>
<p>Now, the service providers above mentioned are known by <code>rsdmx</code> which let users using <code>readSDMX</code> with the helper parameters. The list of service providers can be retrieved doing:</p>
<pre><code class="r">providers <- getSDMXServiceProviders();
as.data.frame(providers)
</code></pre>
<pre><code>## agencyId
## 1 ECB
## 2 ESTAT
## 3 IMF
## 4 OECD
## 5 UNSD
## 6 FAO
## 7 ILO
## 8 UIS
## 9 UIS2
## 10 WBG_WITS
## 11 ABS
## 12 NBB
## 13 INSEE
## 14 INEGI
## 15 ISTAT
## 16 NOMIS
## 17 KNOEMA
## 18 WIDUKIND
## name
## 1 European Central Bank
## 2 Eurostat (Statistical office of the European Union)
## 3 International Monetary Fund
## 4 Organisation for Economic Cooperation and Development
## 5 United Nations Statistics Division
## 6 Food and Agriculture Organization of the United Nations
## 7 International Labour Organization of the United Nations
## 8 UNESCO Institute of Statistics (old - http://data.uis.unesco.org)
## 9 UNESCO Institute of Statistics (new - http://api.uis.unesco.org)
## 10 World Integrated Trade Solution
## 11 Australian Bureau of Statistics
## 12 National Bank of Belgium
## 13 Institut national de la statistique et des études économiques
## 14 Instituto Nacional de Estadística y Geografía (Méjico)
## 15 Istituto nazionale di statistica (Italia)
## 16 NOMIS - UK Official Labour Market Statistics
## 17 KNOEMA knowledge plateform
## 18 Widukind project - International Economics Database
## scale country builder compliant
## 1 international <NA> SDMXREST21RequestBuilder TRUE
## 2 international <NA> SDMXREST21RequestBuilder TRUE
## 3 international <NA> SDMXREST21RequestBuilder TRUE
## 4 international <NA> SDMXDotStatRequestBuilder FALSE
## 5 international <NA> SDMXREST21RequestBuilder TRUE
## 6 international <NA> SDMXREST21RequestBuilder FALSE
## 7 international <NA> SDMXREST21RequestBuilder FALSE
## 8 international <NA> SDMXDotStatRequestBuilder FALSE
## 9 international <NA> SDMXREST21RequestBuilder TRUE
## 10 international <NA> SDMXREST21RequestBuilder TRUE
## 11 national AUS SDMXDotStatRequestBuilder FALSE
## 12 national BEL SDMXDotStatRequestBuilder FALSE
## 13 national FRA SDMXREST21RequestBuilder TRUE
## 14 national MEX SDMXREST21RequestBuilder FALSE
## 15 national ITA SDMXREST21RequestBuilder TRUE
## 16 national UK SDMXRequestBuilder FALSE
## 17 international <NA> SDMXRequestBuilder FALSE
## 18 international <NA> SDMXREST21RequestBuilder FALSE
</code></pre>
<p>Note it is also possible to add an SDMX service provider at runtime. For registering a new SDMX service provider by default, please contact me!</p>
<p>Let's see how it would look like for querying an <code>OECD</code> datasource:</p>
<pre><code class="r">sdmx <- readSDMX(providerId = "OECD", resource = "data", flowRef = "MIG",
key = list("TOT", NULL, NULL), start = 2010, end = 2011)
df <- as.data.frame(sdmx)
head(df)
</code></pre>
<pre><code>## CO2 VAR GEN COU TIME_FORMAT obsTime obsValue OBS_STATUS
## 1 TOT B11 WMN AUS P1Y 2010 107740 <NA>
## 2 TOT B11 WMN AUS P1Y 2011 108865 <NA>
## 3 TOT B11 TOT AUS P1Y 2010 206714 <NA>
## 4 TOT B11 TOT AUS P1Y 2011 210704 <NA>
## 5 TOT B12 TOT AUS P1Y 2010 29320 <NA>
## 6 TOT B12 TOT AUS P1Y 2011 31232 <NA>
</code></pre>
<p>It is also possible to query a dataset together with its “definition”, handled
in a separate SDMX-ML document named <code>DataStructureDefinition</code> (DSD). It is
particularly useful when you want to enrich your dataset with all labels. For this,
you need the DSD which contains all reference data.</p>
<p>To do so, you only need to append <code>dsd = TRUE</code> (default value is <code>FALSE</code>),
to the previous request, and specify <code>labels = TRUE</code> when calling <code>as.data.frame</code>,
as follows:</p>
<pre><code class="r">sdmx <- readSDMX(providerId = "OECD", resource = "data", flowRef = "MIG",
key = list("TOT", NULL, NULL), start = 2010, end = 2011,
dsd = TRUE)
df <- as.data.frame(sdmx, labels = TRUE)
head(df)
</code></pre>
<pre><code>## CO2 CO2_label.fr CO2_label.en VAR
## 1 TOT Total Total B11
## 2 TOT Total Total B11
## 3 TOT Total Total B11
## 4 TOT Total Total B11
## 5 TOT Total Total B12
## 6 TOT Total Total B12
## VAR_label.fr
## 1 Entrées de personnes étrangères par nationalité
## 2 Entrées de personnes étrangères par nationalité
## 3 Entrées de personnes étrangères par nationalité
## 4 Entrées de personnes étrangères par nationalité
## 5 Sorties de personnes étrangères par nationalité
## 6 Sorties de personnes étrangères par nationalité
## VAR_label.en GEN GEN_label.fr
## 1 Inflows of foreign population by nationality WMN Femmes
## 2 Inflows of foreign population by nationality WMN Femmes
## 3 Inflows of foreign population by nationality TOT Total
## 4 Inflows of foreign population by nationality TOT Total
## 5 Outflows of foreign population by nationality TOT Total
## 6 Outflows of foreign population by nationality TOT Total
## GEN_label.en COU COU_label.fr COU_label.en TIME_FORMAT
## 1 Women AUS Australie Australia P1Y
## 2 Women AUS Australie Australia P1Y
## 3 Total AUS Australie Australia P1Y
## 4 Total AUS Australie Australia P1Y
## 5 Total AUS Australie Australia P1Y
## 6 Total AUS Australie Australia P1Y
## TIME_FORMAT_label.en obsTime obsValue OBS_STATUS OBS_STATUS_label.en
## 1 Annual 2010 107740 <NA> <NA>
## 2 Annual 2011 108865 <NA> <NA>
## 3 Annual 2010 206714 <NA> <NA>
## 4 Annual 2011 210704 <NA> <NA>
## 5 Annual 2010 29320 <NA> <NA>
## 6 Annual 2011 31232 <NA> <NA>
</code></pre>
<p>For embedded service providers that require a user authentication/subscription key or token,
it is possible to specify it in <code>readSDMX</code> with the <code>providerKey</code> argument. If provided,
and that the embedded provider requires a specific key parameter, the latter will be appended
to the SDMX web-request. For example, it's the case for the new <a href="UNESCO%20SDMX%20API">https://apiportal.uis.unesco.org/getting-started</a>.</p>
<p>Note that in case you are reading SDMX-ML documents with the native approach (with
URLs), instead of the embedded providers, it is also possible to associate a DSD
to a dataset by using the function <code>setDSD</code>. Let's try how it works:</p>
<pre><code class="r">#data without DSD
sdmx.data <- readSDMX(providerId = "OECD", resource = "data", flowRef = "MIG",
key = list("TOT", NULL, NULL), start = 2010, end = 2011)
#DSD
sdmx.dsd <- readSDMX(providerId = "OECD", resource = "datastructure", resourceId = "MIG")
#associate data and dsd
sdmx.data <- setDSD(sdmx.data, sdmx.dsd)
</code></pre>
<h3>Read <em>local</em> datasets</h3>
<p>This example shows you how to use <code>rsdmx</code> with <em>local</em> SDMX files, previously downloaded from <a href="http://ec.europa.eu/eurostat">EUROSTAT</a>.</p>
<pre><code class="r">#bulk download from Eurostat
tf <- tempfile(tmpdir = tdir <- tempdir()) #temp file and folder
download.file("http://ec.europa.eu/eurostat/estat-navtree-portlet-prod/BulkDownloadListing?sort=1&file=data%2Frd_e_gerdsc.sdmx.zip", tf)
sdmx_files <- unzip(tf, exdir = tdir)
#read local SDMX (set isURL = FALSE)
sdmx <- readSDMX(sdmx_files[2], isURL = FALSE)
stats <- as.data.frame(sdmx)
</code></pre>
<p>By default, <code>readSDMX</code> considers the data source is remote. To read a local file, add <code>isURL = FALSE</code>.</p>
<h2>Read metadata documents</h2>
<p>This section will introduce you on how to read SDMX <strong>metadata</strong> documents, including <code>concepts</code>, <code>codelists</code> and a complete <code>data structure definition</code> (DSD)</p>
<h3>Codelists</h3>
<p>Read codelists from <a href="http://data.fao.org/sdmx/index.html">FAO data portal</a></p>
<pre><code class="r">clUrl <- "http://data.fao.org/sdmx/registry/codelist/FAO/CL_FAO_MAJOR_AREA/0.1"
clobj <- readSDMX(clUrl)
cldf <- as.data.frame(clobj)
</code></pre>
<h3>Data Structure Definition (DSD)</h3>
<p>This example illustrates how to read a complete DSD using a <a href="http://stats.oecd.org">OECD StatExtracts portal</a> data source.</p>
<pre><code class="r">dsdUrl <- "http://stats.oecd.org/restsdmx/sdmx.ashx/GetDataStructure/TABLE1"
dsd <- readSDMX(dsdUrl)
</code></pre>
<p><code>rsdmx</code> is implemented in object-oriented way with <code>S4</code> classes and methods. The properties of <code>S4</code> objects are named <code>slots</code> and can be accessed with the <code>slot</code> method. The following code snippet allows to extract the list of <code>codelists</code> contained in the DSD document, and read one codelist as <code>data.frame</code>.</p>
<pre><code class="r">#get codelists from DSD
cls <- slot(dsd, "codelists")
#get list of codelists
codelists <- sapply(slot(cls, "codelists"), function(x) slot(x, "id"))
#get a codelist
codelist <- as.data.frame(slot(dsd, "codelists"), codelistId = "CL_TABLE1_FLOWS")
</code></pre>
<p>In a similar way, the <code>concepts</code> of the dataset can be extracted from the DSD and read as <code>data.frame</code>.</p>
<pre><code class="r">#get concepts from DSD
concepts <- as.data.frame(slot(dsd, "concepts"))
</code></pre>
<h2>Save & Reload SDMX R objects</h2>
<p>It is possible to save SDMX R objects as RData file (.RData, .rda, .rds), to then
be able to reload them into the R session. It could be of added value for users that
want to keep their SDMX objects in R data files, but also for fast loading of large SDMX
objects (e.g. DSD objects) for use in statistical analyses and R-based web-applications.</p>
<p>To save a SDMX R object to RData file:</p>
<p>To reload a SDMX R object from RData file:</p>
</body>
</html>
|
