Skip to contents

robotoolbox

robotoolbox is an R client to access data from the KoboToolbox.

robotoolbox is built around KoboToolbox API v2 and its main goal is to ease the process by which you access your collected data.

You will need to set your API token and specify your KoboToolbox server URL. An API token is a unique identifier, just like a password. It allows the user to authenticate to Kobotoolbox APIs to access your data. The easiest way to set up robotoolbox is to store the API token and the server url in your .Renviron.

We are using the following environment variables KOBOTOOLBOX_URL and KOBOTOOLBOX_TOKEN for the url and the token. You can use the usethis package and the usethis::edit_r_environ() to add the following variables to your .Renviron file.

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

In an interactive session, you can use directly the kobo_setup function.

library(robotoolbox)
kobo_setup(url = "https://kobo.unhcr.org",
           token = "xxxxxxxxxxxxxxxxxxxxxxxxxx")

You can get your token manually through the Kobotoolbox web interface in your account settings. 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)

This token can then be used in the setup through kobo_setup or in your .Renviron.

kobo_setup(url = "https://kobo.unhcr.org",
           token = token)

Settings can be checked using kobo_settings function.

kobo_settings()
## <robotoolbox settings>
##    KoboToolbox URL: https://kobo.unhcr.org/
##    KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxx

Kobotoolbox projects

List your projects

All your Kobotoolbox projects also named asset can be checked and listed through the web interface.

Using robotoolbox, you can do something similar from R with the 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 kobo_asset. In 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:18
#>   Last modified: 2022-01-07 10:37:35
#>   Submissions: 5

Since asset_list, the list of assets, is a data.frame, 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 onamed Multiple languages.

asset_list |>
  filter(name == "Multiple languages") |>
  pull(uid)
#> [1] "aYuTZn9vegi3Z49MXwKjep"

And it’s then possible to get 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:18
#>   Last modified: 2022-01-07 10:37:35
#>   Submissions: 5

A kobo_asset give you some 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 main function on the robotoolbox package is kobo_data (or kobo_submissions its alias), and as the name suggests, it loads your data from the server.

We can illustrate its usage by trying to read data from the same project named Multiple languages.

We can follow the steps 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:18
#>   Last modified: 2022-01-07 10:37:35
#>   Submissions: 5

We can then 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-07T10:39:47.240-00:00 2022-01-07T10:40:02.122-00:00 2022-01-07 Fatim 1 17735003 5388c680d19148828ea45913af820f30
2022-01-07T10:39:37.049-00:00 2022-01-07T10:39:47.223-00:00 2022-01-07 Jean-Pierre 0 17735002 5388c680d19148828ea45913af820f30
2022-01-07T10:38:29.868-00:00 2022-01-07T10:39:37.029-00:00 2022-01-07 إبراهيم 1 17735000 5388c680d19148828ea45913af820f30

Kobotoolbox form

robotoolbox allows you to represent 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 choices
start NA start NA English (en) Cypi2O0NQ
end NA end NA English (en) F2Erecceg
today NA today NA English (en) 6WnNQUnlF
full_name NA text What is your name? English (en) pkEk0bzX7
full_name NA text Quel est votre nom ? Francais (fr) pkEk0bzX7
full_name NA text ما اسمك ؟ Arabic (ar) pkEk0bzX7
pet_yesno yesno select_one Do you have any pet? English (en) a1xXud0rG 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 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 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 لا