robotoolbox: an R client for Kobotoolbox • robotoolbox

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.