ropensci/rgbif

Interface to the Global Biodiversity Information Facility API

rgbif

rgbif is an R package which gives you access to GBIF mediated data via its REST API.

GBIF (the Global Biodiversity Information Facility) is an international network and data infrastructure funded by the world's governments and aimed at providing anyone, anywhere, open access to data about all types of life on Earth.

Installation

install.packages("rgbif") # CRAN version

pak::pkg_install("ropensci/rgbif") # dev version

install.packages("rgbif", repos="https://dev.ropensci.org") # dev version

Getting Started

There are several long-form articles that can help get you started:

• Getting Started
• Getting Occurrence Data From GBIF
• Working With Taxonomic Names

Most GBIF users are interested in getting lat-lon occurrence records.

occ_search(scientificName = "Pan troglodytes")
occ_data(scientificName = "Pan troglodytes")

It is usually better to get occurrence records using a taxonKey. See the article Working With Taxonomic Names.

taxonKey <- name_backbone("Pan troglodytes")$usageKey
occ_search(taxonKey = taxonKey)

GBIF strongly recommends the use of occ_download() rather than occ_search() for serious research projects. See article Getting Occurrence Data From GBIF.

It is required to set up your GBIF credentials to make downloads from GBIF.

occ_download(pred("taxonKey", 5219534)) # 5219534 is the taxonKey for Pan troglodytes

Citation

Under the terms of the GBIF data user agreement, users who download data agree to cite a DOI. Please see GBIF’s citation guidelines and Citing GBIF Mediated Data.

Please also cite rgbif by running citation(package = "rgbif").

Contributors

This list honors all contributors in alphabetical order. Code contributors are in bold.

adamdsmith - AgustinCamacho - AldoCompagnoni - AlexPeap - andzandz11 - AshleyWoods - AugustT - barthoekstra - benmarwick - cathynewman - cboettig - coyotree - damianooldoni - dandaman - djokester - dlebauer - dmcglinn - dmi3kno - dnoesgaard - DupontCai - ecology-data-science - EDiLD - elgabbas - emhart - fxi - ghost - gkburada - hadley - Huasheng12306 - ibartomeus - JanLauGe - jarioksa - jeroen - jhnwllr - jhpoelen - jivelasquezt - jkmccarthy - johnbaums - jtgiermakowski - jwhalennds - karthik - kgturner - Kim1801 - ljuliusson - ljvillanueva - luisDVA - martinpfannkuchen - MattBlissett - MattOates - maxhenschell - mdsumner - no-la-ngo - Octoberweather - omahs - Pakillo - peterdesmet - PhillRob - PietrH - poldham - qgroom - raymondben - rossmounce - sacrevert - sagitaninta - sckott - scottsfarley93 - simon-tarr - SriramRamesh - stevenpbachman - stevensotelo - stevenysw - TomaszSuchan - tphilippi - vandit15 - vervis - vijaybarve - willgearty - Xuletajr - yvanlebras - zixuan75

Meta

• Please report any issues or bugs.
• License: MIT
• Get citation information for rgbif in R doing citation(package = 'rgbif')
• Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

There are similar GBIF clients in other languages :

• Python
• Ruby
• PHP

This package is part of spocc, along with several other packages, that provide access to occurrence records from multiple data sources.

rgbif's Issues

Implement name_usage fxn

Put in useful http error messages for all functions

stop_for_status, etc.

To do fixes

-Need to change old parameter additions to queries in some of the functions to use the getForm style of querying.
-Species names probably needs to still have the paste() thing to put a +, etc. in between genus and epithet
-add all parameters possible for some functions instead of just a few
-figure out if stylesheet is actually a parameter to include
-include some shortcuts to plotting results on a map using ggplot2

styling geojson

Figure out how to allow users to style geojson point, polygon, line, etc. feature types.

• Point - already done mostly via stylegeojson().
• Polygons
• MultiPolygons
• Lines

fix gbifdata so it doesn't remove rows w/o lat/long by default

Related to #25 -

Need to change gbifdata return data without removing rows with lat/long data that have missing values/zero values/etc.

Lay out how to get higher taxonomic taxonconceptkeys using taxonsearch, etc.

Fixes to gbifdata

• Set minimal=FALSE by default in fxn gbifdata
• minimal parameter is missing in docs for gbifdata, add it in

occurrencelist() not returning all the gbif records for a species

In version 0.3.0, I noticed that the occurrencelist() function does return all of the records that an identical query at http://data.gbif.org/ .

For example the query:

occurrencelist(scientificname = 'Aristolochia serpentaria', coordinatestatus = TRUE, maxresults = 1e6)

returns 179 records but the identical query at http://data.gbif.org/ returns 431 records.

I have not tried to track down the potential source of this discrepancy in the code yet. I also have not investigated if other versions of rgbif have similar issues.

Mapping API

