# Introduction to rbison

#### Scott Chamberlain

#### 2020-06-08

`rbison` is an R package to search and retrieve data from the USGS BISON service. `rbison` wraps R code around the BISON API to allow you to talk to the BISON database from R.

BISON has occurrence data for the US only.

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.

## Info

See https://bison.usgs.gov/doc/api.jsp for API docs for the BISON API.

## Install rbison

    install.packages("rbison")

Or install development version from Github

    install.packages("devtools")
    devtools::install_github("ropensci/rbison")

Load packages

    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 = "Helianthus annuus", count = 10)

Inspect summary

    out$summary

Map occurrences

    head(out$counties)

## All points within the US (including AK and HI)

Get data

    out <- bison(species="Bison bison", count=200)

Inspect summary

    out$summary

Map occurrences

    bisonmap(out, tomap="state")

## All points within the contiguous 48 states

Get data

    out <- bison(species="Aquila chrysaetos", count=400)

Inspect summary

    out$summary

Map occurrences

    bisonmap(out, tomap="points")

## Plot county or state

With any data returned from a `bison` call, you can choose to plot 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")

## Constrain search with county IDs or bounding boxes

### Constrain search to a certain county.

Check out https://en.wikipedia.org/wiki/Federal_Information_Processing_Standard_state_code to get state and county fips codes. Fips codes are like so: First two digits are the state code - last three are the county code. For example the 06 in 06037 is the state of California, and the 037 is the Los Angeles county.

    out <- bison(species="Helianthus annuus", countyFips = "06037")

Inspect summary

    out$summary

By default, the query only returned 10 records

    head(out$points)

Or specify county by its actual name - probably much easier.

    out <- bison(species="Helianthus annuus", county = "Los Angeles")

Inspect summary

    out$summary

By default, the query only returned 10 records

    head(out$points)

`bison` will help you if you spell the name wrong, or use a partial name. The results are not printed below, but you would get a prompt asking you to pick between the two counties that start with Los.

    bison(species="Helianthus annuus", county = "Los")

### Constrain search to a amorphous area.

Check out http://en.wikipedia.org/wiki/Well-known_text for an in depth look at the options, terminology, etc.

    out <- bison(species="Helianthus annuus", aoi = "POLYGON((-111.06360117772908 38.84001566645886,-110.80542246679359 39.37707771107983,-110.20117441992392 39.17722368276862,-110.20666758398464 38.90844075244811,-110.63513438085685 38.67724220095734,-111.06360117772908 38.84001566645886))")

Inspect summary

    out$summary

The data

    out$points

### Constrain search to a certain aoibbox.

An aoibbox uses the format minx, miny, maxx, maxy.

    out <- bison(species="Helianthus annuus", aoibbox = '-120.31,35.81,-110.57,40.21')

Inspect summary

    out$summary

The data, by default, the query only returned 10 records

    head(out$points)