robotoolbox is an R client for retrieving data from KoboToolbox.
robotoolbox uses KoboToolbox API v2
with the primary aim of simplifying the process of accessing your
collected data.
Configure robotoolbox
In order to use robotoolbox, you need to configure and
specify your API token and your
KoboToolbox server URL. An API token is a
unique identifier that acts like a combination of username and password.
It allows the user to authenticate to KoboToolbox API to
access your data. The simplest way to configure robotoolbox
is to store your API token and server URL in your .Renviron
file.
We use the environment variables KOBOTOOLBOX_URL and
KOBOTOOLBOX_TOKEN for the URL and the token, respectively.
You can use the usethis package and the
usethis::edit_r_environ() function to add these environment
variables to your .Renviron file.
The following examples will utilize UNHCR KoboToolbox
server url (https://kobo.unhcr.org/). You can replace this URL by
the one you use, it can be https://kf.kobotoolbox.org/, https://kobo.humanitarianresponse.info/ or any other
KoboToolbox server URL you typically use.
In an interactive session, you can directly use the
kobo_setup function.
library(robotoolbox)
kobo_setup(url = "https://kobo.unhcr.org",
token = "xxxxxxxxxxxxxxxxxxxxxxxxxx")You can manually retrieve your token through the
KoboToolbox account settings in the web interface. There is
also a kobo_token function to do the same thing
automagically from R.
token <- kobo_token(username = "cool_user_name",
password = "gRe@TP@$$WoRd",
overwrite = TRUE)You can then use this token in your .Renviron or during
the setup using kobo_setup.
kobo_setup(url = "https://kobo.unhcr.org",
token = token)You can verify the settings using the kobo_settings
function.
kobo_settings()
## <robotoolbox settings>
## KoboToolbox URL: https://kobo.unhcr.org/
## KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxxKoboToolbox API assets
List your projects
You can view and list all your KoboToolbox projects
(also known as assets) through the web interface.
With robotoolbox, you can achieve a similar outcome in
R using kobo_asset_list function.
#> Error in get(paste0(generic, ".", class), envir = get_method_env()) :
#> object 'type_sum.accel' not found
library(robotoolbox)
library(dplyr)
asset_list <- kobo_asset_list()
asset_list |>
slice_head(n = 6) |>
knitr::kable()| uid | name | asset_type | owner_username | date_created | date_modified | submissions |
|---|---|---|---|---|---|---|
| anCXJBQttAghX8oFeNvgSW | PCS Survey | survey | dickoa | 2022-02-20 14:51:36 | 2022-02-20 14:51:47 | 1 |
| aEwTYNcU76UvLgiY89rPWm | Pan-African Capacity Building in R | survey | rrc_rrrp19 | 2022-01-06 14:33:35 | 2022-01-28 12:31:28 | 95 |
| aWGgYSXbJn3nnqr2qxTxSB | External file v3 | survey | dickoa | 2022-01-26 11:38:45 | 2022-01-26 11:39:41 | 1 |
| aREsLnfwNU9L7ePbUjnajg | Multiple languages 2 | survey | dickoa | 2022-01-18 20:31:47 | 2022-01-18 20:37:10 | 3 |
| aYuTZn9vegi3Z49MXwKjep | Multiple languages | survey | dickoa | 2022-01-07 10:37:18 | 2022-01-07 10:37:35 | 5 |
| aiNdJzr9RzG8V57exPZbsS | empty | dickoa | 2022-01-07 10:36:28 | 2022-01-07 10:36:28 | 0 |
KoboToolbox asset
You can also manipulate directly each asset (project)
using the kobo_asset function. On the server, an asset is
uniquely identified by a uid.
uid <- "aYuTZn9vegi3Z49MXwKjep"
asset <- kobo_asset(uid)
asset#> <robotoolbox asset> aYuTZn9vegi3Z49MXwKjep
#> Asset name: Multiple languages
#> Asset type: survey
#> Asset owner: dickoa
#> Created: 2022-01-07 10:37:19
#> Last modified: 2023-09-07 07:27:34
#> Submissions: 5As asset_list is a data.frame containing
the list of assets, we can subset it and select the uid of
interest based on the available metadata.
As an example, you can get the uid associated to the
asset (survey) named Multiple languages.
#> [1] "aYuTZn9vegi3Z49MXwKjep"You can then retrieve the associated asset object using
the kobo_asset function.
asset_list |>
filter(name == "Multiple languages") |>
pull(uid) |>
kobo_asset()#> <robotoolbox asset> aYuTZn9vegi3Z49MXwKjep
#> Asset name: Multiple languages
#> Asset type: survey
#> Asset owner: dickoa
#> Created: 2022-01-07 10:37:19
#> Last modified: 2023-09-07 07:27:34
#> Submissions: 5A kobo_asset provides basic information about your
project. You can easily get the name, its type (survey), the number of
submissions, when the project was created, and when it was last
modified.
KoboToolbox data
The kobo_data function (or its alias
kobo_submissions) is the main function in
robotoolbox, and it fetches your data from the server, as
its name suggests.
We can illustrate its usage by trying to read data from the same
survey named Multiple languages.
We can follow the steps mentioned above to get the uid,
and the asset.
asset_ml <- asset_list |>
filter(name == "Multiple languages") |>
pull(uid) |>
kobo_asset()
asset_ml#> <robotoolbox asset> aYuTZn9vegi3Z49MXwKjep
#> Asset name: Multiple languages
#> Asset type: survey
#> Asset owner: dickoa
#> Created: 2022-01-07 10:37:19
#> Last modified: 2023-09-07 07:27:34
#> Submissions: 5Then, we can use the asset_ml object, which uniquely
identifies the Multiple languages asset, to read its
data
data_ml <- kobo_data(asset_ml)
data_ml |>
select(start:uuid) |>
slice_head(n = 3) |>
knitr::kable()| start | end | today | full_name | pet_yesno | _id | uuid |
|---|---|---|---|---|---|---|
| 2022-01-07 10:39:37 | 2022-01-07 10:39:47 | 2022-01-07 | Jean-Pierre | 0 | 17735002 | 5388c680d19148828ea45913af820f30 |
| 2022-01-07 10:39:47 | 2022-01-07 10:40:02 | 2022-01-07 | Fatim | 1 | 17735003 | 5388c680d19148828ea45913af820f30 |
| 2022-01-07 10:37:39 | 2022-01-07 10:38:20 | 2022-01-07 | Ahmad | 0 | 17734994 | 5388c680d19148828ea45913af820f30 |
KoboToolbox form
robotoolbox allows you to display and manipulate
KoboToolbox survey forms. You can pull the form from a
particular survey using the kobo_form function
| name | list_name | type | label | lang | kuid | version | choices |
|---|---|---|---|---|---|---|---|
| start | NA | start | NA | English (en) | Cypi2O0NQ | vW6fMPTWKJmBfdSRM7jd4V | |
| end | NA | end | NA | English (en) | F2Erecceg | vW6fMPTWKJmBfdSRM7jd4V | |
| today | NA | today | NA | English (en) | 6WnNQUnlF | vW6fMPTWKJmBfdSRM7jd4V | |
| full_name | NA | text | What is your name? | English (en) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V | |
| full_name | NA | text | Quel est votre nom ? | Francais (fr) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V | |
| full_name | NA | text | ما اسمك ؟ | Arabic (ar) | pkEk0bzX7 | vW6fMPTWKJmBfdSRM7jd4V | |
| pet_yesno | yesno | select_one | Do you have any pet? | English (en) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar) |
| pet_yesno | yesno | select_one | Avez-vous un animal de compagnie ? | Francais (fr) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar) |
| pet_yesno | yesno | select_one | هل تمتلك حيوانا أليفا ؟ | Arabic (ar) | a1xXud0rG | vW6fMPTWKJmBfdSRM7jd4V | 1 , 1 , 1 , 0 , 0 , 0 , Yes , Oui , نعم , No , Non , لا , English (en) , Francais (fr), Arabic (ar) , English (en) , Francais (fr), Arabic (ar) |
Which is a representation in robotoolbox of the
following form
- Survey questions
| type | name | label::English (en) | label::Francais (fr) | label::Arabic (ar) |
|---|---|---|---|---|
| start | start | |||
| end | end | |||
| today | today | |||
| text | full_name | What is your name? | Quel est votre nom ? | ما اسمك ؟ |
| select_one yesno | pet_yesno | Do you have any pet? | Avez-vous un animal de compagnie ? | هل تمتلك حيوانا أليفا ؟ |
- Choices
| list_name | name | label::English (en) | label::Francais (fr) | label::Arabic (ar) |
|---|---|---|---|---|
| yesno | 1 | Yes | Oui | نعم |
| yesno | 0 | No | Non | لا |
Wrapping up
robotoolbox is a powerful R client for interfacing with
the KoboToolbox. Its primary purpose is to simplify and
streamline the process of accessing and managing data collected through
KoboToolbox. With the use of functions like
kobo_setup, kobo_asset, and
kobo_data, users can effortlessly configure their settings,
manipulate their projects (or assets), and load their data
directly from the server. It also comes with utilities to manipulate
audit log data for automatic survey data quality control
(kobo_audit) or to download media attachments
(kobo_attachment_download).
Overall, robotoolbox serves as an essential tool for
researchers and data analysts who rely on KoboToolbox for
data collection and seek an efficient way to integrate their work with
the R environment.