Possibly use

http://uat.gbif.org/developer/maps#preview

An example

More parameters to add to name_lookup

http://dev.gbif.org/wiki/display/POR/Webservice+API#WebserviceAPI-ChecklistBankServices:SearchService

See supported facet filters, and maybe more too

Synonymns

From user Joseph:

• Do you perchance know how to also download records with synonymous Scientific names? For instance using GBIF on the web the speadsheet download for "Euphydryas editha" contains also records for "Occidryas editha augusta." Or the GBIF web download for "Ochotona princeps" contains one record listed as "Ochotona princei."

add additional parameters to endpoints for all functions

gbifmap is broken

All the examples and tutorials we have on the site and many of our talks don't work anymore. gbifmap was replaced by gbifmap_dens and gbifmap_list and this doesn't seem to map out correctly.

for e.g.

> a <- occurrencelist(scientificname = "Puma concolor", coordinatestatus = TRUE, maxresults = 40)
> gbifmap(a)
Error: could not find function "gbifmap"

Support multiple values for a parameter

The GBIF API allows you to set multiple values for some parameters. See here

e.g., you can do scientificname='Abies'&scientificname='Pinus'

Also, can do with other parameters:

scientificname, taxonconceptkey, dataproviderkey, dataresourcekey, resourcenetworkkey, basisofrecordcode, cellid, centicellid, hostisocountrycode, originisocountrycode, originregioncode, year, month, day

One solution is to do

scientificname = c('Puma concolor','Accipiter erythronemius')

makemanylist <- function(x)
{  
  if(length(x) > 1){
    temp <- as.list(x)
    names(temp) <- rep(deparse(substitute(x)), length(x))
    temp
  } else
  {
    x
  }
}

makemanylist(scientificname)

$scientificname
[1] "Puma concolor"

$scientificname
[1] "Accipiter erythronemius"

Remove warning from occurrencelist calls

Is the following bad/meaningless (if not meaningful, remove)?

In is.na(df$decimalLatitude) :
  is.na() applied to non-(list or vector) of type 'NULL'

Package does not load with install_github

Fix this...

occurrencelist parameters

To add all parameters possible for 'occurrencelist' function to make it complete

Fix occurrencelist_all bugs

• Only has support for species basically right now. Add argument for rank, so that user specifies what rank to get syonym names from
• In call to gbif backbone taxonomy, there can be more than one key, so let user choose, or choose one at random, or first one?

Include messages directing users to new functions and parameters with new api

• Indicate new functions for new api to use when they attempt to use a function from the old api
• Try to indicate which parameters are equivalent to old parameters if possible
• Include a crosswalk table for functions in the readme?

NAs introduced by coercion ?

Hi thanks for this package it's really very useful! I just tried out the GitHub version over the one found in CRAN, and ran into an issue just with the demo usage. This in no way affects me, just thought you might want a heads up.

splist <- c('Accipiter erythronemius', 'Junco hyemalis', 'Aix sponsa', 'Buteo regalis')
out <- lapply(splist, function(x) occurrencelist(x, coordinatestatus = T, maxresults = 100))
Warning messages:
1: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
2: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
3: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
4: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
5: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
6: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
7: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
8: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
gbifmap(out)
Error in UseMethod("gbifmap") :
no applicable method for 'gbifmap' applied to an object of class "list"

check minor build errors to fix at some point

• many of these, e.g., gbifmap.gbifdens: no visible binding for global variable 'group'
• S3 methods shown with full name in documentation object 'gbifmap.gbifdens':
  'gbifmap.gbifdens'
• S3 methods shown with full name in documentation object 'gbifmap.gbiflist':
  'gbifmap.gbiflist'
• not sure what this one is:

* checking S3 generic/method consistency ... WARNING
gbifdata:
  function(input, minimal)
gbifdata.gbifdens:
  function(input)

gbifmap:
  function(input, ...)
gbifmap.gbifdens:
  function(input, mapdatabase, region, customize)

gbifmap:
  function(input, ...)
gbifmap.gbiflist:
  function(input, mapdatabase, region, geom, jitter, customize)

print:
  function(x, ...)
print.gbifdens:
  function(x)

print:
  function(x, ...)
print.gbiflist:
  function(x)

Fix taxonget

Not sure what's going on here. Why a function inside a function? The inner function could just be removed to avoid inefficient programming.

taxonsearch returns gbifkey as a factor, screws up follow up function calls

From a user via email, should change to stringsAsFactors=FALSE to avoid this problem

Write tests for new api functions

Aspect ratio in map functions

Need to maintain aspect ratio while plotting maps with fxns gbifmap_list, gbifmap_dens and gbifmap. The maps might look like this

depending on the setting.

We can simply do it by adding coord_fixed(ratio = 1) in functions i.e.

