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.
From CRAN
install.packages("rbison")
Or the development version from Github
install.packages("devtools")devtools::install_github("ropensci/rbison")library('rbison')
Load package
library("rbison")
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#> [1] 7
bisonmap(out)
out <- bison(species = "Cyanocitta stelleri", count = 500)
out$summary#> $fossil#> [1] 4#> #> $observation#> [1] 712380#> #> $centroid#> [1] 1#> #> $specimen#> [1] 3438#> #> $unknown#> [1] 208
bisonmap(out)
out <- bison(species = "Aquila chrysaetos", count = 300)
out$summary#> $fossil#> [1] 681#> #> $observation#> [1] 159076#> #> $centroid#> [1] 1#> #> $unknown#> [1] 11046#> #> $specimen#> [1] 1911
bisonmap(out)
bisonmap(out, tomap = "county")
bisonmap(out, tomap = "state")
The taxa service searches for and gives back taxonomic names
bison_tax(query = "*bear")#> $numFound#> [1] 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#> [1] 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 bison()
function
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)
rbison
in 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 count
parameter so that requests larger than 1000 are handled with a while
loop until we get all the data requested (#58)bison()
the what
parameter 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)vcr
(#61)points
slot 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 data.table
(#60)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 @bomeararbison::bison_solr
now 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 spocc
) (#53)bison_solr()
, e.g., ITISscientificName
, higherGeographyID
, and countryCode
. See ?bison_solr
for details. (#54)count
parameter in bison()
: default is now 25, and max is 500. Also, default for start
set to 0, so we pass that by default now. We check to make sure count
is not greater than 500 since the BISON API does not fail gracefully if it is greater than 500.crul
http client instead of httr
(#47)tools/
dir as requested by CRAN (#48)dplyr::rbind_all()
with dplyr::bind_rows()
(#39)ggplot2
version in mapping function
rbison::bisonmap()
(#38)stats
and methods
packages (#36).Rbuildignore
the vignettes/figure
directory (#37)@importFrom
across all package imports.query
parameter in bison_tax()
is now required.\donttest
.assertthat
.bisonmap()
function.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 bison()
only.stringsAsFactors=FALSE
.callopts
parameters to ...
, so you can pass in named options to httr::GET
calls 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 callopts
is still used.data.table
, importing dplyr
now, and assertthat
jsonlite
from rjson
for JSON parsing.bison()
loses parameter itis
, as it only has one possible value; gains parameter params
that accepts further parameters to modify the search; changed parameter callopts
to ...
.params
parameter in the bison()
function.callopts
to ...
in bison_providers()
.callopts
to ...
in bison_tax()
.bison_solr()
: BISONProviderID
changed to providerID
; BISONResourceID
changed to resourceID
; occurrence_date
changed to eventDate
; collector
changed to recordedBy
; gains parameters catalogNumber
, ITIScommonName
, kingdom
, and verbose
. Adde a bunch of examples.blanktheme()
function to 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 httr::GET
bison()
function gains "itis" parameter. Setting to TRUE allows searches on ITIS taxonomic serial numbers (TSNs)bison()
function gains "tsn" parameter. Specify abison_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()
or bison_solr()
. Now those two functions simply give the data back immediately.