rbison
Interface to the 'USGS' 'BISON' API
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.
Installation
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.
get data
out <- bison(species = "Phocoenoides dalli dalli", count = 10)inspect summary
out$summary#> $specimen#> [1] 7map occurrences
bisonmap(out)
All points within the US (including AK and HI)
get data
out <- bison(species = "Cyanocitta stelleri", count = 500)inspect summary
out$summary#> $fossil#> [1] 4#> #> $observation#> [1] 712380#> #> $centroid#> [1] 1#> #> $specimen#> [1] 3438#> #> $unknown#> [1] 208map occurrences
bisonmap(out)
All points within the contiguous 48 states
get data
out <- bison(species = "Aquila chrysaetos", count = 300)inspect summary
out$summary#> $fossil#> [1] 681#> #> $observation#> [1] 159076#> #> $centroid#> [1] 1#> #> $unknown#> [1] 11046#> #> $specimen#> [1] 1911map occurrences
bisonmap(out)
Map county or state level data
Counties - using last data call for Aquila
bisonmap(out, tomap = "county")
States - using last data call for Aquila
bisonmap(out, tomap = "state")
BISON SOLR interface
taxa
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#> NULLAnd 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#> NULLoccurrence search
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.41912Mapping the data
out <- bison_solr(scientificName = "Aquila chrysaetos", rows = 1000)bisonmap(out)
Meta
- Please report any issues or bugs.
- License: MIT
- Get citation information for
rbisonin R doingcitation(package = 'rbison') - Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
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.
News
rbison 0.8.0
MINOR IMPROVEMENTS
- update readme and vignette regarding relationship between GBIF and BISON (#63)
- fix a test fixture that had non-ascii characters (#64)
rbison 0.7.0
NEW FEATURES
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 thecountparameter so that requests larger than 1000 are handled with awhileloop until we get all the data requested (#58)- to simplify
bison()thewhatparameter 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)
MINOR IMPROVEMENTS
- clean up description of USGS BISON in README (#56) thanks @esellers-usgs
- tests now caching HTTP requests via
vcr(#61) - changed internal processing of the occurrence records output in the
pointsslot of thebison()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 importingdata.table(#60)
BUG FIXES
- fixed bug in
bisonmap()that was causing a problem when a state was given in thebison()call that was passed tobisonmap(tomap = "county"); maps were not right, fixed now (#57) thanks @bomeara
rbison 0.6.0
NEW FEATURES
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 inspocc) (#53)
MINOR IMPROVEMENTS
- Added some missing parameters to
bison_solr(), e.g.,ITISscientificName,higherGeographyID, andcountryCode. See?bison_solrfor details. (#54) - Updated docs for
countparameter inbison(): default is now 25, and max is 500. Also, default forstartset to 0, so we pass that by default now. We check to make surecountis not greater than 500 since the BISON API does not fail gracefully if it is greater than 500.
rbison 0.5.4
NEW FEATURES
- now using
crulhttp client instead ofhttr(#47)
MINOR IMPROVEMENTS
- put readme images in
tools/dir as requested by CRAN (#48) - tidy docs and code to 80 line width (#49)
- use markdown docs (#50)
rbison 0.5.0
MINOR IMPROVEMENTS
- Replace
dplyr::rbind_all()withdplyr::bind_rows()(#39) - Base URLs changd for the BISON API (#34) (#43)
- Fixed a URL in the docs (#44) thanks @esellers-usgs
BUG FIXES
- Fixes for a new
ggplot2version in mapping functionrbison::bisonmap()(#38)
rbison 0.4.8
MINOR IMPROVEMENTS
- Now explicitly importing all non-base R package functions that ship with R, in this case from
statsandmethodspackages (#36) .Rbuildignorethevignettes/figuredirectory (#37)- Using
@importFromacross all package imports. - The
queryparameter inbison_tax()is now required. - Startup message is gone.
- Changed to new base URLs for BISON APIs.
rbison 0.4.5
MINOR IMPROVEMENTS
- Fixes for
\donttest. - Removed dependency on
assertthat. - Sentence Case the Title in the DESCRIPTION file!!!!!!
- Fixed a test for the
bisonmap()function.
rbison 0.4.3
NEW FEATURES
- New function
bison_stats()to query the statistics about BISON downloads. - New function
citation_datause()to get information on data use rules, and citation for using BISON data. - New vignette other_functions that goes over the other functions in
rbison. The main vignette coversbison()only.
BUG FIXES
- Changed output of all data to have
stringsAsFactors=FALSE.
MINOR IMPROVEMENTS
- Changed all
calloptsparameters to..., so you can pass in named options tohttr::GETcalls instead of throughcallopts, except in functions that interact with a SOLR engine, in which case...is reserved for passing on additional SOLR parameters, and thencalloptsis still used. - No longer importing
data.table, importingdplyrnow, andassertthat - Changed to MIT license.
- Changed to
jsonlitefromrjsonfor JSON parsing. bison()loses parameteritis, as it only has one possible value; gains parameterparamsthat accepts further parameters to modify the search; changed parametercalloptsto....- Add many examples of using the
paramsparameter in thebison()function. - Changed parameter
calloptsto...inbison_providers(). - Changed parameter
calloptsto...inbison_tax(). - In
bison_solr():BISONProviderIDchanged toproviderID;BISONResourceIDchanged toresourceID;occurrence_datechanged toeventDate;collectorchanged torecordedBy; gains parameterscatalogNumber,ITIScommonName,kingdom, andverbose. Adde a bunch of examples. - Startup message contains reference to citation function.
rbison 0.3.2
BUG FIXES
- Changed
blanktheme()function tobison_blanktheme()to avoid namespace conflicts with the rgbif package.
rbison 0.3.0
NEW FEATURES
- Added a vignette.
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 tohttr::GETbison()function gains "itis" parameter. Setting to TRUE allows searches on ITIS taxonomic serial numbers (TSNs)bison()function gains "tsn" parameter. Specify a- New function
bison_providers()to get metadata on data providers to BISON.
MINOR IMPROVEMENTS
bison_data()function removed. This function was used to get data back from a call tobison()orbison_solr(). Now those two functions simply give the data back immediately.- A startup message added.
rbison 0.2.4
NEW FEATURES
- Pushed first version to CRAN.