Get all submissions from a KoboToolbox API asset

Get all submissions from a KoboToolbox API asset through a kobo_asset or asset unique identifier.

Usage

kobo_data(
  x,
  lang,
  all_versions,
  colnames_label,
  select_multiple_label,
  select_multiple_sep,
  progress,
  paginate,
  page_size,
  query,
  fields
)

kobo_submissions(
  x,
  lang,
  all_versions,
  colnames_label,
  select_multiple_label,
  select_multiple_sep,
  progress,
  paginate,
  page_size,
  query,
  fields
)

# S3 method for class 'kobo_asset'
kobo_submissions(
  x,
  lang = NULL,
  all_versions = TRUE,
  colnames_label = FALSE,
  select_multiple_label = FALSE,
  select_multiple_sep = "_",
  progress = FALSE,
  paginate = NULL,
  page_size = NULL,
  query = NULL,
  fields = NULL
)

# S3 method for class 'character'
kobo_submissions(
  x,
  lang = NULL,
  all_versions = TRUE,
  colnames_label = FALSE,
  select_multiple_label = FALSE,
  select_multiple_sep = "_",
  progress = FALSE,
  paginate = NULL,
  page_size = NULL,
  query = NULL,
  fields = NULL
)

# Default S3 method
kobo_submissions(
  x,
  lang = NULL,
  all_versions = TRUE,
  colnames_label = FALSE,
  select_multiple_label = FALSE,
  select_multiple_sep = "_",
  progress = FALSE,
  paginate = NULL,
  page_size = NULL,
  query = NULL,
  fields = NULL
)

Arguments

x

the asset uid or the kobo_asset object.

lang

character, form language used for the variable and value labels.

all_versions

logical, whether to use the forms of older versions too. The deployed form always gives the labels. With TRUE, the forms of the older versions found in the submissions add the questions the deployed form lacks, with their labels and repeat groups. With FALSE, only the deployed form is used, which is faster on forms with many versions. Questions it lacks then get their name as label. Rows of a repeat group it lacks, or recorded under a parent the repeat group no longer has, are dropped. Both return every submission, and keep the values of a question moved to another group. To keep the submissions of one version, use query, for example '{"__version__": "vZpLmSfX3dfu6gTXtGPcS8"}'. Default to TRUE.

colnames_label

logical, whether or not to use variable labels in lieu of column names based on form question names. Each column keeps its question name in the kobo_name attribute. Default to FALSE.

select_multiple_label

logical, whether or not to replace select_multiple columns values by labels. The labels of an answer are separated by spaces, and kobo_lang_set() translates them. Default to FALSE.

select_multiple_sep

character, column and choices separator for newly created dummy variables. Default to "_".

progress

logical, whether or not you want to see the progess via message. Default to FALSE.

paginate

logical, split submissions by page_size. Default to NULL.

page_size

integer, number of submissions per request. Default to the value set with kobo_setup(page_size = ), 1000 unless changed. Servers may return fewer submissions per request than asked. kobo_data() detects this limit and requests the missing submissions, so no submission is lost when page_size exceeds it.

query

character, a MongoDB-style query string to filter submissions server-side. For example, '{"field_name": "value"}' to return only submissions where field_name equals "value". The query filters submissions (main table rows) based on top-level fields only. You cannot filter on fields inside a repeat group. All repeat group rows belonging to matching submissions are returned. Default to NULL (no filtering).

fields

character vector of field names to return. When provided, only these fields (plus __version__) are fetched from the server. The server may still include system fields such as _id and _uuid.

For repeat-group forms, fields supports individual selection of main-table columns and table-level selection of top-level repeat groups. A selected repeat group is always returned in full. Selecting individual child columns within a repeat group (for example, "my_repeat/age") is not supported. Nested repeat groups cannot be selected independently, you'll need to include their ancestor repeat group instead.

Repeat-group forms always return a dm object. If no repeat group is selected, the returned dm contains only the main table. Default to NULL (all fields).

Value

A data.frame or A dm object if you have a repeating group of questions. It contains the responses from the Kobotoolbox survey. The dm has a main table and one table for each repeat group, in form order, linked to its parent table. A repeat group without data gives a table with zero rows. _parent_table_name gives the parent table of each row. A repeat group that has another parent in an older form version holds the rows under each parent. Its _parent_index then points to the parent in the deployed form, and a _parent_index_<parent> column points to each other parent.

Details

kobo_data is the main function of robotoolbox, it is used pull submissions from your Kobotoolbox survey. The main result is a data.frame for regular form and you have a dm for a form with repeating groups of questions.

Examples

if (FALSE) { # \dontrun{
# Use your own URL and token
kobo_setup(url = "https://kf.kobotoolbox.org/",
           token = "9et1814c285w094f6v9bd629df47a1a0e81x53a0")
# Use your own unique identifier
uid <- "a9cwEQcbWqWzA5hzkjRUWi"
asset <- kobo_asset(uid)
subs <- kobo_data(asset)

# Filter submissions server-side with a MongoDB query
filtered <- kobo_data(asset, query = '{"pet_yesno": "1"}')

# Select specific fields
partial <- kobo_data(asset, fields = c("full_name", "pet_yesno"))

if (require(dplyr)) {
 library(dplyr)
 glimpse(subs)
 }
} # }