-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathREADME.Rmd
executable file
·213 lines (163 loc) · 10.1 KB
/
README.Rmd
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
---
output:
github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
warning = FALSE,
message = FALSE,
eval = FALSE,
fig.width = 10,
fig.path = "man/figures",
comment = "#> "
)
```
# robotoolbox <img src="man/figures/robotoolbox_hex.png" align="right" width="140" />
[](https://www.repostatus.org/#active)
[](https://gitlab.com/dickoa/robotoolbox/-/pipelines)
[](https://app.codecov.io/gl/dickoa/robotoolbox)
[](https://CRAN.R-project.org/package=robotoolbox)
[](https://opensource.org/license/mit)
`robotoolbox` is an R client to access and manage data from [KoboToolbox](https://www.kobotoolbox.org/), a powerful tool for collecting and analyzing data in challenging environments.
## Features
- Easy authentication with KoboToolbox API
- List and access KoboToolbox assets
- Retrieve and process survey submissions
- Handle multi-language survey forms
- Work with repeating groups in survey data
- Process spatial data from KoboToolbox
- Access and analyze audit logging data
- Download media attachments
## Installation
The package is available on CRAN, Gitlab (dev) and Github (mirror).
### Stable version (CRAN)
```{r}
install.packages("robotoolbox")
```
### Development version
you will need the [`remotes`](https://github.com/r-lib/remotes) package to install it from Gitlab and Github. You can also use the [`pak`](https://github.com/r-lib/pak) package to install it from Github.
```{r}
## From Gitlab
remotes::install_gitlab("dickoa/robotoolbox")
## From Github
pak::pkg_install("dickoa/robotoolbox")
```
## robotoolbox: A quick tutorial
The `robotoolbox` package is a client to [`KoboToolbox API v2`](https://support.kobotoolbox.org/api.html). You will need to set your API token and specify the `KoboToolbox` server URL. The easiest way to set up `robotoolbox` is to store the token and the URL in your `.Renviron` file, which is automatically read by `R` on startup.
### Getting the API token
You can retrieve your `API token` by following the instruction in the official API documentation: https://support.kobotoolbox.org/api.html.
You can also get your token directly from `R` using the `kobo_token` function.
The following examples will utilize UNHCR `KoboToolbox` server url (https://kobo.unhcr.org/). You can replace this URL with https://kf.kobotoolbox.org/, https://kobo.humanitarianresponse.info/ or any other `KoboToolbox` server URL you typically use.
```{r}
kobo_token(username = "xxxxxxxxx",
password = "xxxxxxxxx",
url = "https://kobo.unhcr.org")
```
### Setting up Your Session
You can either edit directly the `.Renviron` file or access it by calling `usethis::edit_r_environ()` (assuming you have the `usethis` package installed) and entering the following two lines:
```{bash, eval=FALSE, engine="sh"}
KOBOTOOLBOX_URL="https://kobo.unhcr.org/"
KOBOTOOLBOX_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxx
```
Or use directly the `kobo_setup` function
```{r}
kobo_setup(url = "https://kobo.unhcr.org",
token = "xxxxxxxxxxxxxxxxxxxxxxxxxx")
```
You can check the settings using the `kobo_settings` function.
```{r}
library("robotoolbox")
kobo_settings()
## <robotoolbox settings>
## KoboToolbox URL: https://kobo.unhcr.org/
## KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxx
```
With the settings done, it is possible to list all `assets` (e.g surveys, questions, etc) for the account associated to the token and URL.
### Accessing data
```{r}
library("dplyr")
l <- kobo_asset_list()
l
# A tibble: 24 x 7
uid name asset_type owner_username date_created
<chr> <chr> <chr> <chr> <dttm>
1 b9kgvd… Proj_A1… survey xxxxxxxxxxxxx… 2020-04-27 20:34:23
2 aRFJMp… Proj_A2… survey xxxxxxxxxxxxx… 2020-04-27 21:21:12
3 a6qMG7… Proj_A3… survey xxxxxxxxxxxxx… 2021-05-25 16:59:08
4 azhrVs… Proj_A4… survey xxxxxxxxxxxxx… 2021-05-25 13:59:46
5 aReR58… Proj_A5… survey xxxxxxxxxxxxx… 2021-06-07 09:15:53
6 aWaoqy… Proj_A6… survey xxxxxxxxxxxxx… 2021-05-29 10:46:09
7 aABU3C… Proj_A7… survey xxxxxxxxxxxxx… 2020-11-28 15:00:10
8 aaznyX… Proj_A9… survey xxxxxxxxxxxxx… 2020-11-28 14:28:48
9 aCVr2Q… Proj_A9… survey xxxxxxxxxxxxx… 2021-05-25 13:30:24
10 aPxNao… Proj_A10… survey xxxxxxxxxxxxx… 2020-04-27 11:37:34
# … with 14 more rows, and 3 more variables:
# date_modified <dttm>, submissions <int>
glimpse(l)
$ uid <chr> "b9kgvd7AXQCmo5qyUOBEl", "aRfJMpTSGRLzZ…"
$ name <chr> "Proj_A1", "Proj_A2", "Proj_A3", "Proj_A…"
$ asset_type <chr> "survey", "survey", "survey", "survey", …
$ owner_username <chr> "xxxxxxxxxxxxxx", "xxxxxxxxxxxxxxx", "xx…"
$ date_created <dttm> 2020-04-27 20:34:23, 2020-04-27 21:21:1…
$ date_modified <dttm> 2021-06-17 01:52:57, 2021-06-17 01:52:5…
$ submissions <int> 2951, 2679, 2, 1, 0, 0, 287, 73, 0, 274,…
```
The list of `assets` is a `tibble`, you can filter it to select the form unique identifier `uid` that uniquely identify the API asset you want to open. The function `kobo_asset` can then be used to get the `asset` from the `uid`.
```{r}
uid <- l |>
filter(name == "proj_A1") |>
pull(uid) |>
first()
uid
## b9agvd9AXQCmo5qyUOBEl
asset <- kobo_asset(uid)
asset
## <robotoolbox asset> b9agvd9AXQCmo5qyUOBEl
## Asset Name: proj_A1
## Asset Type: survey
## Created: 2021-05-10 07:47:53
## Last modified: 2021-08-16 12:35:50
## Submissions: 941
```
Now with the selected `asset`, we can extract the `submissions` using the `kobo_submissions` function. The `kobo_data` can also be used, it's an alias of `kobo_submissions`.
```{r}
df <- kobo_submissions(asset) ## or df <- kobo_data(asset)
glimpse(df)
## Rows: 941
## Columns: 17
## $ id <int> …
## $ start <dttm> …
## $ end <dttm> …
## $ today <date> …
## $ deviceid <chr> …
## $ test <chr+lbl> …
## $ round <date> …
## $ effective_date <date> …
## $ collect_type <chr+lbl> …
## $ covid_module <chr+lbl> …
## $ country <chr+lbl> …
## $ interviewer_id <chr> …
## $ respondent_is_major <chr+lbl> …
## $ consent <chr+lbl> …
## $ admin_level_1 <chr+lbl> …
## $ admin_level_2 <chr+lbl> …
## $ admin_level_3 <chr+lbl> …
```
### Multi-Languages Survey forms
`robotoolbox` uses the R package [`labelled`](https://larmarange.github.io/labelled/) to provide tools to manipulate variable labels and value labels. You can learn more about this here. You can learn more about this [here](https://dickoa.gitlab.io/robotoolbox/articles/multilang-forms.html)
### Repeating groups
Repeating groups associate multiple records to a single record in the `main` table. It's used to group questions that need to be answered repeatedly.
The package [`dm`](https://dm.cynkra.com) is used to model such relationship and allow you to safely query and join such linked data for your analysis. Learn more about it [here](https://dickoa.gitlab.io/robotoolbox/articles/repeat-group-data.html)
### Spatial data
`KoboToolbox` provides three types of question to record spatial data: `geopoint` for points, `geotrace` for lines and `geoshape` to map close polygons. `robotoolbox` associates to each spatial column a [`WKT`](https://libgeos.org/specifications/wkt/) column. It provides a simple way to use it with various GIS software and `R` package for spatial data analysis. The `sf` package is the standard for spatial vector data handling and visualization. Learn more about it [here](https://dickoa.gitlab.io/robotoolbox/articles/spatial-data.html)
### Audit logging data
`KoboToolbox` comes with a feature that records all activities related to a form submission in a log file. The audit logging metadata is useful for data quality control, security and workflow management. The `kobo_audit` function allow you to read `KoboToolbox` audit logs file. Learn more in the following vignette: [Audit Data](https://dickoa.gitlab.io/robotoolbox/articles/audit-data.html)
### I'm collecting data using `ODK`
[OpenDataKit (`ODK`)](https://getodk.org/) is an open-source tool for collecting data. Similar to `KoboToolbox`, `ODK` utilizes the [XLSForm standard](https://xlsform.org/en/) for form creation. Both tools offer similar features and functionality, and data collected using `KoboToolbox` can be collected using [`ODK Collect`](https://docs.getodk.org/collect-intro/) as well.
If you are using `ODK` in conjunction with R, the `ruODK` package is an excellent resource. The [ruODK R package](https://docs.ropensci.org/ruODK/index.html) served as the primary inspiration for `robotoolbox` and provides similar functionality for interacting with ODK data.
## Meta
* Please [report any issues or bugs](https://gitlab.com/dickoa/robotoolbox/-/issues).
* License: MIT
* Please note that this project is released with a [Contributor Code of Conduct](https://dickoa.gitlab.io/robotoolbox/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.