rglobi vignette - an R interface to the aggregated biotic interaction data of GloBI (http://globalbioticinteractions.org)

About the package

rglobi allows easy access to the GLoBI database by wrapping the existing API.


Quick start

First, install rglobi

For released version, use:

install.packages("rglobi")

For most recent development version, use:

install.packages("devtools")
## 
## The downloaded binary packages are in
##  /var/folders/v4/0_y78_xj1x7b72l89cwc2kq80000gp/T//RtmpF6qc1T/downloaded_packages
devtools::install_github("ropensci/rglobi")
## Downloading github repo ropensci/rglobi@master
## Installing rglobi
## '/Library/Frameworks/R.framework/Resources/bin/R' --vanilla CMD INSTALL  \
##   '/private/var/folders/v4/0_y78_xj1x7b72l89cwc2kq80000gp/T/RtmpF6qc1T/devtools15b730380a08/ropensci-rglobi-0b49250'  \
##   --library='/Library/Frameworks/R.framework/Versions/3.1/Resources/library'  \
##   --install-tests 
## 
## Reloading installed rglobi
library("rglobi")

Find interactions involving a certain species

Determining which species interact with each other (and how and where) is a major focus of ecology. The Global Biotic Interactions Database offers data on multiple interaction types, and the rglobi library offers several ways to specify and access these interactions. get_interactions() is the primary function used if data on a specific interaction type is required. A focus taxon is entered (may be specified as “Genus species” or higher level (e.g., Genus, Family, Class)).

hsapiens <- get_interactions(taxon = "Homo sapiens", interaction.type = "preysOn")
head(hsapiens)
##   source_taxon_external_id source_taxon_name
## 1               EOL:327955      Homo sapiens
## 2               EOL:327955      Homo sapiens
## 3               EOL:327955      Homo sapiens
## 4               EOL:327955      Homo sapiens
## 5               EOL:327955      Homo sapiens
## 6               EOL:327955      Homo sapiens
##                                                                                                                                                                                                           source_taxon_path
## 1 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 2 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 3 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 4 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 5 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 6 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
##   source_specimen_life_stage interaction_type target_taxon_external_id
## 1                         NA          preysOn               EOL:328048
## 2                         NA          preysOn               EOL:328716
## 3                         NA          preysOn                 EOL:1666
## 4                         NA          preysOn               EOL:326518
## 5                         NA          preysOn              EOL:4453589
## 6                         NA          preysOn              EOL:2815988
##                   target_taxon_name
## 1                 Nandinia binotata
## 2             Cephalophus monticola
## 3                           Manidae
## 4               Atherurus africanus
## 5 Cercopithecus nictitans nictitans
## 6                         Serpentes
##                                                                                                                                                                                                                                                                                                      target_taxon_path
## 1                                                                                                                                                                                                                              Animalia | Chordata | Mammalia | Carnivora | Nandiniidae | Nandinia | Nandinia binotata
## 2                                                                                                                                                                                                                        Animalia | Chordata | Mammalia | Artiodactyla | Bovidae | Cephalophus | Cephalophus monticola
## 3                                                                                                                                                                                                                                                                 Animalia | Chordata | Mammalia | Pholidota | Manidae
## 4                                                                                                                                                                                                                            Animalia | Chordata | Mammalia | Rodentia | Hystricidae | Atherurus | Atherurus africanus
## 5 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Cercopithecoidea | Cercopithecidae | Cercopithecinae | Cercopithecini | Cercopithecus | Cercopithecus nictitans | Cercopithecus nictitans nictitans
## 6                                                                                                                                                                                           Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Reptilia | Squamata | Serpentes
##   target_specimen_life_stage latitude longitude study_title
## 1                         NA       NA        NA          NA
## 2                         NA       NA        NA          NA
## 3                         NA       NA        NA          NA
## 4                         NA       NA        NA          NA
## 5                         NA       NA        NA          NA
## 6                         NA       NA        NA          NA

get_predators_of() and get_prey_of() are wrappers for get_interactions() that remove the need to specify interaction type

hsapiens <- get_prey_of("Homo sapiens")
head(hsapiens)
##   source_taxon_external_id source_taxon_name
## 1               EOL:327955      Homo sapiens
## 2               EOL:327955      Homo sapiens
## 3               EOL:327955      Homo sapiens
## 4               EOL:327955      Homo sapiens
## 5               EOL:327955      Homo sapiens
## 6               EOL:327955      Homo sapiens
##                                                                                                                                                                                                           source_taxon_path
## 1 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 2 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 3 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 4 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 5 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
## 6 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Hominoidea | Hominidae | Homininae | Homo | Homo sapiens
##   source_specimen_life_stage interaction_type target_taxon_external_id
## 1                         NA          preysOn               EOL:328048
## 2                         NA          preysOn               EOL:328716
## 3                         NA          preysOn                 EOL:1666
## 4                         NA          preysOn               EOL:326518
## 5                         NA          preysOn              EOL:4453589
## 6                         NA          preysOn              EOL:2815988
##                   target_taxon_name
## 1                 Nandinia binotata
## 2             Cephalophus monticola
## 3                           Manidae
## 4               Atherurus africanus
## 5 Cercopithecus nictitans nictitans
## 6                         Serpentes
##                                                                                                                                                                                                                                                                                                      target_taxon_path
## 1                                                                                                                                                                                                                              Animalia | Chordata | Mammalia | Carnivora | Nandiniidae | Nandinia | Nandinia binotata
## 2                                                                                                                                                                                                                        Animalia | Chordata | Mammalia | Artiodactyla | Bovidae | Cephalophus | Cephalophus monticola
## 3                                                                                                                                                                                                                                                                 Animalia | Chordata | Mammalia | Pholidota | Manidae
## 4                                                                                                                                                                                                                            Animalia | Chordata | Mammalia | Rodentia | Hystricidae | Atherurus | Atherurus africanus
## 5 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Primates | Haplorrhini | Simiiformes | Cercopithecoidea | Cercopithecidae | Cercopithecinae | Cercopithecini | Cercopithecus | Cercopithecus nictitans | Cercopithecus nictitans nictitans
## 6                                                                                                                                                                                           Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Reptilia | Squamata | Serpentes
##   target_specimen_life_stage latitude longitude study_title
## 1                         NA       NA        NA          NA
## 2                         NA       NA        NA          NA
## 3                         NA       NA        NA          NA
## 4                         NA       NA        NA          NA
## 5                         NA       NA        NA          NA
## 6                         NA       NA        NA          NA

For a complete list of supported interaction types,

get_interaction_types()
##      interaction     source     target
## 1        preysOn   predator       prey
## 2   preyedUponBy       prey   predator
## 3     parasiteOf   parasite       host
## 4    hasParasite       host   parasite
## 5     pollinates pollinator      plant
## 6   pollinatedBy      plant pollinator
## 7     pathogenOf   pathogen       host
## 8    hasPathogen      plant pollinator
## 9     symbiontOf     source     target
## 10 interactsWith     source     target

For data sources in which type of interactions was not specified, the interaction is labeled “interacts_with”.

If you wish to view all interactions instead of specific types (e.g., parasitism and predation instead of just one of the two), the get_interactions_by_taxa() function allows this. In addition, the function provides options to search for interactions between two groups (source and target taxa, see above table) and only find interactions in a certain region.

rattus <- get_interactions_by_taxa(sourcetaxon = "Rattus")
head(rattus)
##   source_taxon_external_id source_taxon_name
## 1               EOL:328447     Rattus rattus
## 2               EOL:328447     Rattus rattus
## 3               EOL:328447     Rattus rattus
## 4               EOL:328447     Rattus rattus
## 5               EOL:328447     Rattus rattus
## 6               EOL:328447     Rattus rattus
##                                                                                                                                                                             source_taxon_path
## 1 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
## 2 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
## 3 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
## 4 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
## 5 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
## 6 Animalia | Bilateria | Deuterostomia | Chordata | Vertebrata | Gnathostomata | Tetrapoda | Mammalia | Theria | Eutheria | Rodentia | Myomorpha | Muridae | Murinae | Rattus | Rattus rattus
##   source_specimen_life_stage interaction_type target_taxon_external_id
## 1                         NA    interactsWith             EOL:13340393
## 2                         NA    interactsWith             EOL:10702710
## 3                         NA    interactsWith              EOL:5004474
## 4                         NA    interactsWith              EOL:4968671
## 5                         NA    interactsWith              EOL:4965412
## 6                         NA    interactsWith              EOL:4963889
##              target_taxon_name
## 1            Mastophorus muris
## 2           Trypanosoma lewisi
## 3           Calodium hepaticum
## 4                  Raillietina
## 5 Nippostrongylus brasiliensis
## 6                     Syphacia
##                                                                                                                  target_taxon_path
## 1                                     Animalia | Nematoda | Secernentea | Spirurida | Spiruridae | Mastophorus | Mastophorus muris
## 2 Cellular organisms | Eukaryota | Euglenozoa | Kinetoplastida | Trypanosomatidae | Trypanosoma | Herpetosoma | Trypanosoma lewisi
## 3                                                                                                               Calodium hepaticum
## 4                                                Animalia | Platyhelminthes | Cestoda | Cyclophyllidea | Davaineidae | Raillietina
## 5                 Animalia | Nematoda | Secernentea | Strongylida | Heligosomidae | Nippostrongylus | Nippostrongylus brasiliensis
## 6                                                            Animalia | Nematoda | Secernentea | Ascaridida | Oxyuridae | Syphacia
##   target_specimen_life_stage latitude longitude study_title
## 1                         NA       NA        NA          NA
## 2                         NA       NA        NA          NA
## 3                         NA       NA        NA          NA
## 4                         NA       NA        NA          NA
## 5                         NA       NA        NA          NA
## 6                         NA       NA        NA          NA

Only a source taxa need be identified, but you can also specify a target taxon and/or geographic boundary (Coordinates must be in decimal degrees (EPSG:4326) and correspond to the west, south, east, and northern boundaries (i.e., min x, min y, max x, max y).

aves_crustacea_northern_hemisphere <- get_interactions_by_taxa( sourcetaxon = "Aves", targettaxon = "Crustacea", bbox=c(-180, 0, 180, 90 ))
head(aves_crustacea_northern_hemisphere)
##   source_taxon_external_id       source_taxon_name
## 1                EOL:18884                 Cepphus
## 2              EOL:1047918      Anas platyrhynchos
## 3              EOL:1049560 Recurvirostra americana
## 4              EOL:1049376  Arenaria melanocephala
## 5              EOL:1048977       Bucephala albeola
## 6              EOL:1048977       Bucephala albeola
##                                                                                           source_taxon_path
## 1                                          Animalia | Chordata | Aves | Charadriiformes | Alcidae | Cepphus
## 2                          Animalia | Chordata | Aves | Anseriformes | Anatidae | Anas | Anas platyrhynchos
## 3 Animalia | Chordata | Aves | Charadriiformes | Recurvirostridae | Recurvirostra | Recurvirostra americana
## 4           Animalia | Chordata | Aves | Charadriiformes | Scolopacidae | Arenaria | Arenaria melanocephala
## 5                      Animalia | Chordata | Aves | Anseriformes | Anatidae | Bucephala | Bucephala albeola
## 6                      Animalia | Chordata | Aves | Anseriformes | Anatidae | Bucephala | Bucephala albeola
##   source_specimen_life_stage interaction_type target_taxon_external_id
## 1                         NA          preysOn              EOL:2625033
## 2                         NA          preysOn              EOL:2620777
## 3                         NA    interactsWith              EOL:2625033
## 4                         NA          preysOn              EOL:2620777
## 5                         NA    interactsWith              EOL:2625033
## 6                         NA          preysOn              EOL:2620777
##   target_taxon_name
## 1          Copepoda
## 2        Gammaridea
## 3          Copepoda
## 4        Gammaridea
## 5          Copepoda
## 6        Gammaridea
##                                                                                                                               target_taxon_path
## 1                                              Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Maxillopoda | Copepoda
## 2 Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Malacostraca | Eumalacostraca | Peracarida | Amphipoda | Gammaridea
## 3                                              Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Maxillopoda | Copepoda
## 4 Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Malacostraca | Eumalacostraca | Peracarida | Amphipoda | Gammaridea
## 5                                              Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Maxillopoda | Copepoda
## 6 Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea | Malacostraca | Eumalacostraca | Peracarida | Amphipoda | Gammaridea
##   target_specimen_life_stage latitude longitude study_title
## 1                         NA       NA        NA          NA
## 2                         NA       NA        NA          NA
## 3                         NA       NA        NA          NA
## 4                         NA       NA        NA          NA
## 5                         NA       NA        NA          NA
## 6                         NA       NA        NA          NA

Find interactions in a geographic areas

Instead of a taxon-specific approach, users may also wish to gather information on all interactions occuring in a specific area. For example, a group developing ecoystem models for the Gulf of Mexico may want to consider all the data from that region. rglobi enables this type of search by allowing users to specify a rectangular bounding box. Coordinates must be in decimal degrees (EPSG:4326) and correspond to the west, south, east, and northern boundaries (i.e., min x, min y, max x, max y).

gulfinteractions <- get_interactions_in_area( bbox=c(-97.0, 17.5, -81, 31))
head(gulfinteractions)
##   source_taxon_external_id        source_taxon_name
## 1                    EOL:1                 Animalia
## 2                 EOL:1905           Actinopterygii
## 3              EOL:2598871                Crustacea
## 4               EOL:208553 Chloroscombrus chrysurus
## 5               EOL:208553 Chloroscombrus chrysurus
## 6               EOL:208553 Chloroscombrus chrysurus
##                                                                                             source_taxon_path
## 1                                                                                                    Animalia
## 2                          Biota | Animalia | Chordata | Vertebrata | Gnathostomata | Pisces | Actinopterygii
## 3                                     Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea
## 4 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
## 5 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
## 6 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
##   source_specimen_life_stage interaction_type target_taxon_external_id
## 1                         NA     preyedUponBy               EOL:208553
## 2                         NA     preyedUponBy               EOL:208553
## 3                         NA     preyedUponBy               EOL:208553
## 4                         NA          preysOn                    EOL:1
## 5                         NA          preysOn                 EOL:1905
## 6                         NA          preysOn              EOL:2598871
##          target_taxon_name
## 1 Chloroscombrus chrysurus
## 2 Chloroscombrus chrysurus
## 3 Chloroscombrus chrysurus
## 4                 Animalia
## 5           Actinopterygii
## 6                Crustacea
##                                                                                             target_taxon_path
## 1 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
## 2 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
## 3 Animalia | Chordata | Actinopterygii | Perciformes | Carangidae | Chloroscombrus | Chloroscombrus chrysurus
## 4                                                                                                    Animalia
## 5                          Biota | Animalia | Chordata | Vertebrata | Gnathostomata | Pisces | Actinopterygii
## 6                                     Animalia | Bilateria | Protostomia | Ecdysozoa | Arthropoda | Crustacea
##   target_specimen_life_stage latitude longitude study_title
## 1                         NA       NA        NA          NA
## 2                         NA       NA        NA          NA
## 3                         NA       NA        NA          NA
## 4                         NA       NA        NA          NA
## 5                         NA       NA        NA          NA
## 6                         NA       NA        NA          NA

To see all locations for which interactions have entered in GloBi,

areas <- get_interaction_areas()
head(areas)
##   Latitude Longitude
## 1 29.34695 -92.98061
## 2 29.03260 -92.28701
## 3 28.03673 -96.11108
## 4 27.62409 -95.77403
## 5 26.33146 -96.03294
## 6 30.25024 -86.13114

You can also restrict this search to a certain area:

areas <- get_interaction_areas (bbox=c(-67.87,12.79,-57.08,23.32))
head(areas)
##      Latitude Longitude
## 1251 18.24829 -66.49989
## 1255 18.33884 -65.82572
## 1268 18.06667 -63.06667
## 1339 13.16667 -59.53333

Custom Queries using Cypher

Currently, GloBI is powered by neo4j, a graph database. Most results created by the R functions provided by rglobi are basically wrappers for commonly used cypher queries. This way, you can still use the library without having to learn Cypher, a graph query language. However, if you feel adventurous, you can execute queries using Cypher only using the function query():

result <- query("START taxon = node:taxons(name='Homo sapiens') MATCH taxon<-[:CLASSIFIED_AS]-predator-[:ATE|PREYS_ON]->prey-[:CLASSIFIED_AS]->preyTaxon RETURN distinct(preyTaxon.name) as `prey.taxon.name` LIMIT 10")
result
##         prey.taxon.name
## 1          Homo sapiens
## 2    Macropus bernardus
## 3             Mysticeti
## 4   Dendrolagus scottae
## 5   Engraulis japonicus
## 6         Sergia lucens
## 7       Martes melampus
## 8   Lophocebus albigena
## 9            Salmonidae
## 10 Moschus chrysogaster

This particular query returns the names of the first ten known prey or diet items of humans (Homo sapiens). More examples of GloBI specific Cypher queries can be found on the GloBI Cypher Wiki.

Pagination

By default, the amount of results are limited. If you'd like to retrieve all results, you can used pagination. For instance, to retrieve parasitic interactions using pagination, you can use:

otherkeys = list("limit"=10, "skip"=0)
first_page_of_ten <- get_interactions_by_type(interactiontype = c("hasParasite"), otherkeys = otherkeys)
otherkeys = list("limit"=10, "skip"=10)
second_page_of_ten <- get_interactions_by_type(interactiontype = c("hasParasite"), otherkeys = otherkeys)

To exhaust all available interactions, you can keep paging results until the size of the page is less than the limit (e.g., nrows(interactions) < limit).

Selecting Taxonomic Schemes

GloBI integrations with various different taxonomies (see Selecting specific taxonomies).

To select a specific preferred taxonomy like the Open Tree of Life reference taxonomy to retrieve up to 10 parasitic interactions, use:

parasitic_interactions <- get_interactions_by_type(interactiontype = c("hasParasite"), otherkeys = list("taxonIdPrefix"="OTT", "limit"=10))

Note that if no taxonomic mapping for the preferred taxonomy is available, another taxonomy will be selected.