Interface to the 'USGS' 'BISON' (< https://bison.usgs.gov/>) API, a 'database' for species occurrence data. Data comes from species in the United States from participating data providers. You can get data via 'taxonomic' and location based queries. A simple function is provided to help visualize data.
Wrapper for the USGS Bison API
USGS Biodiversity Information Serving Our Nation (BISON) is a web-based federal mapping resource that provides access to georeferenced (those with latitude and longitude coordinates) and non-georeferenced data describing the occurrence or presence of terrestrial and aquatic species recorded or collected by a person (or instrument) at a specific time in the United States, U.S. Territories, U.S. Marine Exclusive Economic Zones (EEZs), and Canada. Each record in a species occurrence dataset available in BISON will typically consist of a scientific name (genus and specific epithet), a date, and one or more geographic references such as a state name, county name, and/or decimal latitude and longitude coordinates. In addition to these typical data fields, species occurrence datasets often include many other data fields that describe each species occurrence event in more detail.
BISON is the US Node of GBIF and regularly updates from GBIF to have full coverage and is committed to eventually providing most BISON originating data to GBIF, however, users should be aware that several million BISON records are not in GBIF. The Solr API for BISON is fully open with no limits, allowing full batch download, faceting and geospatial searches on both DC fields and BISON added fields such as the full ITIS taxonomy, FIPS Codes, and georeferencing of county records to documented centroids.
rbison allows one to pull species occurrence data from these datasets, inspect species occurance summaries, and then map species occurance within the US, within the contiguous 48 states, and/or at county or state level.
Current data providers for BISON can be found at https://bison.usgs.gov/providers.jsp
See https://bison.usgs.gov/doc/api.jsp for API docs for the BISON API.
Or the development version from Github
Notice that the function
bisonmap automagically selects the map extent to plot for you, being one of the contiguous lower 48 states, or the lower 48 plus AK and HI, or a global map. If some or all points outside the US, a global map is drawn, and throws a warning. . You may want to make sure the occurrence lat/long coordinates are correct.
out <- bison(species = "Phocoenoides dalli dalli", count = 10)
out$summary#> $specimen#>  7
out <- bison(species = "Cyanocitta stelleri", count = 500)
out$summary#> $fossil#>  4#>#> $observation#>  712380#>#> $centroid#>  1#>#> $specimen#>  3438#>#> $unknown#>  208
out <- bison(species = "Aquila chrysaetos", count = 300)
out$summary#> $fossil#>  681#>#> $observation#>  159076#>#> $centroid#>  1#>#> $unknown#>  11046#>#> $specimen#>  1911
bisonmap(out, tomap = "county")
bisonmap(out, tomap = "state")
The taxa service searches for and gives back taxonomic names
bison_tax(query = "*bear")#> $numFound#>  54#>#> $names#> lc_vernacularName vernacularName#> 1 American black bear American black bear#> 2 American Black Bear American Black Bear#> 3 Asian Black Bear Asian Black Bear#> 4 Asiatic black bear Asiatic black bear#> 5 banded woollybear banded woollybear#> 6 Bear Canyon talussnail Bear Canyon talussnail#> 7 Bear Creek slitmouth Bear Creek slitmouth#> 8 bear daisy bear daisy#> 9 bear flower bear flower#> 10 bear garlic bear garlic#>#> $highlight#> NULL#>#> $facets#> NULL
And you can search by scientific name
bison_tax(query = "Helianthus*", method = "scientificName")#> $numFound#>  240#>#> $names#> scientificName#> 1 Discoaster helianthus#> 2 Helianthus decapetalus#> 3 Helianthus ambiguus#> 4 Helianthus crassifolius#> 5 Helianthus dowellianus#> 6 Helianthus luxurians#> 7 Helianthus arenicola#> 8 Helianthus atrorubens#> 9 Helianthus frondosus#> 10 Helianthus nuttallii canadensis#>#> $highlight#> NULL#>#> $facets#> NULL
The occurrence service searches by scientific names and gives back occurrence
data similar to data given back by the
Searching for data and looking at output
x <- bison_solr(scientificName = "Aquila chrysaetos", rows = 10,fl = "scientificName,decimalLongitude,decimalLatitude")x$points#> decimalLongitude scientificName decimalLatitude#> 1 -75.9530 Aquila chrysaetos 37.12740#> 2 -122.8319 Aquila chrysaetos 42.45076#> 3 -114.0025 Aquila chrysaetos 46.69240#> 4 -111.8859 Aquila chrysaetos 41.24911#> 5 -113.3001 Aquila chrysaetos 49.18417#> 6 -121.7681 Aquila chrysaetos 37.68183#> 7 -121.9796 Aquila chrysaetos 37.49512#> 8 -90.6039 Aquila chrysaetos 43.84988#> 9 -113.7063 Aquila chrysaetos 48.81654#> 10 -107.1469 Aquila chrysaetos 40.41912
Mapping the data
out <- bison_solr(scientificName = "Aquila chrysaetos", rows = 1000)bisonmap(out)
rbisonin R doing
citation(package = 'rbison')
This package is part of a richer suite called SPOCC Species Occurrence Data, along with several other packages, that provide access to occurrence records from multiple databases. We recommend using SPOCC as the primary R interface to rbison unless your needs are limited to this single source.
bison()pagination: previous max as far as we knew was 500 per a single request, but apparently is now 1000. In addition, we no loop internally over the
countparameter so that requests larger than 1000 are handled with a
whileloop until we get all the data requested (#58)
whatparameter is defunct/removed. It let the user pick what part of the results they wanted, but it is super simple to do this once the data is returned. (#59)
pointsslot of the
bison()function. previously we were filtering the records to only those with lat and lon values. now we return all. this means some records may not have lat/lon data, and may have other missing data. along with this, now importing
bisonmap()that was causing a problem when a state was given in the
bison()call that was passed to
bisonmap(tomap = "county"); maps were not right, fixed now (#57) thanks @bomeara
rbison::bison_solrnow supports range queries for certain parameters. It doesn't make sense to do a range query for a character string parameter (e.g., range between Asteraceae and Juncaceae), but you can do them for any parameters that are numeric/integer/date. See examples in
?bison_solr. (this was added originally to facilitate date based searching in
?bison_solrfor details. (#54)
bison(): default is now 25, and max is 500. Also, default for
startset to 0, so we pass that by default now. We check to make sure
countis not greater than 500 since the BISON API does not fail gracefully if it is greater than 500.
crulhttp client instead of
tools/dir as requested by CRAN (#48)
ggplot2version in mapping function
@importFromacross all package imports.
bison_tax()is now required.
bison_stats()to query the statistics about BISON downloads.
citation_datause()to get information on data use rules, and citation for using BISON data.
rbison. The main vignette covers
..., so you can pass in named options to
httr::GETcalls instead of through
callopts, except in functions that interact with a SOLR engine, in which case
...is reserved for passing on additional SOLR parameters, and then
calloptsis still used.
rjsonfor JSON parsing.
itis, as it only has one possible value; gains parameter
paramsthat accepts further parameters to modify the search; changed parameter
paramsparameter in the
recordedBy; gains parameters
verbose. Adde a bunch of examples.
bison_blanktheme()to avoid namespace conflicts with the rgbif package.
bison()function gains "what" parameter, to allow selection of the type of data to get back. All data is returned from the API (As there is no way to select subsets of data), but the what parameter lets you discard the things you don't want, saving on memory.
bison()function gains "callopts" parameter to pass on curl options to
bison()function gains "itis" parameter. Setting to TRUE allows searches on ITIS taxonomic serial numbers (TSNs)
bison()function gains "tsn" parameter. Specify a
bison_providers()to get metadata on data providers to BISON.
bison_data()function removed. This function was used to get data back from a call to
bison_solr(). Now those two functions simply give the data back immediately.