title: “BIEN tutorial”


library(ape) #Package for working with phylogenies in R
library(maps) #Useful for making quick maps of occurrences
library(sp) # A package for spatial data

An overview of the package

We try to make this package as easy and intuitive to use as possible, but it is still often easiest to start with our vignette. Particularly useful are the “Function Names” and “Function Directory” sections.


The function names follow a consistent naming strategy, and mostly consist of 3 parts:

  1. The prefix “BIEN_”
  2. The type of data being accessed, e.g. “occurrence_”
  3. How you'll be querying the data. For example, the suffix “state” refers to functions that return data for a specified state.

As a complete example, the function BIEN_occurrence_species returns occurrence records for a given species (or set of species).

Function Families

Currently we have 9 function families in RBIEN. These are sets of functions that access a given type of data.

  1. occurrence records (BIEN_occurrence_...)
  2. range maps (BIEN_ranges_...)
  3. plot data (BIEN_plot_...)
  4. trait data (BIEN_trait_...)
  5. taxonomic information (BIEN_taxonomy_...)
  6. phylogenies (BIEN_phylogeny_...)
  7. stem data (BIEN_stem_...)
  8. species lists (BIEN_list_...)
  9. metadata (BIEN_metadata_...)

We'll walk through each of the function families and take a look at some the options available within each.

Occurrence records

These functions begin with the prefix BIEN_occurrence_... and allow you to query occurrences by either taxonomy or geography. Functions include:

  1. BIEN_occurrence_country Returns all occurrence records within a given country

  2. BIEN_occurrence_state Returns all occurrences records within a given state/province

  3. BIEN_occurrence_county Returns all occurrences records within a given state/province

  4. BIEN_occurrence_family Returns all occurrence records for a specified family

  5. BIEN_occurrence_genus Returns all occurrence records for a specified genus

  6. BIEN_occurrence_species Returns all occurrence records for a specified species

Each of these functions has a number of different arguments that modify your query, either refining your search criteria or returning more data for each record. These arguments include:

  1. cultivated If TRUE, records known to be cultivated will be returned.

  2. only.new.world If TRUE, records returned are limited to those in North and South America, where greater data cleaing and validation has been done.

  1. all.taxonomy If TRUE, the query will return additional taxonomic data, including the uncorrected taxonomic information for those records.

  2. native.status If TRUE, additional information will be returned regarding whether a species is native in a given region.

  3. natives.only If TRUE, the default, information for occurrences flagged as introduced will not be returned.

  4. observation.type If TRUE, the query will return whether each record is from either a plot or a specimen. This may be useful if a user believes one type of information may be more accurate.

  5. political.boundaries If TRUE, the query will return information on which country, state, etc. that an occurrence is found within.

  6. collection.info If TRUE, the quest will return additional information about the collection and identification of that specimen.

Example 1: Occurrence records for a species

Okay, enough reading. Let's get some data.

Let's say we're interested in the species Xanthium strumarium and we'd like some occurrence data. We'll use the function BIEN_occurrence_species to grab the occurrence data.

Xanthium_strumarium <- BIEN_occurrence_species(species = "Xanthium strumarium")

Take a moment and view the dataframe and take a look at the structure

## 'data.frame':    2357 obs. of  10 variables:
##  $ scrubbed_species_binomial  : chr  "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" ...
##  $ latitude                   : num  40.1 38.6 39.2 38.2 38.6 ...
##  $ longitude                  : num  -92.1 -90.2 -91.8 -91.9 -90.3 ...
##  $ date_collected             : Date, format: "1934-10-15" "1894-07-03" ...
##  $ datasource                 : chr  "MO" "MO" "MO" "MO" ...
##  $ dataset                    : chr  "MO" "MO" "MO" "MO" ...
##  $ dataowner                  : chr  "MO" "MO" "MO" "MO" ...
##  $ custodial_institution_codes: chr  "MO" "MO" "MO" "MO" ...
##  $ collection_code            : chr  NA NA NA NA ...
##  $ datasource_id              : num  281 281 281 281 281 281 281 281 281 272 ...
##   scrubbed_species_binomial latitude longitude date_collected datasource
## 1       Xanthium strumarium 40.13075 -92.14917     1934-10-15         MO
## 2       Xanthium strumarium 38.63798 -90.24525     1894-07-03         MO
## 3       Xanthium strumarium 39.21727 -91.84273     1985-09-21         MO
## 4       Xanthium strumarium 38.16665 -91.92466     1934-09-16         MO
## 5       Xanthium strumarium 38.62388 -90.34611     1991-09-01         MO
## 6       Xanthium strumarium 37.82746 -92.20761     1935-10-06         MO
##   dataset dataowner custodial_institution_codes collection_code
## 1      MO        MO                          MO            <NA>
## 2      MO        MO                          MO            <NA>
## 3      MO        MO                          MO            <NA>
## 4      MO        MO                          MO            <NA>
## 5      MO        MO                          MO            <NA>
## 6      MO        MO                          MO            <NA>
##   datasource_id
## 1           281
## 2           281
## 3           281
## 4           281
## 5           281
## 6           281

