Skip to contents

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.

In order to use robotoolbox, you need to configure API token and specify your KoboToolbox server URL. An API token is a unique identifier, just like a username and a password. It allows the user to authenticate to Kobotoolbox API to access your data. The simplest way to configure robotoolbox is to store the API token and the server url in your .Renviron.

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() to add the following variables to your .Renviron file.

The following examples will utilize UNHCR Kobotoolbox server url (https://kobo.unhcr.org). You can replace this URL by 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 projects

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: 2022-01-07 10:37:36
#>   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 project 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: 2022-01-07 10:37:36
#>   Submissions: 5

A kobo_asset provides basic information about your project. You can easily get the name, 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 the 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 project named Multiple languages.

We can follow the steps mentioned above to get 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: 2022-01-07 10:37:36
#>   Submissions: 5

Then, we can use the asset_ml object, which uniquely identify 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:47 2022-01-07 10:40:02 2022-01-07 Fatim 1 17735003 5388c680d19148828ea45913af820f30
2022-01-07 10:39:37 2022-01-07 10:39:47 2022-01-07 Jean-Pierre 0 17735002 5388c680d19148828ea45913af820f30
2022-01-07 10:38:29 2022-01-07 10:39:37 2022-01-07 إبراهيم 1 17735000 5388c680d19148828ea45913af820f30

Kobotoolbox form

robotoolbox allows you to display and manipulate Kobotoolbox forms. You can pull the form from a particular project 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

The robotoolbox is a powerful R client specifically designed 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 provides capabilities to handle and manipulate Kobotoolbox forms directly from R. 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.