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 or not to include submissions from all form versions. Default to TRUE. If FALSE, it uses the data from the latest version of the form.

colnames_label

logical, whether or not to use variable labels in lieu of column names based on form question names. Default to FALSE.

select_multiple_label

logical, whether or not to replace select_multiple columns values by labels. 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 page.

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.

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)
 }
} # }