The default data that is returned consists of the latitude, longitude and date collected, along with a set of attribution data. The meaning of some of these columns is obvious (e.g. latitude, longitide), however others may be less clear. The meanings of these columns and the information within is explained in more detail in our data dictionary, available at http://bien.nceas.ucsb.edu/bien/tools/rbien/data-dictionary/

If we want more information on these occurrences, we just need to change the arguments:

Xanthium_strumarium_full <- BIEN_occurrence_species(species = "Xanthium strumarium",cultivated = T,only.new.world = F,all.taxonomy = T,native.status = T,observation.type = T,political.boundaries = T)

## 'data.frame':    6325 obs. of  34 variables:
##  $ scrubbed_species_binomial   : chr  "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" ...
##  $ verbatim_family             : chr  "Asteraceae" "Asteraceae" "Asteraceae" "Asteraceae" ...
##  $ verbatim_scientific_name    : chr  "Xanthium strumarium L." "Xanthium strumarium L." "Xanthium strumarium L." "Xanthium strumarium L." ...
##  $ family_matched              : chr  "Asteraceae" "Asteraceae" "Asteraceae" "Asteraceae" ...
##  $ name_matched                : chr  "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" ...
##  $ name_matched_author         : chr  "L." "L." "L." "L." ...
##  $ higher_plant_group          : chr  "flowering plants" "flowering plants" "flowering plants" "flowering plants" ...
##  $ taxonomic_status            : chr  "accepted" "accepted" "accepted" "accepted" ...
##  $ scrubbed_family             : chr  "Asteraceae" "Asteraceae" "Asteraceae" "Asteraceae" ...
##  $ scrubbed_author             : chr  "L." "L." "L." "L." ...
##  $ native_status               : chr  "P" NA "P" "P" ...
##  $ native_status_reason        : chr  "Present in one or more checklists for region, status not indicated" NA "Present in one or more checklists for region, status not indicated" "Present in one or more checklists for region, status not indicated" ...
##  $ native_status_sources       : chr  "usda, vascan, tropicos" NA "usda, vascan, tropicos" "usda, vascan, tropicos" ...
##  $ isintroduced                : int  0 NA 0 0 0 NA 0 0 NA 0 ...
##  $ native_status_country       : chr  "N" NA "N" "N" ...
##  $ native_status_state_province: chr  "P" NA "P" "P" ...
##  $ native_status_county_parish : chr  "" NA "" "" ...
##  $ country                     : chr  "United States" "Turkmenistan" "United States" "United States" ...
##  $ state_province              : chr  "Missouri" "Ahal" "Missouri" "Missouri" ...
##  $ county                      : chr  "Knox" NA "Saint Louis" "Audrain" ...
##  $ locality                    : chr  "Between Edina and Knox City prairie" "Eastern Kopetdag, the canyon Schukurbachshi, on clayey slopes." "St. Charles Road waste roadsides" "NW 1/4 NW 1/4 Sec. 27; NW corner of junction of north-south and east-west gravel roads, ca. 4.5 mi NNW of Middl"| __truncated__ ...
##  $ latitude                    : num  40.1 NA 38.6 39.2 38.2 ...
##  $ longitude                   : num  -92.1 NA -90.2 -91.8 -91.9 ...
##  $ date_collected              : Date, format: "1934-10-15" "2004-06-02" ...
##  $ datasource                  : chr  "MO" "MO" "MO" "MO" ...
##  $ dataset                     : chr  "MO" "MO" "MO" "MO" ...
##  $ dataowner                   : chr  "MO" "MO" "MO" "MO" ...
##  $ custodial_institution_codes : chr  "MO" "MO" "MO" "MO" ...
##  $ collection_code             : chr  NA NA NA NA ...
##  $ datasource_id               : num  281 281 281 281 281 281 281 281 281 281 ...
##  $ is_cultivated               : int  0 0 0 0 0 0 0 0 0 0 ...
##  $ is_cultivated_in_region     : int  0 NA 0 0 0 NA 0 0 0 0 ...
##  $ is_new_world                : int  1 0 1 1 1 NA 1 1 1 1 ...
##  $ observation_type            : chr  "specimen" "specimen" "specimen" "specimen" ...

