---
title: Introduction to rgbif
author: Scott Chamberlain
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{introduction}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
knitr::opts_chunk$set(
	comment = "#>",
	collapse = TRUE,
	warning = FALSE,
	message = FALSE,
  purl = NOT_CRAN,
  eval = NOT_CRAN
)
```

Seach and retrieve data from the Global Biodiverity Information Facilty (GBIF)

## About the package

`rgbif` is an R package to search and retrieve data from the Global Biodiverity Information Facilty (GBIF). `rgbif` wraps R code around the [GBIF API][gbifapi] to allow you to talk to GBIF from R.


## Get rgbif

Install from CRAN

```{r install, eval=FALSE}
install.packages("rgbif")
```

Or install the development version from GitHub

```{r installgh, eval=FALSE}
devtools::install_github("ropensci/rgbif")
```

Load rgbif

```{r load}
library("rgbif")
```

## Number of occurrences

Search by type of record, all observational in this case

```{r occ_count1}
occ_count(basisOfRecord='OBSERVATION')
```

Records for **Puma concolor** with lat/long data (georeferened) only. Note that `hasCoordinate` in `occ_search()` is the same as `georeferenced` in `occ_count()`.

```{r occ_count2}
occ_count(taxonKey=2435099, georeferenced=TRUE)
```

All georeferenced records in GBIF

```{r occ_count3}
occ_count(georeferenced=TRUE)
```

Records from Denmark

```{r occ_count4}
denmark_code <- isocodes[grep("Denmark", isocodes$name), "code"]
occ_count(country=denmark_code)
```

Number of records in a particular dataset

```{r occ_count6}
occ_count(datasetKey='9e7ea106-0bf8-4087-bb61-dfe4f29e0f17')
```

All records from 2012

```{r occ_count7}
occ_count(year=2012)
```

Records for a particular dataset, and only for preserved specimens

```{r occ_count8}
occ_count(datasetKey='e707e6da-e143-445d-b41d-529c4a777e8b', basisOfRecord='OBSERVATION')
```

## Search for taxon names

Get possible values to be used in taxonomic rank arguments in functions

```{r taxrank}
taxrank()
```

`name_lookup()` does full text search of name usages covering the scientific and vernacular name, the species description, distribution and the entire classification across all name usages of all or some checklists. Results are ordered by relevance as this search usually returns a lot of results.

By default `name_lookup()` returns five slots of information: meta, data, facets, hierarchies, and names. hierarchies and names elements are named by their matching GBIF key in the `data.frame` in the data slot.

```{r}
out <- name_lookup(query='mammalia')
```

```{r}
names(out)
```

```{r}
out$meta
```

```{r}
head(out$data)
```

```{r}
out$facets
```

```{r}
out$hierarchies[1:2]
```

```{r}
out$names[2]
```

Search for a genus

```{r name_lookup1}
head(name_lookup(query='Cnaemidophorus', rank="genus", return="data"))
```

Search for the class mammalia

```{r name_lookup2}
head(name_lookup(query='mammalia', return = 'data'))
```

Look up the species Helianthus annuus

```{r name_lookup3}
head(name_lookup(query = 'Helianthus annuus', rank="species", return = 'data'))
```

The function `name_usage()` works with lots of different name endpoints in GBIF, listed at [http://www.gbif.org/developer/species#nameUsages](http://www.gbif.org/developer/species#nameUsages).

```{r}
name_usage(key=3119195, language="FRENCH", data='vernacularNames')
```

The function `name_backbone()` is used to search against the GBIF backbone taxonomy

```{r}
name_backbone(name='Helianthus', rank='genus', kingdom='plants')
```

The function `name_suggest()` is optimized for speed, and gives back suggested names based on query parameters.

```{r}
head( name_suggest(q='Puma concolor') )
```


## Single occurrence records

Get data for a single occurrence. Note that data is returned as a list, with slots for metadata and data, or as a hierarchy, or just data.

Just data

```{r occ_get1}
occ_get(key=855998194, return='data')
```

Just taxonomic hierarchy

```{r occ_get2}
occ_get(key=855998194, return='hier')
```

All data, or leave return parameter blank

```{r occ_get3}
occ_get(key=855998194, return='all')
```

Get many occurrences. `occ_get` is vectorized

```{r occ_get4}
occ_get(key=c(855998194, 240713150), return='data')
```


## Search for occurrences

By default `occ_search()` returns a `dplyr` like output summary in which the data printed expands based on how much data is returned, and the size of your window. You can search by scientific name:

```{r}
occ_search(scientificName = "Ursus americanus", limit = 20)
```

Or to be more precise, you can search for names first, make sure you have the right name, then pass the GBIF key to the `occ_search()` function:

```{r}
key <- name_suggest(q='Helianthus annuus', rank='species')$key[1]
occ_search(taxonKey=key, limit=20)
```

Like many functions in `rgbif`, you can choose what to return with the `return` parameter, here, just returning the metadata:

```{r}
occ_search(taxonKey=key, return='meta')
```

You can choose what fields to return. This isn't passed on to the API query to GBIF as they don't allow that, but we filter out the columns before we give the data back to you.

```{r}
occ_search(scientificName = "Ursus americanus", fields=c('name','basisOfRecord','protocol'), limit = 20)
```

Most parameters are vectorized, so you can pass in more than one value:

```{r}
splist <- c('Cyanocitta stelleri', 'Junco hyemalis', 'Aix sponsa')
keys <- sapply(splist, function(x) name_suggest(x)$key[1], USE.NAMES=FALSE)
occ_search(taxonKey=keys, limit=5)
```


********************

## Maps

Using thet GBIF map web tile service, making a raster and visualizing it.

```{r gbifmap1, eval=FALSE}
x <- map_fetch(taxonKey = 2480498, year = 2000:2017)
library(raster)
plot(x)
```

![](../man/figures/rgbif_vign_1.png)

[gbifapi]: https://www.gbif.org/developer/summary
