In dickoa/robotoolbox: Client for the 'KoboToolbox' API

knitr::opts_chunk$set(
  collapse = TRUE,
  message = FALSE,
  warning = FALSE,
  echo = TRUE,
  comment = "#>")

During data collection, it is often necessary to translate survey forms into multiple languages. KoboToolbox forms allow users to easily add translations, which can be used to label questions and choice values in either single or multiple-choice questions.

robotoolbox provides the capability to access these labels used in the form. The labelled package is used to encode variable labels for question labels and value labels for choice labels.

The following example showcases a project in KoboToolbox that employs three languages: English, French, and Arabic.

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 | لا |

Loading the survey

To load this survey from your KoboToolbox server into your R session, you can use its unique identifier (uid = aYuTZn9vegi3Z49MXwKjep) with the kobo_asset function.

library(robotoolbox)
library(dplyr)
uid <- "aYuTZn9vegi3Z49MXwKjep"
asset <- kobo_asset(uid)
asset

library(robotoolbox)
library(dplyr)
asset <- asset_ml
asset

Listing available languages

The kobo_lang function can be used to list all available languages for this survey.

kobo_lang(asset)

Reading data in each language

The kobo_data function allows you to specify the language to be loaded using the lang parameter. You can check the spelling of each language using kobo_lang.

df_en <- kobo_data(asset, lang = "English (en)")
df_fr <- kobo_data(asset, lang = "Francais (fr)")
df_ar <- kobo_data(asset, lang = "Arabic (ar)")
glimpse(df_en)

df_en <- data_ml_en
df_fr <- data_ml_fr
df_ar <- data_ml_ar
glimpse(df_en)

If the lang parameter is not specified, the default language is used. In this project, the default language is English (en).

df_default <- kobo_data(asset)
all.equal(df_default, df_en)

df_default <- data_ml_default
all.equal(df_default, df_en)

Accessing variable labels

You can use the var_label function from the labelled package to access question labels.

library(labelled)
var_label(df_en$full_name)
var_label(df_fr$full_name)
var_label(df_ar$full_name)

var_label(df_en$pet_yesno)
var_label(df_fr$pet_yesno)
var_label(df_ar$pet_yesno)

Variable labels as column names

The kobo_data function has an additional parameter colnames_label (default is FALSE) that allows you to use the variable labels as column names. While this is not recommended for data analysis, it can be useful when exporting your data.frame to a spreadsheet. This feature is already available in the traditional KoboToolbox export tools.

kobo_data(asset_ml,
          colnames_label = TRUE, lang = "Arabic (ar)") |>
names()

names(data_ml_vlabel)

Accessing labels from `select_one` question type

The to_factor function can convert the values of single-choice questions into labels.

table(to_factor(df_en$pet_yesno))
table(to_factor(df_fr$pet_yesno))
table(to_factor(df_ar$pet_yesno))

If you prefer character values over factors, you can use to_character to have the labels in character format instead of factors.

count(df_ar, pet_yesno_ar = to_character(pet_yesno))

Accessing labels for `select_multiple` question type

Labels from select_multiple is also accessible using the kobo_data parameter select_multiple_label. Let's demonstrate this feature with the following form:

Survey questions

| type | name | label::English (en) | |---------------------|-----------|-----------------------------| | start | start | | | end | end | | | today | today | | | text | full_name | What is your name? | | select_multiple pet | pet_type | What type of pet do you own |

Choices

| list_name | name | label::English (en) | |-----------|------|---------------------| | pet | 1 | rabbit | | pet | 2 | chicken | | pet | 3 | dog | | pet | 4 | cat | | pet | 5 | turtle |

data_sm <- kobo_data(uid)
glimpse(data_sm)

library(dplyr)
library(robotoolbox)
glimpse(data_sm)

The column pet_type contains values (1 to 5) instead of the labels (dog, cat, etc.). Now, let's set the new select_multiple_label to TRUE and read again the data.

data_sm_label <- kobo_data(uid,
                           select_multiple_label = TRUE)
glimpse(data_sm_label)

glimpse(data_sm_label)

We can now see the labels (dog, cat, etc.) instead of the values (1 to 5) for the pet_type question.

Variable labels have been improved for all the dummy variables related to the select_multiple question (whether or not you use the select_multiple_label parameter).