We now have considerably more information.

Let's take a quick look at where those occurrences are.

# Make a quick map to plot our points on

map('world',fill=T , col= "grey", bg="light blue") 

#Plot the points from the full query in red


# Plot the points from the default query in blue


plot of chunk unnamed-chunk-6

From the map, we can see that the points from the default query (in blue) all fall within the New World. The points from the full query (red + blue) additionally include occurrences from the Old World.

Example 2: Occurrence records for a country

Since we may be interested in a particular geographic area, rather than a particular set of species, there are also options to easily extract data by political region as well.

We'll choose a relatively small region, the Bahamas, for our demonstration.

Bahamas <- BIEN_occurrence_country(country =  "Bahamas")

#Let's see how many species we have
## [1] 954
#Nearly 1000 species, not bad.

#Now, let's take a look at where those occurrences are:
map(regions = "Bahamas" ,fill=T , col= "grey", bg="light blue")


plot of chunk unnamed-chunk-7

#Looks like some islands are considerably better sampled than others.

Range maps

These functions begin with the prefix BIEN_ranges_... and return (unsurprisingly) species ranges. Most of these functions work by saving the downloaded ranges to a specified directory in shapefile format, rather than by loading them into the R environment.

Functions include:

  1. BIEN_ranges_species Downloads range maps for given species and save them to a specified directory.

  2. BIEN_ranges_genus Saves range maps for all species within a genus to a specified directory.

  3. BIEN_ranges_load_species This function returns the ranges for a set of species as a SpatialPolygonsDataFrame object.

The range functions have different arguments than we have seen so far, including:

  1. directory This is where the function will be saving the shapefiles you download

  2. matched If TRUE, the function will return a dataframe listing which species ranges were downloaded and which weren't.

  3. match_names_only If TRUE, the function will check whether a map is available for each species without actually downloading it

  4. include.gid If TRUE, the function will append a unique gid number to each range map's filename. This argument is designed to allow forward compatibility when BIEN contains multiple range maps for each species.

Example 3: Range maps and occurrence points

If we have a species we're interested in, and would like to load the range map into the environment, we can use the function BIEN_ranges_load_species. Let's try this for Xanthium strumarium.

Xanthium_strumarium_range <- BIEN_ranges_load_species(species = "Xanthium strumarium")

The range map is now in our global environment as a SpatialPolygonsDataFrame. Let's plot the map and see what it looks like.

#First, let's add a base map so that our range has some context:

map('world',fill=T , col= "grey", bg="light blue",xlim = c(-180,-20),ylim = c(-60,80))

#Now, we can add the range map:

plot of chunk unnamed-chunk-9

Now, let's add those occurrence points from earlier to this map:

map('world',fill=T , col= "grey", bg="light blue",xlim = c(-180,-20),ylim = c(-60,80))

plot of chunk unnamed-chunk-10

Plot data

These functions begin with the prefix “BIENplot” and return ecological plot data. Functions include:

  1. BIEN_plot_list_sampling_protocol Returns the different plot sampling protocols found in the BIEN database.

  2. BIEN_plot_list_datasource Returns the different datasources that are available in the BIEN database.

  1. BIEN_plot_sampling_protocol Downloads data for a specified sampling protocol

  2. BIEN_plot_datasource Downloads data for a specific datasource

  1. BIEN_plot_country

  2. BIEN_plot_state

  3. BIEN_plot_dataset Downloads data for a given dataset (which is nested within a datasource)

  4. BIEN_plot_name Downloads data for a specific plot name (these are nested within a given dataset)

Again we have some of the same arguments available for these queries that we saw for the occurrence functions. We also have the new argument all.metadata, which causes the functions to return more metadata for each plot.

Example 4: Plot data by plot name

Let's take a look at the data for an individual plot.