...
    geom_polygon(aes(group=group), fill="white", color="gray40", size=0.2) + coord_fixed(ratio = 1) +
 ..

Reach out to users to test functions on newapi branch

Wrapping new api

Hey @dmcglinn I started wrapping the new GBIF API described here in the newapi branch of this repo. Feel free to chip in if you get a chance.

Match rgbif search beavior with that of GBIF website

Relate to issues #25

Change search functions in rgbif including occurrencelist, occurrencelist_many,and densitylist so that they match the search functionality of the GBIF website.

E.g., in issue #25 the search for 'Aristolochia serpentaria' only returns exact matches of 'Aristolochia serpentaria', whereas the site returns fuzzy matches.

try to change rgbif to match behavior of GBIF website

This may be hard though

if as simple as always changing 'Aristolochia serpentaria' to 'Aristolochia serpentaria*', would be easy, but perhaps not that easy

When maxresults is > 10000, R writes 1e+05 , and hence the url is not working. Don't fix that for me. Moreover, using "100000" solves it.

From @ibartomeus on twitter

with respect to occurrencelist fxn

Search error from cran version

I was reading the rgbif tutorial to integrate part of it into a figshare tutorial and I get the following error when I run this code snippet

library(rgbif)
dan_chr <- occurrencelist(sciname = "Danaus chrysippus", coordinatestatus = TRUE, maxresults = 1000, latlongdf = TRUE)
Namespace prefix to on decimalLatitude is not defined (but repeated 1000x)

Better default maps

Port over maps like used in rbison to rgbif

occ_search help file - taxonkey

Minor point but had me confused.

occ_search takes taxonKey NOT name but then in arguments you have:

taxonKey - Scientific name

Add deprecated support throughout package when transitioning

Following on Gavin's suggestions:

Step 1: add deprecated stuff and submit to CRAN

• Don't remove old functions, but use the function .Deprecated() within the body of deprecated functions, and specify what the new function name is to use, if any.
• Add .Rd files for the deprecated functions like fxnname-deprecated.Rd
• Add an rgbif-deprecated.Rd file to list deprecated functions

Step 2: add defunct stuff and submit to CRAN

At some later point, whenever ready:

• deprecated functions are made defunct via replacement of the fxn body with a call to .Defunct()
• remove the fxnname-deprecated.Rd entries
• remove defunct fxns from rgbif-deprecated.Rd
• add the defunct functions as a list to rgbif-defunct.Rd

ggplot2 syntax changes

From Karthik:

"additional suggestions. rather than have "poitntype" why not keep it as geom? Would make it easier for regular ggplotters to guess the correct one rather than learn new usage. Same with jitterposition. why not just "jitter"?"

Make name_lookup return something more useful

Right now name_lookup returns a list of a whole bunch of data. Make an option for more concise output.

Change capwords fxn name to avoid namespace conflicts

Change https://github.com/ropensci/rgbif/blob/newapi/R/zzz.r from capwords() to gbif_capwords() maybe

Make useful outputs from name_usage function

Right now returns lists

Update gbifmap function

from karhink:

https://gist.github.com/4254076

Cran version of rgbif returning results for incorrect species name

Hey fellas,

I'm not sure if this is the best place for this so if not I'm happy to repost elsewhere but I just wanted to let you know that the cran version of rgbif is returning wonky species results for the function occurrencelist(). For example if you attempt to run the examples in ~/library/rgbif/demo/List.R then you will see that the queries return results for a variety of different species names. Each time you run a query you get a different set of species names as well. My version of R is 2.15.1 (64-bit).

This does not happen in the github version of the package! Let me know if you need more specifics.

Dan

More then 1000 results?

Can't I get more than 1000 results?

> pres_rgbif <- occurrencelist(scientificname='Erebia gorge*', maxresults = 2000, 
+                        coordinatestatus = TRUE, latlongdf = TRUE, removeZeros = FALSE)
> nrow(pres_rgbif)
[1] 1000
> require(dismo)
> pres_dismo <- gbif("Erebia", "gorge*",sp=TRUE)
Erebia gorge* : 1739 occurrences found
0-1000-1739
> nrow(pres_dismo)
[1] 1739

make vignette

gbifdata make handle cases with no data, etc.

Add ability to gbifmap fxn to plot outputs from dismo

Have a more informative error message when a name isn't found.

Update the vignette for new api

Submit new version to CRAN

coercion NAs issue

occurrencelist and occurrencelist_many throwing errors

1: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
2: In FUN(1:7[[7L]], ...) : NAs introduced by coercion
3: In FUN(1:7[[7L]], ...) : NAs introduced by coercion

mentioned in this bug report

occ_search help file - taxonkey

Minor point but had me confused.

occ_search takes taxonKey NOT name but then in arguments you have:

taxonKey - Scientific name

Write a test suite

Maybe makes more sense for taxonsearch to return all data, not just taxonconceptKeys