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
.
#> [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
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
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.