LUQUILLO <- BIEN_plot_name(plot.name = "LUQUILLO")
##   plot_name subplot elevation_m plot_area_ha
## 1  LUQUILLO       1         300          0.1
## 2  LUQUILLO       1         300          0.1
## 3  LUQUILLO       1         300          0.1
## 4  LUQUILLO       1         300          0.1
## 5  LUQUILLO       1         300          0.1
## 6  LUQUILLO       1         300          0.1
##                       sampling_protocol     recorded_by
## 1 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
## 2 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
## 3 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
## 4 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
## 5 0.1 ha  transect, stems >= 2.5 cm dbh            <NA>
## 6 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
##   scrubbed_species_binomial individual_count latitude longitude
## 1          Cyathea aquilina                1       NA        NA
## 2         Dacryodes excelsa                1  18.1833  -65.8333
## 3           Guarea guidonia                1  18.1833  -65.8333
## 4         Paullinia pinnata                1  18.1833  -65.8333
## 5        Prestoea acuminata                4  18.1833  -65.8333
## 6     Schefflera morototoni                1  18.1833  -65.8333
##   date_collected datasource                 dataset       dataowner
## 1           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
## 2           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
## 3           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
## 4           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
## 5           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
## 6           <NA>    SALVIAS Gentry Transect Dataset James S. MIller
##   custodial_institution_codes collection_code datasource_id
## 1                        <NA>            <NA>            14
## 2                        <NA>            <NA>            14
## 3                        <NA>            <NA>            14
## 4                        <NA>            <NA>            14
## 5                        <NA>            <NA>            14
## 6                        <NA>            <NA>            14

We can see that this is a 0.1 hectare transect where stems >= 2.5 cm diameter at breast height were included. If we'd like more detail, we can use additional arguments:

LUQUILLO_full <- BIEN_plot_name(plot.name = "LUQUILLO",cultivated = T,all.taxonomy = T,native.status = T,political.boundaries = T,all.metadata = T)

The dataframe LUQUILLO_full contains more useful information, including metadata on which taxa were included, which growth forms were included and information on whether species are known to be native or introduced.

Trait data

These functions begin with the prefix BIEN_trait_... and access the BIEN trait database. Note that the spelling of the trait names must be precise, so we recommend using the function BIEN_trait_list first. Traits names are standardized to follow http://www.top-thesaurus.org/ where available. Trait units have been standardized for each trait.

Functions include:

  1. BIEN_trait_list Start with this. It returns a dataframe of the traits available.

  2. BIEN_trait_family Returns a dataframe of all trait data for a given family (or families).

  3. BIEN_trait_genus

  4. BIEN_trait_species

  5. BIEN_trait_trait Downloads all records of a specified trait (or traits).

  6. BIEN_trait_mean Estimates species mean trait values using genus or family level means where species-level data is absent.

  7. BIEN_trait_traitbyfamily Downloads data for a given family (or families) and trait(s).

  8. BIEN_trait_traitbygenus

  9. BIEN_trait_traitbyspecies

Example 5: Accessing trait data

If you're interested in accessing all traits for a taxon, say the genus Salix, just go ahead and use the corresponding function:

Salix_traits<-BIEN_trait_genus(genus = "Salix")

If instead we're interested in a particular trait, the first step is to check if that trait is present and verify the spelling using the function BIEN_trait_list.

##                                             trait_name
## 1                    diameter at breast height (1.3 m)
## 2                          flower pollination syndrome
## 3                                            leaf area
## 4                leaf carbon content per leaf dry mass
## 5        leaf carbon content per leaf nitrogen content
## 6                    leaf dry mass per leaf fresh mass
## 7                  leaf nitrogen content per leaf area
## 8              leaf nitrogen content per leaf dry mass
## 9            leaf phosphorus content per leaf dry mass
## 10              leaf photosynthetic rate per leaf area
## 11          leaf photosynthetic rate per leaf dry mass
## 12     leaf stomatal conductance for H2O per leaf area
## 13                                      leaf thickness
## 14                               plant flowering begin
## 15                            plant flowering duration
## 16                                         seed length
## 17                                           seed mass
## 18                                       stem dry mass
## 19                                   stem wood density
## 20                      whole plant dispersal syndrome
## 21                             whole plant growth form
## 22                   whole plant growth form diversity
## 23                                  whole plant height
## 24 whole plant leaf area per whole plant leaf dry mass
## 25                           whole plant leaf dry mass
## 26                           whole plant sexual system
## 27                    whole plant vegetative phenology
## 28                               whole plant woodiness

