records: Methods for nested lists and 'dsmz_result' objects

In BacDive: API Client for BacDive

Methods for nested lists and ‘dsmz_result’ objects

Description

Calls to a JSON-based API may yield nested lists whose conversion to a data frame may not be straightforward. The ‘records’ class of objects can assist in such conversions.

Usage

  records(object, ...)

  ## S3 method for class 'list'
 records(object, ...)

  ## S3 method for class 'dsmz_result'
 records(object, ...)

  ## S3 method for class 'records'
 as.data.frame(x, row.names = NULL,
    optional = TRUE, ...)

  ## S3 method for class 'dsmz_result'
 as.data.frame(x, row.names = NULL,
    optional = TRUE, ...)

  ## S3 method for class 'records'
 summary(object, ...)

  ## S3 method for class 'dsmz_result'
 summary(object, ...)

  ## S3 method for class 'records'
 print(x, ...)

  ## S3 method for class 'dsmz_result'
 print(x, ...)

Arguments

object	List or object of class ‘records’ (which is a special kind of list), or a list or other object to be converted to a ‘records’ object.
x	Object of class ‘records’ or other object that can be converted to such an object.
row.names	NULL or a character vector with row names for the data frame.
optional	Logical vector of length 1 indicating whether creation of syntactic and unique (column) names for the data frame is optional. Note that non-unique names within x, if any, could be corrected but could still yield unexpected assignments of values to columns. The presence of empty names yields an error, hence setting optional to FALSE is necessary in that case.
...	Optional arguments passed to other methods.

Details

This package uses ‘dsmz_result’ objects for storing the direct results of querying the API and ‘records’ objects for storing compiled results (created from ‘dsmz_result’ objects).

Note that each ‘dsmz_result’ object also responds to `$` and `[[`. The most important key is probably ‘results’ as it yields the API entries (one per taxon name). summary and print show an overview of all keys.

When the server signals that the API query was erroneous (as opposed to just yielding zero results), the structure of the returned ‘dsmz_result’ object is different. While a ‘results’ entry should be missing, entries such as ‘code’ (giving the HTTP status code), ‘message’ and ‘title’ should be present in such a case and should indicate the kind of problem.

The compiled API results as returned by retrieve are of class ‘records’. A dedicated as.data.frame method can convert such objects to a data frame.

Value

The as.data.frame method creates a data frame from a list of class ‘records’. The records method creates an object of that class if the given object passes the tests (see the examples). The other methods yield or display basic information about a ‘records’ object.

The summary function returns a list or character vector. The print method returns x, invisibly.

References

https://www.restapitutorial.com/httpstatuscodes.html

See Also

Other common.functions: print.dsmz_keycloak, refresh, retrieve, summary.dsmz_keycloak

Examples

print(records(list()))

x <- records(list(list(A = 1, B = 2)))
print(x)

# the list elements must be lists
x <- try(records(list(A = 1, B = 2)))
stopifnot(inherits(x, "try-error"))

# the list elements must be named lists
x <- try(records(list(list(1, 2))))
stopifnot(inherits(x, "try-error"))

# resulting data frame columns can be lists
x <- records(list(list(A = -1, B = 2), list(B = 3:4)))
stopifnot(inherits(x, "records"))
print(x)
y <- as.data.frame(x)
print(y)
stopifnot(is.data.frame(y), anyNA(y),
  "list" %in% sapply(y, class), dim(y) == c(2L, 2L))

# missing keys yield missing data (NA values)
x <- records(list(list(A = 1, B = 2), list(C = 3, D = 4)))
stopifnot(inherits(x, "records"))
print(x)
y <- as.data.frame(x)
print(y)
stopifnot(is.data.frame(y), anyNA(y),
  dim(y) == c(2L, 4L))

BacDive documentation built on April 29, 2022, 3 a.m.