ala_fields: Retrieves a list of all field names that can be used with data retrieval functions

Description

Note for occurrence fields: only fields that are indexed in the ALA database can be queried (e.g. used in the fq parameter in occurrences. These fields are identified by the indexed column in ala_fields("occurrence"). Only fields that are stored in the database can be returned as part of an occurrences call. These fields are identified by the stored column in ala_fields("occurrence"). The calling syntaxes ala_fields("occurrence_stored") and ala_fields("occurrence_indexed") are for convenience, and are equivalent to subset(ala_fields("occurrence"),stored) and subset(ala_fields("occurrence"),indexed).

Usage

ala_fields(fields_type = "occurrence", as_is = TRUE)
field_info(field_id, maxrows = 50, record_count_only = FALSE)

Arguments

fields_type

text: one of the following

"general" - for searching taxa, datasets, layers, and collections metadata
"occurrence" - for species occurrence records
"occurrence_stored" - can be returned as part of a species occurrence record search (equivalent to subset(ala_fields("occurrences"),stored))
"occurrence_indexed" - can be queried as part of a species occurrence record search (equivalent to subset(ala_fields("occurrences"),indexed))
"layers" - fields associated with the environmental and contextual layers. For additional information on layers, including metadata and licensing, see search_layers
"assertions" - potential issues flagged on one or more occurrence record fields
"images - for image search

as_is

logical: if TRUE, leave the field names as they are returned from the ALA web services. Arguments that are passed directly to the ALA's web services (e.g. parameter fq in occurrences) should use field names in this format. If as_is is FALSE, the returned $names entries will be modified to make them consistent with the corresponding column names in R data.frames returned by e.g. occurrences. as_is = FALSE has no effect when fields_type is "layers". Note that prior to v1.20, as_is = FALSE did not work correctly.

field_id

text: id of environmental/contextual layer field for which to look up information Prepend "el" for "environmental" (gridded) layers and "cl" for "contextual" (polygonal) layers

maxrows

integer: maximum number of records to download. Some contextual layers (those with field_ids starting with "cl") have a very large number of records and attempting to download the full set can cause R to crash. Specifying -1 for maxrows will download the full set of records for that field

record_count_only

logical: if TRUE, return just the count of records that would be downloaded, but don't download them. This really only makes sense for contextual layers, because environmental layers have only one record per layer

Value

If record_count_only is TRUE, the number of records is returned as numeric. Otherwise, a data frame containing the field name and various attributes; an empty data frame is returned if no match is found

References

Relevant ALA web services:

for fields_type "occurrence": https://api.ala.org.au/#ws72
for fields_type "general": https://api.ala.org.au/#ws88
for fields_type "layers": https://api.ala.org.au/#ws11 (see also descriptions of the spatial layers: https://spatial.ala.org.au/ws/layers/index)
for fields_type "assertions": https://api.ala.org.au/#ws81

Examples

Run this code

# NOT RUN {
 l <- ala_fields("layers")
 l[, 4]
 o <- ala_fields("occurrence")
 o[1:13, ]
 a <- ala_fields("assertions")
 a$description
 field_info("cl22")
 field_info("el767")
# }