This repository has been archived by the owner on Oct 24, 2023. It is now read-only.
forked from Edouard-Legoupil/koboloadeR
/
index.html
662 lines (641 loc) · 34.5 KB
/
index.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
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
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html>
<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.0">
<title>Retrieve Data Using the KoBo Toolbox API & Automatise data exploration • koboloadeR</title>
<!-- jquery --><script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script><!-- Font Awesome icons --><link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">
<!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js" integrity="sha384-cV+rhyOuRHc9Ub/91rihWcGmMmCXDeksTtCihMupQHSsi8GIIRDG0ThDc3HGQFJ3" crossorigin="anonymous"></script><!-- sticky kit --><script src="https://cdnjs.cloudflare.com/ajax/libs/sticky-kit/1.1.3/sticky-kit.min.js" integrity="sha256-c4Rlo1ZozqTPE2RLuvbusY3+SU1pQaJC0TjuhygMipw=" crossorigin="anonymous"></script><!-- pkgdown --><link href="pkgdown.css" rel="stylesheet">
<script src="pkgdown.js"></script><meta property="og:title" content="Retrieve Data Using the KoBo Toolbox API & Automatise data exploration">
<meta property="og:description" content="This package facilitates the data crunching & exploration for dataset collected using xlsform.">
<meta name="twitter:card" content="summary">
<!-- mathjax --><script src="https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></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>
<div class="container template-home">
<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">
<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">koboloadeR</a>
<span class="label label-default" data-toggle="tooltip" data-placement="bottom" title="Released package">0.1.5</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="index.html">
<span class="fa fa-home fa-lg"></span>
</a>
</li>
<li>
<a href="reference/index.html">Reference</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
Articles
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="articles/examples.html">KoboloadeR Examples</a>
</li>
</ul>
</li>
<li>
<a href="news/index.html">Changelog</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/unhcr/koboloadeR">
<span class="fa fa-github fa-lg"></span>
</a>
</li>
</ul>
</div>
<!--/.nav-collapse -->
</div>
<!--/.container -->
</div>
<!--/.navbar -->
</header><div class="row">
<div class="contents col-md-9">
<div id="introduction" class="section level1">
<div class="page-header"><h1 class="hasAnchor">
<a href="#introduction" class="anchor"></a>Introduction</h1></div>
<p>koboloadeR is a R package to conduct data discovery and analysis for data collected through <a href="https://www.kobotoolbox.org/">KoboToolbox</a>, <a href="https://opendatakit.org/">ODK</a>, <a href="https://ona.io/home/">ONA</a> or any <strong><a href="http://xlsform.org">xlsform</a></strong> compliant data collection platform. This package first builds on the capacity of UNHCR Kobo server @ <a href="http://kobo.unhcr.org" class="uri">http://kobo.unhcr.org</a> but it can also be used from any structured dataset.</p>
</div>
<div id="approach" class="section level1">
<h1 class="hasAnchor">
<a href="#approach" class="anchor"></a>Approach</h1>
<p>The main concept behind the package is to implement a survey data analysis plan and configuration directly within the <a href="http://xlsform.org">xlsform</a> excel file that has been used to develop the questionnaire. A few additional column are created in this excel document, the package read those column to generate a series of predefined report.</p>
<p><img src="https://raw.githubusercontent.com/unhcr/koboloadeR/gh-pages/inst/script/workflow.png" alt="alt text"></p>
<p>This approach has the following advantages:</p>
<ul>
<li><p>End users <strong>do not need to code</strong> in R and to master the language in order to use the package;</p></li>
<li><p>The data <strong>analysis plan</strong> is de facto fully documented and described;</p></li>
<li><p>The resulting data crunching reports are fully <strong>reproducible</strong>;</p></li>
<li><p>Analysis <strong>iterations</strong> are facilitated;</p></li>
<li><p>Good <strong>practises</strong> are enforced through the package.</p></li>
</ul>
<p>To go in more details, the suggested workflow is presented below (note that all of it is not yet fully implented - see <a href="https://github.com/unhcr/koboloadeR/issues">issue tracking for more details</a>)</p>
<p><img src="https://raw.githubusercontent.com/unhcr/koboloadeR/gh-pages/inst/script/workflow2.png" alt="alt text"></p>
</div>
<div id="features" class="section level1">
<h1 class="hasAnchor">
<a href="#features" class="anchor"></a>Features</h1>
<p>The <code>koboloadeR</code> package allows to:</p>
<ul>
<li><p>connect to the <a href="https://kc.kobotoolbox.org/api/v1/">KoBo API (v1)</a> for the <a href="http://www.kobotoolbox.org/">KoBo Toolbox</a> project.</p></li>
<li><p>compute a data dictionnary based on <a href="http://xlsform.org">xlsform</a>. It implies ot have a few additionnal column in the xlsform in order to better define how data shoudl be analysid (cf infra). as it based on a standard, this part and the following should work for any <a href="http://xlsform.org/#xlsform-tools">xlsform compatible server</a> such as <a href="https://opendatakit.org/">OpenDataKit</a> or <a href="https://ona.io/home/">ONA</a></p></li>
<li><p>generate automatically of a series of charts & maps based on the data dictionnary</p></li>
<li><p>generate automatically of a series of charts & maps based on a formatted data analysis plan</p></li>
<li><p>access to a series of dedicated Shiny application to set up your project</p></li>
<li><p>support the full range of data science level</p></li>
</ul>
<p><img src="https://raw.githubusercontent.com/unhcr/koboloadeR/gh-pages/inst/script/datascience.png" alt="alt text"></p>
</div>
<div id="koboloader-quick-setup-and-walk-through" class="section level1">
<h1 class="hasAnchor">
<a href="#koboloader-quick-setup-and-walk-through" class="anchor"></a>koboloadeR quick setup and Walk Through</h1>
<div id="prerequisite" class="section level2">
<h2 class="hasAnchor">
<a href="#prerequisite" class="anchor"></a>Prerequisite</h2>
<p>To be able to use koboloadeR you will need:</p>
<ul>
<li><p>R: download here: <a href="https://cran.rstudio.com/" class="uri">https://cran.rstudio.com/</a>). For Windows, choose “install R for the first time”.</p></li>
<li><p>R Studio (<a href="https://www.rstudio.com/products/rstudio/download/#download" class="uri">https://www.rstudio.com/products/rstudio/download/#download</a>)</p></li>
</ul>
</div>
<div id="software-installation" class="section level2">
<h2 class="hasAnchor">
<a href="#software-installation" class="anchor"></a>Software installation</h2>
<ul>
<li>Install R: follow instruction from the installer.</li>
<li>Install R Studio: follow instruction from the installer</li>
<li>Launch R Studio</li>
</ul>
<div id="package-installation-koboloader-from-github-up-to-date-version" class="section level3">
<h3 class="hasAnchor">
<a href="#package-installation-koboloader-from-github-up-to-date-version" class="anchor"></a>Package installation: koboloadeR from Github (up to date version):</h3>
<p>Note that the package is still in beta-version. We hope to have soon a release available on CRAN.</p>
<ul>
<li>Open R studio interface and within the R console, install ‘devtool’ package:</li>
</ul>
<pre><code>install.packages("devtools")</code></pre>
<ul>
<li>Install koboloadeR:</li>
</ul>
<pre><code>library(devtools)
install_github("unhcr/koboloadeR", ref = "gh-pages")
</code></pre>
<ul>
<li>You are all set! You can know use koboloadeR. If you have a problem consult the common troubleshooting part at the end of this page.</li>
</ul>
</div>
</div>
</div>
<div id="quick-start" class="section level1">
<h1 class="hasAnchor">
<a href="#quick-start" class="anchor"></a>Quick start</h1>
<div id="create-a-project" class="section level2">
<h2 class="hasAnchor">
<a href="#create-a-project" class="anchor"></a>Create a project</h2>
<p>First, in R Studio:</p>
<ul>
<li>In R Studio, select File, click New project. A box opens</li>
<li>Choose New Directory</li>
<li>Choose Empty project</li>
<li>Type the name of the folder where you want to put your data</li>
<li>Select where you want to put this folder</li>
<li>Click Create project</li>
</ul>
<p>Then setup a few things: run those two lines:</p>
<pre><code>library (koboloadeR) # This loads koboloadeR package
kobo_projectinit() # Creates folders necessary and transfer files needed</code></pre>
<p>It might take a while as a few other packages have to be installed or loaded. Once the see the " >" again at the beginning of the line, you can run:</p>
<pre><code><a href="reference/kobo_shiny.html">kobo_shiny("app_koboloadeR.R")</a></code></pre>
<p>This will launch a graphic interface with other instructions and options.</p>
<p>For better performances, select “Open in Browser” on the top of the window.</p>
</div>
<div id="get-your-data" class="section level2">
<h2 class="hasAnchor">
<a href="#get-your-data" class="anchor"></a>Get your data</h2>
<p>Either:</p>
<ul>
<li>Grab your data with <code>kobo_data_downloader</code> & Get your form with <code>kobo_form</code>
</li>
<li>or simply copy your data in <code>csv</code> format and your xlsform in <code>xls</code> format in the <code>data</code> folder that was created during the project initiation</li>
</ul>
<p>use the following options to extract data <img src="https://raw.githubusercontent.com/unhcr/koboloadeR/gh-pages/inst/script/exportformat.png" alt="alt text"></p>
<p>You may also use a dedicated shinyapp for this</p>
<pre><code><a href="reference/kobo_shiny.html">kobo_shiny("app_dataviewer.R")</a></code></pre>
</div>
</div>
<div id="build-a-sample" class="section level1">
<h1 class="hasAnchor">
<a href="#build-a-sample" class="anchor"></a>Build a sample</h1>
<p>You may also use a dedicated shinyapp for this</p>
<pre><code><a href="reference/kobo_shiny.html">kobo_shiny("app_sampling.R")</a></code></pre>
</div>
<div id="resources" class="section level1">
<h1 class="hasAnchor">
<a href="#resources" class="anchor"></a>Resources</h1>
<p>Here are a few introductions and tutorials for R:</p>
<ul>
<li>A good introduction to R here: <a href="https://ismayc.github.io/rbasics-book" class="uri">https://ismayc.github.io/rbasics-book</a>
</li>
<li>An introduction to R: complete but not very user-friendly: <a href="https://cran.r-project.org/doc/manuals/r-release/R-intro.html" class="uri">https://cran.r-project.org/doc/manuals/r-release/R-intro.html</a>
</li>
<li>Try R: <a href="http://tryr.codeschool.com/" class="uri">http://tryr.codeschool.com/</a>
</li>
<li>Data Camp’s Introduction to R: <a href="https://www.datacamp.com/courses/free-introduction-to-r" class="uri">https://www.datacamp.com/courses/free-introduction-to-r</a>
</li>
</ul>
<p>To go further:</p>
<ul>
<li><a href="https://www.rstudio.com/online-learning/" class="uri">https://www.rstudio.com/online-learning/</a></li>
<li><a href="https://www.r-bloggers.com/how-to-learn-r-2/" class="uri">https://www.r-bloggers.com/how-to-learn-r-2/</a></li>
</ul>
</div>
<div id="background-elements-on-the-package" class="section level1">
<h1 class="hasAnchor">
<a href="#background-elements-on-the-package" class="anchor"></a>Background elements on the package</h1>
<div id="challenges-with-household-survey-analysis" class="section level2">
<h2 class="hasAnchor">
<a href="#challenges-with-household-survey-analysis" class="anchor"></a>Challenges with Household Survey analysis</h2>
<p>Household survey often results in dataset with over 300 variables to process & explore. In Humanitarian Environment, deadlines to get insights from those dataset are often tight. Manual processing is very lengthy and can be done only for a limited part of the dataset. Often, because of those challenges, a lot of potential insights are not discovered. This package is developped to support this challenge around data crunching. It’s part of the initiative around an <a href="https://unhcr.github.io/Integrated-framework-household-survey/">Integrated Framework for Household Survey (IFHS): A toolkit to facilitate design, collection & analysis</a>.</p>
</div>
<div id="data-crunching" class="section level2">
<h2 class="hasAnchor">
<a href="#data-crunching" class="anchor"></a>Data Crunching</h2>
<p>KoboloadeR packages aims at separating “<em>input</em>”, “<em>processing</em>” and “<em>output</em>” within the data crunching phase of the data analysis worklfow.</p>
<p>The “output” will be one or multiple Rmd (Rmarkdown) file(s) than will generate word, pdf or html reports and the configuration file includes references to all “input”:</p>
<ul>
<li>Path to <strong>raw data</strong> files collected using <a href="https://opendatakit.org/">OpenDataKit</a>, <a href="http://www.kobotoolbox.org/">Kobotoolbox</a> or <a href="https://ona.io">ONA</a><br>
</li>
<li>Path to form (defined using the standard format <a href="http://xlsform.org">xlsform</a>) in order to build a <strong>data dictionary</strong><br>
</li>
<li>Path to the <strong>sample weight</strong> for each observation (based on cluster or strata…)<br>
</li>
<li>Path to the data <strong>cleaning log</strong><br>
</li>
<li>Path to the <strong>indicator calculation</strong> sheet</li>
</ul>
</div>
<div id="advantage-of-koboloader" class="section level2">
<h2 class="hasAnchor">
<a href="#advantage-of-koboloader" class="anchor"></a>Advantage of KoboLoadeR</h2>
<ul>
<li>
<strong>Productivity</strong>: Once the configuration file is written, run the script in Rstudio to get the output</li>
<li>
<strong>Training</strong>: No need to write R instruction – limited knowledge of R is required</li>
<li>
<strong>Iteration</strong>: Check the output, adjust the various input files & re-run the script till you get a satisfying report</li>
<li>
<strong>Reproducibility</strong>: all analysis input are de facto documented</li>
</ul>
<p>KoboLoadeR takes care of the processing component so that the technical team can focus on the interpretation.</p>
</div>
<div id="output-of-koboloader" class="section level2">
<h2 class="hasAnchor">
<a href="#output-of-koboloader" class="anchor"></a>Output of koboloadeR</h2>
<ul>
<li>Frequency tables & Bar chart for select type questions</li>
<li>Frequency tables & Histogram for numeric questions</li>
<li>Frequency table for text questions</li>
<li>Cross-tab & graph (if 2 categorical: bar chart, if 1 categoric + 1 numeric: boxplot & if 2 numeric: scatterplot)</li>
<li>Chi-squared test & corrplot presentation</li>
<li>Mapping if geographic field are configured (still in development)</li>
<li>and more to come…</li>
</ul>
</div>
<div id="data-analysis-plan-within-your-xlsfrom" class="section level2">
<h2 class="hasAnchor">
<a href="#data-analysis-plan-within-your-xlsfrom" class="anchor"></a>Data Analysis Plan within your <code>xlsfrom</code>
</h2>
<p><code>Xlsform</code> is a convenient format to build advance form using any spreadsheet software such as <a href="https://www.libreoffice.org/download/libreoffice-fresh/">Libreoffice</a> or MsExcel.</p>
<p>In order to build an an analysis plan within the form, the columns described in the tables below needs to be added. Note that if the column are not present, the script will create dummy ones. It’s always possible to add your analysis plan to an existing form and relaunch <code>kobo_dico</code> in order to regenerate the correct analysis plan.</p>
<p>Note that for charting purpose, it’s recommanded that labels for questions & choices should not exceed 70 characters. It’s possible again to re-edit directly your xlsform and regenerate a new <code>dico</code>.</p>
<div id="in-the-survey-worksheet" class="section level3">
<h3 class="hasAnchor">
<a href="#in-the-survey-worksheet" class="anchor"></a>In the <code>survey</code> worksheet:</h3>
<table class="table">
<colgroup>
<col width="58%">
<col width="41%">
</colgroup>
<thead><tr class="header">
<th>Column</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr class="odd">
<td><code>chapter</code></td>
<td>used to breakfdown the final report</td>
</tr>
<tr class="even">
<td><code>disaggregation</code></td>
<td>used to flag variables used to <code>facet</code> dataset</td>
</tr>
<tr class="odd">
<td><code>correlate</code></td>
<td>used to flag variables used for statistical test of independence (for categorical variable) or correlation for numeric variable</td>
</tr>
<tr class="even">
<td><code>variable</code></td>
<td>used to flag <code>ordinal</code> variables so that graphs are not ordered per frequency.</td>
</tr>
<tr class="odd">
<td><code>anonymise</code></td>
<td>used to generate an anonymised datset in line the anonymisation plan within the xlsform</td>
</tr>
<tr class="even">
<td><code>structuralequation</code></td>
<td>used to tag variables to the standard structural equation model: <code>risk</code>, <code>coping</code>, <code>vulnerability</code>
</td>
</tr>
<tr class="odd">
<td><code>clean</code></td>
<td>used to flag external csv file to be used for the cleaning of a specific variable</td>
</tr>
<tr class="even">
<td><code>cluster</code></td>
<td>used to flag variables used for statistical clustering</td>
</tr>
<tr class="odd">
<td><code>predict</code></td>
<td>used to flag variables to be predicted based on a joined registration dataset</td>
</tr>
<tr class="even">
<td><code>mappoint</code></td>
<td>used to flag variables to be mapped as point</td>
</tr>
<tr class="odd">
<td><code>mappoly</code></td>
<td>used to flag variables to be mapped as polygon</td>
</tr>
</tbody>
</table>
</div>
<div id="in-the-choices-worksheet" class="section level3">
<h3 class="hasAnchor">
<a href="#in-the-choices-worksheet" class="anchor"></a>In the <code>choices</code> worksheet:</h3>
<table class="table">
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead><tr class="header">
<th>Column</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr class="odd">
<td><code>order</code></td>
<td>used to define order for ordinal variables</td>
</tr>
<tr class="even">
<td><code>weight</code></td>
<td>used to define weight for each answers in case it’s used for some specific indicator calculation</td>
</tr>
<tr class="odd">
<td><code>recategorise</code></td>
<td>used to recategorise quickly choices for a question</td>
</tr>
</tbody>
</table>
</div>
<div id="in-a-separate-indicator-worksheet" class="section level3">
<h3 class="hasAnchor">
<a href="#in-a-separate-indicator-worksheet" class="anchor"></a>In a separate <code>indicator</code> worksheet:</h3>
<p>The idea is to map calculation necessary to create complex indicators from the variables defined in the <code>survey</code> worksheet. This will document and automate the generation of indicators (i.e. feature enginerring). This worksheet will allow to generate an additional elements to the data dictionnnary – i.e. <code>dico</code> dataframe.</p>
<p>Below are the minimum elements/column to document:</p>
<table class="table">
<colgroup>
<col width="30%">
<col width="70%">
</colgroup>
<thead><tr class="header">
<th>Column</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr class="odd">
<td><code>type</code></td>
<td>type of indicator select_one or integer or numeric</td>
</tr>
<tr class="even">
<td><code>name</code></td>
<td>short name for the indicator</td>
</tr>
<tr class="odd">
<td><code>label</code></td>
<td>label for the indicator</td>
</tr>
<tr class="even">
<td><code>chapter</code></td>
<td>chapter to include the indicator in</td>
</tr>
<tr class="odd">
<td><code>frame</code></td>
<td>frame to use to append the idnicator to</td>
</tr>
<tr class="even">
<td><code>calculation</code></td>
<td>used to reference the calculation. This will be a precise R formula</td>
</tr>
</tbody>
</table>
<p>define wether the indicator is <code>Measurement</code>: variable used to quantify other indicators, <code>Disaggregation</code>: variable that describes certain groups, <code>Predictor</code>: Indicator that describes the cause of a situation, <code>Outcome</code>: Indicator that describes the consequence of a situation or <code>Judgment</code>: indicator that translates a subjective assessment method to be used for the indicator: <code>Percentage</code>, <code>Sum</code>, <code>Max/Min</code>, <code>Average</code>, <code>Score</code>, <code>Denominator</code>, <code>Numerator</code>, <code>Numerator.external</code> (i.e. linked to an external value)</p>
</div>
</div>
<div id="shiny-apps" class="section level2">
<h2 class="hasAnchor">
<a href="#shiny-apps" class="anchor"></a>Shiny Apps</h2>
<p>The package contains the following Shiny apps, accessible via <code><a href="reference/kobo_apps.html">kobo_apps("app_name")</a></code>:</p>
<table class="table">
<colgroup>
<col width="50%">
<col width="50%">
</colgroup>
<thead><tr class="header">
<th>App</th>
<th>Description</th>
</tr></thead>
<tbody><tr class="odd">
<td><code>"data_viewer"</code></td>
<td>The <code>"data_viewer"</code> app provides a basic login screen to authenticate against the specified API. Once authenticated, the datasets available via the specified login are displayed, and a dropdown list is populated with which one can select the dataset they want to view. The dataset is also made available in the users Global Environment.</td>
</tr></tbody>
</table>
<p>Here’s <a href="http://news.mrdwab.com/post/koboloader/">a blog post introducing the package</a>!</p>
</div>
<div id="gettinf-data-from-api" class="section level2">
<h2 class="hasAnchor">
<a href="#gettinf-data-from-api" class="anchor"></a>Gettinf data from API</h2>
<p>The following examples access the public data available via KoBo Toolbox. Note that all of the functions have been set with defaults of <code>user = NULL</code> and <code>api = 'kobo'</code>.</p>
<pre><code>kobo_datasets()[, c("description", "id"), with = FALSE] ## Just show the first two columns
# description id
# 1: 关于“西装微定制现状的调查“ 10427
# 2: زانیاری لەسەر كۆمپانیاكانی نەوت لە گەرمیان 11190
# 3: מיפוי שדרות צ'רצ'יל - ורד ויואב 12568
# 4: Test 39717
# 5: Market Survey 7640
# ---
# 403: Webuy_Stock lot Business (No.1 Stock Bazar in Bangladesh) 30792
# 404: WWF Zambia [Field Reporter] 4163
# 405: xls_form_training 41820
# 406: Mwanza KAP SURVEY 2015 25206
# 407: Elisha Zelina, GST6109 1857
kobo_submission_count(4163)
# [1] 37
kobo_data_downloader("4163")
# No local dataset found.
# Downloading remote file.
# ... The contents would normally be printed here
### On a subsequent run, if the file is already there and no changes have been made
kobo_data_downloader("4163")
# Number of rows in local and remote file match.
# Using local file.</code></pre>
<p>The <code>kobo_data_downloader</code> automatically checks for the existence of an object in your workspace named “data_####” (where “####” is the numeric form ID). If such an object is found, it then uses <code>kobo_submission_count</code> to compare the number of rows in the local dataset against the number of rows in the remote dataset. If the number is found to be different, the remote dataset is re-downloaded. If they are found to be the same, the local dataset is used.</p>
<p>In the future, it is intended that there would be a more robust and efficient method rather than redownloading the entire dataset each time a change has been detected.</p>
<hr>
<p>Run the examples at the help pages to get a sense of some of the other features:</p>
<pre><code>example("kobo_datasets")
example("kobo_submission_count")
example("kobo_data_downloader")</code></pre>
</div>
<div id="authentication" class="section level2">
<h2 class="hasAnchor">
<a href="#authentication" class="anchor"></a>Authentication</h2>
<p>These functions all use basic HTTP authentication. The easiest way to enter the password details is the common <code>"username:password"</code> approach. Thus, when accessing form data using authentication, the function would be used in the following manner:</p>
<pre><code><a href="reference/kobo_data_downloader.html">kobo_data_downloader("123456", "username:password")</a></code></pre>
</div>
<div id="anonymisation" class="section level2">
<h2 class="hasAnchor">
<a href="#anonymisation" class="anchor"></a>Anonymisation</h2>
<p>This method should be used whenever Kobo or ODK forms are used as data collection tools and personal data is being collected. Even when personal data is not being collected it still may be appropriate to apply the methodology since quasi-identifiable data or other sensitive data could lead to personal identification or should not be shared.</p>
<table class="table">
<colgroup>
<col width="53%">
<col width="46%">
</colgroup>
<thead><tr class="header">
<th>Type</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr class="odd">
<td><strong>Direct identifiers</strong></td>
<td>Can be directly used to identify an individual. E.g. Name, Address, Date of birth, Telephone number, GPS location</td>
</tr>
<tr class="even">
<td><strong>Quasi- identifiers</strong></td>
<td>Can be used to identify individuals when it is joined with other information. E.g. Age, Salary, Next of kin, School name, Place of work</td>
</tr>
<tr class="odd">
<td><strong>Sensitive information</strong></td>
<td>& Community identifiable information Might not identify an individual but could put an individual or group at risk. E.g. Gender, Ethnicity, Religious belief</td>
</tr>
</tbody>
</table>
<p>The following are different anonymisation actions that can be performed on sensitive fields. The type of anonymisation should be dictated by the desired use of the data. A good approach to follow is to start from the minimum data required, and then to identify if any of those fields should be obscured.</p>
<p>The methods below can be referenced in the dedicated column within xlsform (cf above)</p>
<div id="how-to-reference-the-anonymisation-plan-in-the-xlsfrom-" class="section level3">
<h3 class="hasAnchor">
<a href="#how-to-reference-the-anonymisation-plan-in-the-xlsfrom-" class="anchor"></a>How to reference the anonymisation plan in the xlsfrom.</h3>
<p>The <code>anonymise</code> column is used to reference the anonymisation plan. it can take the following values.</p>
<table class="table">
<colgroup>
<col width="53%">
<col width="46%">
</colgroup>
<thead><tr class="header">
<th>Method</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr class="odd">
<td><strong>remove</strong></td>
<td>Variable is removed entirely from the data set. The Variable is preserved in the original file.</td>
</tr>
<tr class="even">
<td><strong>reference</strong></td>
<td>Variable is removed entirely from the data set and is copied into a reference file. A random unique identifier field is added to the reference file and the data set so that they can be joined together in future. The reference file is never shared and the Variable is also preserved in the original file.</td>
</tr>
<tr class="odd">
<td><strong>key</strong></td>
<td>Variable to be consisdered for k-anonymity & individual disclosure risk analysis (i.e. quasi-identifiers)</td>
</tr>
<tr class="even">
<td><strong>outlier</strong></td>
<td>Variable is removed entirely</td>
</tr>
<tr class="odd">
<td><strong>sensitve</strong></td>
<td>Variable is removed entirely</td>
</tr>
</tbody>
</table>
</div>
<div id="potential-good-practices" class="section level3">
<h3 class="hasAnchor">
<a href="#potential-good-practices" class="anchor"></a>Potential Good practices</h3>
<p>Data about who, where and how the data is collected is often stored separately to the main data and can be used identify individuals (i.e. metadata will be removed)</p>
<p>Text variables likely to be removed as well…</p>
<p>The Variable values are replaced with meaningless values but the categories are preserved. A reference file is created to link the original value with the meaningless value. Typically applied to categorical Variable . For example, Town names could be masked with random combinations of letters. It would still be possible to perform statisitical analysis on the Variable but the person running the analysis would not be able to identify the original values, they would only become meaningful when replaced with the original values. The reference file is never shared and the data is also preserved in the original file.</p>
<p>Generalise</p>
<p>Continuous Variable is turned into categorical or ordinal Variable by summarising it into ranges. For example, Age could be turned into age ranges, Weight could be turned into ranges. It can also apply to categorical Variable where parent groups are created. For example, illness is grouped into illness type. Generalised Variable can also be masked for extra anonymisation. The Variable is preserved in the original file.</p>
</div>
</div>
</div>
<div id="common-troubleshooting" class="section level1">
<h1 class="hasAnchor">
<a href="#common-troubleshooting" class="anchor"></a>Common Troubleshooting</h1>
<p>Before anything else, try to restart the R session:</p>
<ul>
<li>In R studio, on top go to “Session”</li>
<li>“Restart R”</li>
</ul>
<div id="can-not-install-the-package" class="section level2">
<h2 class="hasAnchor">
<a href="#can-not-install-the-package" class="anchor"></a>Can not install the package</h2>
<p>Note that in case you get the following error:</p>
<pre><code>InternetOpenUrl failed: 'An error occurred in the secure channel support'</code></pre>
<p>Enter the command:</p>
<pre><code>setInternet2(TRUE)</code></pre>
<p>Alternatively, you may add to .Rprofile or Rprofile.site the following line:</p>
<pre><code>options(download.file.method = "wininet")</code></pre>
</div>
<div id="unable-to-move-temporary-installation" class="section level2">
<h2 class="hasAnchor">
<a href="#unable-to-move-temporary-installation" class="anchor"></a>Unable to move temporary installation</h2>
<p>One common errors during the package installation is linked to the antivirus <em>“real time file system protection”</em>. The following will fix the problem:</p>
<pre><code>trace(utils:::unpackPkgZip, edit=TRUE)
</code></pre>
<p>Edit line 140:</p>
<pre><code>Sys.sleep(0.5)
</code></pre>
<p>to:</p>
<pre><code>Sys.sleep(2)
</code></pre>
<div id="the-application-crashed" class="section level3">
<h3 class="hasAnchor">
<a href="#the-application-crashed" class="anchor"></a>The application crashed</h3>
<p>If the application (graphic interface) crashes, make sure that all packages necessary are loaded with:</p>
<pre><code>source("code/0-packages.R")</code></pre>
<p>Also make sure that you downloaded your data in the right format:</p>
<ul>
<li>Export as XLS</li>
<li>XML values and headers</li>
<li>Include groups in headers</li>
<li>‘Group separator’ as dot (‘.’)</li>
</ul>
</div>
<div id="error-when-building-the-dictionnary-or-configuration-file" class="section level3">
<h3 class="hasAnchor">
<a href="#error-when-building-the-dictionnary-or-configuration-file" class="anchor"></a>Error when building the dictionnary or configuration file</h3>
<p>If you see this message (or similar error):</p>
<pre><code>Error in file(file, ifelse(append, "a", "w")) :
cannot open the connection</code></pre>
<p>It is most likely because you have the form, dictionary or data set open on your computer. If you close it and start over, the problem should be fixed.</p>
</div>
<div id="error-when-loading-packages" class="section level3">
<h3 class="hasAnchor">
<a href="#error-when-loading-packages" class="anchor"></a>Error when loading packages</h3>
<p>If you get this error:</p>
<pre><code>Error: package or namespace load failed for 'rJava'</code></pre>
<p>It could be because you have a 64bit version of R, but have a 32bit version of Java. Check this thread for guidance: <a href="https://stackoverflow.com/questions/37735108/r-error-onload-failed-in-loadnamespace-for-rjava" class="uri">https://stackoverflow.com/questions/37735108/r-error-onload-failed-in-loadnamespace-for-rjava</a></p>
</div>
</div>
</div>
</div>
<div class="col-md-3" id="sidebar">
<div class="links">
<h2>Links</h2>
<ul class="list-unstyled">
<li>Browse source code at <br><a href="https://github.com/unhcr/koboloadeR">https://github.com/unhcr/koboloadeR</a>
</li>
<li>Report a bug at <br><a href="https://github.com/unhcr/koboloadeR/issues">https://github.com/unhcr/koboloadeR/issues</a>
</li>
</ul>
</div>
<div class="license">
<h2>License</h2>
<ul class="list-unstyled">
<li><a href="https://www.r-project.org/Licenses/GPL-3">GPL-3</a></li>
</ul>
</div>
<div class="developers">
<h2>Developers</h2>
<ul class="list-unstyled">
<li>Edouard Legoupil <br><small class="roles"> Author, maintainer </small> </li>
<li>Maher Daoud <br><small class="roles"> Author </small> </li>
<li><a href="authors.html">All authors...</a></li>
</ul>
</div>
</div>
</div>
<footer><div class="copyright">
<p>Developed by Edouard Legoupil, Maher Daoud.</p>
</div>
<div class="pkgdown">
<p>Site built with <a href="http://pkgdown.r-lib.org/">pkgdown</a>.</p>
</div>
</footer>
</div>
</body>
</html>