robotoolbox is an R client to access and manage data from
KoboToolbox, a powerful tool for
collecting and analyzing data in challenging environments.
- Easy authentication with KoboToolbox API
- List and access KoboToolbox assets
- Retrieve and process survey submissions
- Handle multi-language survey forms
- Work with repeating groups in survey data
- Process spatial data from KoboToolbox
- Access and analyze audit logging data
- Download media attachments
The package is available on CRAN, Gitlab (dev) and Github (mirror).
install.packages("robotoolbox")you will need the remotes package
to install it from Gitlab and Github. You can also use the
pak package to install it from Github.
## From Gitlab
remotes::install_gitlab("dickoa/robotoolbox")
## From Github
pak::pkg_install("dickoa/robotoolbox")The robotoolbox package is a client to
KoboToolbox API v2. You
will need to set your API token and specify the KoboToolbox server
URL. The easiest way to set up robotoolbox is to store the token and
the URL in your .Renviron file, which is automatically read by R on
startup.
You can retrieve your API token by following the instruction in the
official API documentation: https://support.kobotoolbox.org/api.html.
You can also get your token directly from R using the kobo_token
function.
The following examples will utilize UNHCR KoboToolbox server url
(https://kobo.unhcr.org/). You can replace this URL with
https://kf.kobotoolbox.org/, https://kobo.humanitarianresponse.info/
or any other KoboToolbox server URL you typically use.
kobo_token(username = "xxxxxxxxx",
password = "xxxxxxxxx",
url = "https://kobo.unhcr.org")You can either edit directly the .Renviron file or access it by
calling usethis::edit_r_environ() (assuming you have the usethis
package installed) and entering the following two lines:
KOBOTOOLBOX_URL="https://kobo.unhcr.org/"
KOBOTOOLBOX_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxOr use directly the kobo_setup function
kobo_setup(url = "https://kobo.unhcr.org",
token = "xxxxxxxxxxxxxxxxxxxxxxxxxx")You can check the settings using the kobo_settings function.
library("robotoolbox")
kobo_settings()
## <robotoolbox settings>
## KoboToolbox URL: https://kobo.unhcr.org/
## KoboToolbox API Token: xxxxxxxxxxxxxxxxxxxxxxxxxxWith the settings done, it is possible to list all assets (e.g
surveys, questions, etc) for the account associated to the token and
URL.
library("dplyr")
l <- kobo_asset_list()
l
# A tibble: 24 x 7
uid name asset_type owner_username date_created
<chr> <chr> <chr> <chr> <dttm>
1 b9kgvd… Proj_A1… survey xxxxxxxxxxxxx… 2020-04-27 20:34:23
2 aRFJMp… Proj_A2… survey xxxxxxxxxxxxx… 2020-04-27 21:21:12
3 a6qMG7… Proj_A3… survey xxxxxxxxxxxxx… 2021-05-25 16:59:08
4 azhrVs… Proj_A4… survey xxxxxxxxxxxxx… 2021-05-25 13:59:46
5 aReR58… Proj_A5… survey xxxxxxxxxxxxx… 2021-06-07 09:15:53
6 aWaoqy… Proj_A6… survey xxxxxxxxxxxxx… 2021-05-29 10:46:09
7 aABU3C… Proj_A7… survey xxxxxxxxxxxxx… 2020-11-28 15:00:10
8 aaznyX… Proj_A9… survey xxxxxxxxxxxxx… 2020-11-28 14:28:48
9 aCVr2Q… Proj_A9… survey xxxxxxxxxxxxx… 2021-05-25 13:30:24
10 aPxNao… Proj_A10… survey xxxxxxxxxxxxx… 2020-04-27 11:37:34
# … with 14 more rows, and 3 more variables:
# date_modified <dttm>, submissions <int>
glimpse(l)
$ uid <chr> "b9kgvd7AXQCmo5qyUOBEl", "aRfJMpTSGRLzZ…"
$ name <chr> "Proj_A1", "Proj_A2", "Proj_A3", "Proj_A…"
$ asset_type <chr> "survey", "survey", "survey", "survey", …
$ owner_username <chr> "xxxxxxxxxxxxxx", "xxxxxxxxxxxxxxx", "xx…"
$ date_created <dttm> 2020-04-27 20:34:23, 2020-04-27 21:21:1…
$ date_modified <dttm> 2021-06-17 01:52:57, 2021-06-17 01:52:5…
$ submissions <int> 2951, 2679, 2, 1, 0, 0, 287, 73, 0, 274,…The list of assets is a tibble, you can filter it to select the form
unique identifier uid that uniquely identify the API asset you want to
open. The function kobo_asset can then be used to get the asset from
the uid.
uid <- l |>
filter(name == "proj_A1") |>
pull(uid) |>
first()
uid
## b9agvd9AXQCmo5qyUOBEl
asset <- kobo_asset(uid)
asset
## <robotoolbox asset> b9agvd9AXQCmo5qyUOBEl
## Asset Name: proj_A1
## Asset Type: survey
## Created: 2021-05-10 07:47:53
## Last modified: 2021-08-16 12:35:50
## Submissions: 941Now with the selected asset, we can extract the submissions using
the kobo_submissions function. The kobo_data can also be used, it’s
an alias of kobo_submissions.
df <- kobo_submissions(asset) ## or df <- kobo_data(asset)
glimpse(df)
## Rows: 941
## Columns: 17
## $ id <int> …
## $ start <dttm> …
## $ end <dttm> …
## $ today <date> …
## $ deviceid <chr> …
## $ test <chr+lbl> …
## $ round <date> …
## $ effective_date <date> …
## $ collect_type <chr+lbl> …
## $ covid_module <chr+lbl> …
## $ country <chr+lbl> …
## $ interviewer_id <chr> …
## $ respondent_is_major <chr+lbl> …
## $ consent <chr+lbl> …
## $ admin_level_1 <chr+lbl> …
## $ admin_level_2 <chr+lbl> …
## $ admin_level_3 <chr+lbl> …robotoolbox uses the R package
labelled to provide tools to
manipulate variable labels and value labels. You can learn more about
this here. You can learn more about this
here
Repeating groups associate multiple records to a single record in the
main table. It’s used to group questions that need to be answered
repeatedly. The package dm is used to model
such relationship and allow you to safely query and join such linked
data for your analysis. Learn more about it
here
KoboToolbox provides three types of question to record spatial data:
geopoint for points, geotrace for lines and geoshape to map close
polygons. robotoolbox associates to each spatial column a
WKT column. It provides a
simple way to use it with various GIS software and R package for
spatial data analysis. The sf package is the standard for spatial
vector data handling and visualization. Learn more about it
here
KoboToolbox comes with a feature that records all activities related
to a form submission in a log file. The audit logging metadata is useful
for data quality control, security and workflow management. The
kobo_audit function allow you to read KoboToolbox audit logs file.
Learn more in the following vignette: Audit
Data
OpenDataKit (ODK) is an open-source tool for
collecting data. Similar to KoboToolbox, ODK utilizes the XLSForm
standard for form creation. Both tools offer
similar features and functionality, and data collected using
KoboToolbox can be collected using
ODK Collect as well.
If you are using ODK in conjunction with R, the ruODK package is an
excellent resource. The ruODK R
package served as the
primary inspiration for robotoolbox and provides similar functionality
for interacting with ODK data.
- Please report any issues or bugs.
- License: MIT
- Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.