Search for data or analyses on audioBlast.
Usage
audioblast(
type,
name,
endpoint = NULL,
check = TRUE,
max_pages = NULL,
page = 1,
page_size = 50,
quiet = FALSE,
on.issue = stop,
output = "data.frame",
...
)Arguments
- type
One of data, analysis, standalone.
- name
Name of data or analysis source.
- endpoint
Optionally specify endpoint of an audioBlast module.
- check
Logical. Checks that the module and endpoint exist before sending the query to audioBlast.
- max_pages
Maximum number of data pages to return, by default this is set to NULL and returns all pages.
- page
First page of results to request, defaults to 1.
- page_size
Number of results on each page, defaults to 50. Larger pages need fewer requests to fetch many results.
- quiet
If true will not print progress. Silence is a virtue.
- on.issue
Function to call on error or warning. By default
stopto raise a standard R error. Setting towarningwill instead a warning.- output
By default a
data.frame. "Annotation" will return a list ofAnnotationobjects, with the annotator asidentifiedByand the date of the annotation asdateIdentified; "Annotations", as it was spelt before, still works and is deprecated. "RecordingSet" returns the recordings found by a search of the recordings module as a RecordingSet. "JSON-LD" and "Turtle" return the RDF that audioBlast gives for modules that describe their records as linked data, as a character vector with one element for each page.- ...
Fields and values to filter on. Any field defined by audioBlast.
Value
A data frame, a list of Annotation objects, a RecordingSet or a
character vector, depending on output. NULL if nothing matches the
query.
Details
Filters are given as named arguments in .... audioBlast refuses a filter
that a module does not have with an error naming it, and
audioblastFilters() lists the filters a module has.
A filter given NULL is a filter left out, as it is elsewhere in R. A
filter given NA, or no values at all, is refused by name instead: such a
filter is almost always a lookup that failed or a column that holds nothing,
and leaving it out would search the whole module rather than the part that
was asked for.
A filter that audioBlast lists as taking several values can be given a
vector, e.g. id = c(10754, 11096), which matches a row holding any one of
them. audioBlast takes at most 100 values in a request, so longer vectors are
sent as several requests and their results combined.
A filter on a range (e.g. duration or lat) can be given a single value,
matched exactly, or a range made with ab_range(), e.g.
duration = ab_range(10, 20).
Columns that audioBlast describes as numeric are returned as numbers, and all others as character strings.
audioBlast gives the fields its records carry rather than every field the
module has, and the records of one search can come from sources that do not
hold the same fields, so the responses of a search can differ in them. The
results are joined on all the fields any response carried, and a record that
came without a field has NA there. The fields that only some responses
carried are named in a message, as such an NA says that audioBlast did not
give the field for that record rather than that its source holds nothing.
In a RecordingSet each recording is identified by its audioBlast address,
and its location is the URL of its file. Where audioBlast has measured a
file, which its status says, the hash, duration, sample_rate,
channels and codec of the recording are what audioBlast measured;
otherwise its duration, sample_rate and channels are what its source
says of it. What the source says is kept in the columns declared_duration,
declared_sample_rate and declared_channels, and every other field
audioBlast gives is kept under its own name. A recording that audioBlast gives
without a source or an ID has no address, and is left out with a message. A
recording given more than once, as a search paged through while recordings
are being added to audioBlast can give one, is kept once, also with a
message.
See also
audioblastFilters() for the filters a module takes,
audioblastRecord() to fetch one record, and audioblastDownload() to
download the recordings found.
Examples
if (FALSE) { # \dontrun{
audioblast("data", "recordings", taxon="Gryllotalpa vineae")
# Several recordings at once
audioblast("data", "recordings", source="bio.acousti.ca", id=c(10754, 11096))
# Recordings between 10 and 20 seconds long
audioblast("data", "recordings", source="bio.acousti.ca",
duration=ab_range(10, 20), max_pages=1)
# The classification of a taxon, from the root down
audioblast("data", "taxa", "classification", source="bio.acousti.ca", id=247)
} # }