If we're interested in leaf area, we see that this is indeed called “leaf area” in the database. Now that we know the proper spelling, we can use the function BIEN_trait_trait to download all observations of that trait.

leaf_area <- BIEN_trait_trait(trait = "leaf area")

Note that the units have been standardized and that there is a full set of attribution data for each trait.

#Taxonomy Data

While there are existing packages that query taxonomic data (e.g. those included in the excellent taxize package), the RBIEN taxonomy functions access the taxonomic information that underlies the BIEN database, ensuring consistency.

  1. BIEN_taxonomy_family Downloads all taxonomic information for a given family.

  2. BIEN_taxonomy_genus

  3. BIEN_taxonomy_species

Example 6: Taxonomic data

Let's say we're interested in the genus Asclepias, and we'd like to get an idea of how many species there are in this genus and what higher taxa it falls within.

Asclepias_taxonomy<-BIEN_taxonomy_genus(genus = "Asclepias")

#We see that the genus Asclepias falls within the family Apocynaceae and the order Gentianales.

#You'll also notice that a given species may appear more than once (due to multiple circumscriptions, some of which may be illegitimate).

#If we'd just like to know all the speciess that aren't illegitimate:
Asclepias_species<-unique(Asclepias_taxonomy$scrubbed_species_binomial[Asclepias_taxonomy$scrubbed_taxonomic_status %in% c("accepted",  "no opinion")])


The BIEN database currently contains 101 phylogenies for new world plants. This includes 100 replicated phylogenies that include a large fraction of New World plant species (“complete phylogenies”) and 1 phylogeny containing only those New World plant species for which molecular data were available (“conservative phylogeny”). Currently, there are only 2 functions available:

  1. BIEN_phylogeny_complete This function will return a specified number of the replicated “complete” phylogenies. Note that each phylogeny is several Mb in size, so downloading many may take a while on slow connections.

  2. BIEN_phylogeny_conservative This function returns the conservative phylogeny.

Arguments: The function BIEN_phylogeny_complete has a few arguments that are worth explaining:

  1. n_phylogenies This is the number of replicated phylogenies that you want to download (between 1 and 100)

  2. seed This function sets the seed for the random number generator before randomly drawing the phylogenies to be downloaded. This is useful for replicating analyses.

  3. replicates This function allows you to specify WHICH of the 100 phylogenies to download, rather than having them selected randomly.

*Example 7: Phylogenies *

Let's say we want to download the conservative phylogeny.

phylo <- BIEN_phylogeny_conservative()

#Let's make sure it looks alright

plot.phylo(x = phylo, show.tip.label =  FALSE)

plot of chunk unnamed-chunk-17

#If we just want to see which species are included

phylo_species <- phylo$tip.label

Stem Data

The BIEN database contains stem data associated with many of the plots. This is typically either diameter at breast height or diameter at ground height. At present, there is only one stem function (although expect more in the future):

  1. BIEN_stem_species This function downloads all of the stem data for a given species (or set of species)
  2. BIEN_stem_genus
  3. BIEN_stem_family
  4. BIEN_stem_datasource This function downloads all of the stem data for a given datasource.


The arguments for this function are the same that we have seen in the occurrence and plot functions.

*Example 8: Stem data *

If we'd like stem data for the species Cupressus arizonica

Cupressus_arizonica_stems<-BIEN_stem_species("Cupressus arizonica")

Species lists

These functions begin with the prefix BIEN_list_ and allow you to quickly get a list of all the species in a geographic unit. Functions include:

  1. BIEN_list_country Returns all species found within a country.

  2. BIEN_list_state Returns all species found within a given state/province or other 2nd level political division.

  3. BIEN_list_county Returns all species found within a given county/parish/or other 3rd level political division.

Some of the same arguments we saw in the occurrence functions appear here as well, including “cultivated” and “only.new.world”.

Example 9: Species list for a country

Let's return to our previous example. What if we just need a list of the species in the Bahamas, rather than the specific details of each occurrence record? We can instead use the function BIEN_list_country to download a list of species, which should be much faster than using BIEN_occurrence_country to get a species list.

Bahamas_species_list<-BIEN_list_country(country = "Bahamas")

#Notice that this time, we have 998 species, whereas previously we saw that there were 999 unique species.  What happened?  The list functions ignore NA values for species names, but R does not.  R counted NA values as a unique species name, giving one extra unique value.

If we wanted to retrieve the results for multiple countries at once, that is simple as well. We just need to supply a vector of countries.

