A quick introduction to robotoolbox

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.

KOBOTOOLBOX_URL="https://kobo.unhcr.org/"
KOBOTOOLBOX_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxx

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: xxxxxxxxxxxxxxxxxxxxxxxxxx

KoboToolbox 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.

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: 5

As 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.

asset_list |>
  filter(name == "Multiple languages") |>
  pull(uid)
#> [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: 5

A 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: 5

Then, 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

asset_ml |>
  kobo_form() |>
  knitr::kable()
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) , vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V
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) , vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V
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) , vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V, vW6fMPTWKJmBfdSRM7jd4V

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.