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

library(robotoolbox)
library(dplyr)
asset_list <- kobo_asset_list()

asset_list |>
  slice_head(n = 6) |>
  knitr::kable()

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

asset_list |>
  filter(name == "Multiple languages") |>
  pull(uid)

#> [1] "aYuTZn9vegi3Z49MXwKjep"

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

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()

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()

Which is a representation in robotoolbox of the following form

• Survey questions

• Choices

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.