Retrieve ALA occurrence data via the "occurrence download" web service.
At least one of taxon
, wkt
, or fq
must be supplied for
a valid query.
occurrences( taxon, wkt, fq, fields, extra, qa, method, generate_doi = FALSE, email, email_notify = FALSE, download_reason_id = ala_config()$download_reason_id, reason, verbose = ala_config()$verbose, record_count_only = FALSE, use_layer_names = TRUE, use_data_table = TRUE )
taxon | string: (optional) query of the form field:value
(e.g. "genus:Heleioporus") or a free text search (e.g. "macropodidae").
Note that a free-text search is equivalent to specifying the "text" field
(i.e. |
---|---|
wkt | string: (optional) a WKT (well-known text) string providing a spatial polygon within which to search, e.g. "POLYGON((140 -37,151 -37,151 ] -26,140.131 -26,140 -37))" |
fq | string: (optional) character string or vector of strings,
specifying filters to be applied to the original query. These are of the
form "INDEXEDFIELD:VALUE" e.g. "kingdom:Fungi".
See |
fields | string vector: (optional) a vector of field names to return.
Note that the columns of the returned data frame are not guaranteed to
retain the ordering of the field names given here. If not specified, a
default list of fields will be returned. See
|
extra | string vector: (optional) a vector of field names to include
in addition to those specified in |
qa | string vector: (optional) list of record issues to include in
the download. Use |
method | string: This parameter is deprecated. Now all queries use
offline method unless |
generate_doi | logical: by default no DOI will be generated. Set to true if you intend to use the data in a publication or similar |
string: the email address of the user performing the download
(required unless |
|
email_notify | logical: by default an email with the download information will be sent to the `email` specified. Set to `FALSE` if you are doing a large number of downloads |
download_reason_id | numeric or string: (required unless
record_count_only is TRUE) a reason code for the download, either as a
numeric ID (currently 0--11) or a string (see |
reason | string: (optional) user-supplied description of the reason for the download. Providing this information is optional but will help the ALA to better support users by building a better understanding of user communities and their data requests |
verbose | logical: show additional progress information? [default is set by ala_config()] |
record_count_only | logical: if TRUE, return just the count of records
that would be downloaded, but don't download them. Note that the record
count is always re-retrieved from the ALA, regardless of the caching
settings. If a cached copy of this query exists on the local machine, the
actual data set size may therefore differ from this record count.
|
use_layer_names | logical: if TRUE, layer names will be used as layer column names in the returned data frame (e.g. "radiationLowestPeriodBio22"). Otherwise, layer id value will be used for layer column names (e.g. "el871") |
use_data_table | logical: if TRUE, attempt to read the data.csv file using the fread function from the data.table package. If this fails with an error or warning, or if use_data_table is FALSE, then read.table will be used (which may be slower) |
Data frame of occurrence results, with one row per occurrence record. The columns of the dataframe will depend on the requested fields
Associated ALA web service for record counts: https://api.ala.org.au/#ws3
Associated ALA web service for occurence downloads: https://api.ala.org.au/#ws4
Field definitions: https://biocache-ws.ala.org.au/ws/index/fields
WKT reference http://www.geoapi.org/3.0/javadoc/org/opengis/referencing/doc-files/WKT.html
ala_reasons
for download reasons;
ala_config
if (FALSE) { ## count of records from this data provider x <- occurrences(taxon = "data_resource_uid:dr356",record_count_only = TRUE) ## download records, with standard fields x <- occurrences(taxon = "data_resource_uid:dr356", download_reason_id = 10, email = 'your_email_here') ## download records, with all fields x <- occurrences(taxon = "data_resource_uid:dr356",download_reason_id = 10, fields = ala_fields("occurrence_stored",as_is = TRUE)$name) ## download records, with specified fields x <- occurrences(taxon = "genus:Heleioporus", fields = c("longitude","latitude", "common_name","taxon_name","el807"),download_reason_id = 10) ## download records in polygon, with no quality assertion information x <- occurrences(taxon = "genus:Heleioporus", wkt = "POLYGON((145 -37,150 -37,150 -30,145 -30,145 -37))", download_reason_id = 10,qa = "none") y <- occurrences(taxon = "taxon_name:\"Alaba vibex\"",fields = c("latitude", "longitude","el874"), download_reason_id = 10) str(y) # equivalent direct webservice call # [see this by setting ala_config(verbose = TRUE)]: # https://biocache-ws.ala.org.au/ws/occurrences/index/download?q=taxon_name%3A%22Alaba%20vibex%22& # fields=latitude,longitude,el874&reasonTypeId=10&sourceTypeId=2001&esc=%5C&sep=%09&file=data occurrences(taxon="taxon_name:\"Eucalyptus gunnii\"", fields=c("latitude","longitude"), qa="none",fq="basis_of_record:LivingSpecimen", download_reason_id=10) # equivalent direct webservice call # [see this by setting ala_config(verbose=TRUE)]: # https://biocache-ws.ala.org.au/ws/occurrences/index/download?q=taxon_name%3A%22 # Eucalyptus%20gunnii%22&fq=basis_of_record%3ALivingSpecimen&fields=latitude,longitude&qa=none& # reasonTypeId=10&sourceTypeId=2001&esc=%5C&sep=%09&file=data }