Package 'RColetum'

RColetum

Description

An R package to get data from Coletum.

RColetum functions

The currents functions that are provide by RColetum are:

• GetForms: get the information about all forms.

• GetForm: get the metadata and field structure of a form.

• GetAnswers: get the all the answers of a form or personalize with filters and take just what you need.

• FlattenAnswers: flatten a GetAnswers result into a single data frame.

Author(s)

Maintainer: André Smaniotto [email protected]

Authors:

• Marcelo Magnani [email protected]

• Rodrigo Sant'Ana [email protected]

Other contributors:

• GeoSapiens [copyright holder, funder]

See Also

Useful links:

• https://github.com/geo-sapiens/RColetum

• Report bugs at https://github.com/geo-sapiens/RColetum/issues

---

Flatten a GetAnswers result into a single data frame.

Description

Converts the output of GetAnswers into a single flat data.frame. Works with any form: if the form is simple (no groups or multivalued fields), GetAnswers already returns a plain data.frame and this function returns it unchanged. For forms with groups or multivalued fields, the main data frame and all nested data frames are joined using dplyr::full_join.

Usage

FlattenAnswers(answers)

Arguments

answers

The return value of GetAnswers: either a plain data.frame (simple form) or a list with a main data frame and nested data frames (form with groups or multivalued fields).

Details

When the form contains multivalued groups or fields, each submission may produce multiple rows in the nested data frames. Joining them to the main data frame causes row duplication: each combination of main row and nested row is represented. Account for this in any aggregation.

Value

A single data.frame. For simple forms the columns keep their original names. For forms with groups, main-frame columns are prefixed with "answer." and nested-frame columns are prefixed with their group componentId.

Examples

answers <- GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5719)
FlattenAnswers(answers)

# Pipe-friendly
GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5719) |> FlattenAnswers()

---

Get all the answers of a form.

Description

Get all the current answers of a specific form. This function calls GetForm internally to understand the form structure.

Usage

GetAnswers(
  token,
  idForm,
  nameForm = NULL,
  source = NULL,
  createdAfter = NULL,
  createdBefore = NULL,
  updatedAfter = NULL,
  updatedBefore = NULL,
  createdBy = NULL,
  updatedBy = NULL,
  page = 1,
  page_size = 100,
  all_pages = TRUE
)

Arguments

token	String access token.
idForm	Numeric Id of the required form.
nameForm	String name of the required form. Used only when idForm is not supplied. When this parameter is used, one extra access quota is spent.
source	Optional filter. Origin of the answer: "web_public", "web_private" or "mobile".
createdAfter	Optional filter. Returns answers created after this date (exclusive). Accepts ISO 8601 format ("YYYY-MM-DD" or "YYYY-MM-DDThh:mm:ssTZD").
createdBefore	Optional filter. Returns answers created before this date (exclusive). Accepts ISO 8601 format.
updatedAfter	Optional filter. Returns answers updated after this date (exclusive). Accepts ISO 8601 format.
updatedBefore	Optional filter. Returns answers updated before this date (exclusive). Accepts ISO 8601 format.
createdBy	Optional filter. Returns answers created by the user with this numeric ID.
updatedBy	Optional filter. Returns answers whose last update was made by the user with this numeric ID.
page	Integer. Starting page when all_pages = FALSE. Default: 1.
page_size	Integer. Number of records per API request (max 500). Default: 100.
all_pages	Logical. If TRUE (default), fetches all pages automatically and returns a combined result. If FALSE, returns only the page specified by page.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A list with two elements when the form has groups or multivalued fields: the first element is the main data frame (scalar fields and metadata), the second is a named list of nested data frames linked by main_df_id. For simple forms with no groups or multivalued fields, a single data.frame is returned directly. Use FlattenAnswers to join everything into one flat table.

Metadata columns in the main data frame: main_df_id, created_by_user_name, created_by_user_id, created_at_source, created_at, created_at_coordinates.latitude, created_at_coordinates.longitude, updated_at, updated_at_coordinates.latitude, updated_at_coordinates.longitude.

Examples

GetAnswers("cizio7xeohwgc8k4g4koo008kkoocwg", 5705)
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             nameForm = "RColetum Test - Iris")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             createdAfter = "2012-12-20",
             createdBefore = "2018-12-20")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             source = "web_public",
             createdAfter = "2012-12-20T19:20:30+01:00",
             createdBefore = "2018-12-20T19:20:30+01:00")
GetAnswers(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
             idForm = 5705,
             all_pages = FALSE,
             page = 1,
             page_size = 3)

---

Get form metadata and field structure.

Description

Retrieves the metadata and complete component (field) structure of a specific form. This function replaces the former GetFormStructure.

Usage

GetForm(token, idForm, nameForm = NULL)

Arguments

token	A string access token.
idForm	Numeric Id of the required form.
nameForm	String name of the required form. Used only when idForm is not supplied. When this parameter is used, one extra access quota is spent.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A list with elements: id, name, description, status, category, version, public_answers, and components (a nested data frame representing the form's field schema, where each row is a component with columns id, type, label, help_block, maximum, minimum, visibility, and — for group components — components).

Examples

GetForm("cizio7xeohwgc8k4g4koo008kkoocwg", 5705)
GetForm("cizio7xeohwgc8k4g4koo008kkoocwg", nameForm = "RColetum Test - Iris")
GetForm(token = "cizio7xeohwgc8k4g4koo008kkoocwg",
        nameForm = "RColetum Test - Iris")

---

Get info of all forms.

Description

Retrieve information about all forms in the account.

Usage

GetForms(
  token,
  status = NULL,
  name = NULL,
  page = 1,
  page_size = 100,
  all_pages = TRUE
)

Arguments

token	String access token.
status	Optional filter. State of the form: "enabled" or "disabled".
name	Optional filter. Returns forms whose name contains this string (partial match, case-insensitive).
page	Integer. Starting page when all_pages = FALSE. Default: 1.
page_size	Integer. Number of records per API request (max 500). Default: 100.
all_pages	Logical. If TRUE (default), fetches all pages automatically and returns a combined data frame. If FALSE, returns only the page specified by page.

Details

To get more details about the fields provided by the result, please visit the API documentation.

Value

A data frame with columns: id, name, description, status, category, version, public_answers. Returns NULL with a warning if no forms are found.

Examples

GetForms("cizio7xeohwgc8k4g4koo008kkoocwg")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", status = "enabled")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", name = "Iris")
GetForms("cizio7xeohwgc8k4g4koo008kkoocwg", page_size = 3, all_pages = FALSE)

---