country_vector<-c("Haiti","Dominican Republic")
Haiti_DR <- BIEN_list_country(country = country_vector)

We can also use political division codes (from geonames.org) instead of writing out the full country names.

#To see all of the political division names, and associated codes, we can use this function:


#Let's take a look at what the dataframe contains:

##         country country.code state_province state_province_ascii
## 1 Aland Islands           AX           <NA>                 <NA>
## 2    Azerbaijan           AZ           <NA>                 <NA>
## 3    Azerbaijan           AZ           <NA>                 <NA>
## 4       Burundi           BI           <NA>                 <NA>
## 5       Burundi           BI           <NA>                 <NA>
## 6       Burundi           BI           <NA>                 <NA>
##   state.code       county_parish county_parish_ascii county.code
## 1         01   Landskapet Ãland    Landskapet Aland      830602
## 2         00   MirbǝÅir Rayonu     Mirbasir Rayonu      585509
## 3         00      Shaumyan Rayon      Shaumyan Rayon      585038
## 4         02 Commune of Buterere Commune of Buterere     7670922
## 5         02  Commune of Buyenzi  Commune of Buyenzi     8335225
## 6         02  Commune of Gihanga  Commune of Gihanga     8303259
#In addition to the standardized country, state (state_province_ascii) and county (county_parish_ascii) names, we have the associated codes that can be used in BIEN functions.
#Note that 'state' refers to any primary political division (e.g. province), and 'county' refers to any secondary political division (e.g. parish).

#Looking at the political_names dataframe, we see that the Dominican Republic has country code "DO", and Haiti has country code "HT"

Haiti_DR_from_codes <- BIEN_list_country(country.code = c("HT","DO"))


The BIEN metadata functions start with the prefix BIEN_metadata_... and provide useful metadata for the BIEN database.

  1. BIEN_metadata_database_version Returns the current version number of the BIEN database and the release date.

  2. BIEN_metadata_match_data Rudimentary function to check for changed records between old and current queries.

  3. BIEN_metadata_citation Function to generate bibtex citations for use in reference managers.

  4. BIEN_metadata_list_political_names Returns a dataframe containing political division names and associate codes.

*Example 10: Metadata *

To check what the current version of the BIEN database is (which we recommend reporting when using BIEN data):

##   db_version db_release_date
## 1      3.4.5      2017-05-18

** Example 11: Citations**

One of the more innovative features of the BIEN package is that it will generate custom attribution data for you based on what data you downloaded through the package.

Let's say we're interested in Selaginella selaginoides, and we'd like to download some occurrence data:

Selaginella_selaginoides_occurrences<-BIEN_occurrence_species("Selaginella selaginoides",only.new.world = F)

If we plan on using those data in a publication ,we'll need proper attribution. We can use BIEN_metadata_citation to do this for us:

citation_info<-BIEN_metadata_citation(dataframe = Selaginella_selaginoides_occurrences)

citation_info is a list that contains 3 elements: 1. A bit of general information on how to use the list. 2. A set of bibtex formatted references. 3. Acknowledgement text.

To make things even easier on ourselves, we can use some of the additional functionality of the BIEN_metadata_citation function:

temp_dir <- file.path(tempdir(), "BIEN_temp") #Set a temporary working directory

citation_info<-BIEN_metadata_citation(dataframe = Selaginella_selaginoides_occurrences,
                                     bibtex_file = file.path(temp_dir,"selaginella_selaginoides.bib"),

Now, we have a bibtex file, selaginella_selaginoides.bib, that can be loaded into a reference manages (e.g. Endnote, Paperpile, etc.), and a text file, selaginella_selaginoides.txt, containing text that can be pasted into the acknowledgements section of a publication.

What if we also have some trait data? No problem there, the code handles that as well:

#First, let's get some trait data:
selaginella_selaginoides_traits<-BIEN_trait_species(species = "Selaginella selaginoides")

#Now, we just need to modify our previous bit of code to include the trait data as well:

temp_dir <- file.path(tempdir(), "BIEN_temp")

citation_info<-BIEN_metadata_citation(dataframe = Selaginella_selaginoides_occurrences,
                                      trait.dataframe = selaginella_selaginoides_traits,
                                      bibtex_file = file.path(temp_dir,"selaginella_selaginoides.bib"),

The updated citation information will now contain references for both trait and occurrence records.

Combining Queries

*Example 11: Putting it all together * Coming soon!