rgbif_vignette.Rmd

<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{Tutorial for the new GBIF API}
-->

rgbif vignette - 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. 

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

## Install rgbif and dependencies

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

## Load rgbif and dependencies

```{r load, comment=NA, warning=FALSE, message=FALSE}
library(rgbif); library(XML); library(RCurl); library(plyr); library(ggplot2); library(maps)
```

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

## Get number of occurrences for a set of search parameters

### Search by type of record, all observational in this case

```{r occ_count1, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
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, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(taxonKey=2435099, georeferenced=TRUE)
```

### All georeferenced records in GBIF

```{r occ_count3, comment=NA, warning=FALSE, message=FALSE, cache=TRUE, results='asis'}
occ_count(georeferenced=TRUE)
```

### Records from Denmark

```{r occ_count4, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(country='DENMARK')
```

### Records from France

```{r occ_count5, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(hostCountry='FRANCE')
```

### Number of records in a particular dataset

```{r occ_count6, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(datasetKey='9e7ea106-0bf8-4087-bb61-dfe4f29e0f17')
```

### All records from 2012

```{r occ_count7, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(year=2012)
```

### Records for a particular dataset, and only for preserved specimens

```{r occ_count8, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_count(datasetKey='8626bd3a-f762-11e1-a439-00145eb45e9a', basisOfRecord='PRESERVED_SPECIMEN')
```

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

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

```{r taxrank, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
taxrank()
```

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

## Search for taxon information

### Search for a genus 

```{r name_lookup1, comment=NA, warning=FALSE, message=FALSE}
head(name_lookup(query='Cnaemidophorus', rank="genus", return="data"))
```

### Search for the class mammalia

```{r name_lookup2, comment=NA, warning=FALSE, message=FALSE}
head(name_lookup(query='mammalia')$data)
```

### Look up the species Helianthus annuus

```{r name_lookup3, comment=NA, warning=FALSE, message=FALSE}
head(name_lookup('Helianthus annuus', rank="species")$data)
```

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

## 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, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_get(key=773433533, return='data')
```

### Just taxonomic hierarchy

```{r occ_get2, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_get(key=773433533, return='hier')
```

### All data, or leave return parameter blank

```{r occ_get3, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_get(key=773433533, return='all')
```

### Get many occurrences. `occ_get` is vectorized

```{r occ_get4, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
occ_get(key=c(773433533,101010,240713150,855998194,49819470), return='data')
```

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

## Maps

### Static map using the ggplot2 package

Make a map of **Puma concolor** occurrences

```{r gbifmap1, comment=NA, warning=FALSE, message=FALSE, cache=TRUE}
key <- name_backbone(name='Puma concolor', kingdom='plants')$speciesKey
dat <- occ_search(taxonKey=key, return='data', limit=300, minimal=FALSE)
gbifmap(input=dat)
```

[gbifapi]: http://data.gbif.org/tutorial/services