title: “BIEN tutorial”

Setup

library(BIEN)
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.

vignette("BIEN")

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

str(Xanthium_strumarium)
## 'data.frame':    2935 obs. of  10 variables:
##  $ scrubbed_species_binomial  : chr  "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" ...
##  $ latitude                   : num  NA 39.4 44.7 40.9 41.1 ...
##  $ longitude                  : num  NA -84.6 -93.1 -88.6 -85.5 ...
##  $ date_collected             : Date, format: NA NA ...
##  $ datasource                 : chr  "GBIF" "GBIF" "GBIF" "GBIF" ...
##  $ dataset                    : chr  "UCJEPS" "USDA NRCS" "USDA NRCS" "USDA NRCS" ...
##  $ dataowner                  : chr  "UCJEPS" "USDA NRCS" "USDA NRCS" "USDA NRCS" ...
##  $ custodial_institution_codes: chr  "UCJEPS" "USDA NRCS" "USDA NRCS" "USDA NRCS" ...
##  $ collection_code            : chr  "JEPS" "USDA Plants" "USDA Plants" "USDA Plants" ...
##  $ datasource_id              : num  1021 102 102 102 102 ...
head(Xanthium_strumarium)
##   scrubbed_species_binomial latitude longitude date_collected datasource
## 1       Xanthium strumarium       NA        NA           <NA>       GBIF
## 2       Xanthium strumarium 39.43840 -84.57740           <NA>       GBIF
## 3       Xanthium strumarium 44.68480 -93.06482           <NA>       GBIF
## 4       Xanthium strumarium 40.88810 -88.55674           <NA>       GBIF
## 5       Xanthium strumarium 41.13542 -85.50394           <NA>       GBIF
## 6       Xanthium strumarium       NA        NA           <NA>       GBIF
##     dataset dataowner custodial_institution_codes collection_code
## 1    UCJEPS    UCJEPS                      UCJEPS            JEPS
## 2 USDA NRCS USDA NRCS                   USDA NRCS     USDA Plants
## 3 USDA NRCS USDA NRCS                   USDA NRCS     USDA Plants
## 4 USDA NRCS USDA NRCS                   USDA NRCS     USDA Plants
## 5 USDA NRCS USDA NRCS                   USDA NRCS     USDA Plants
## 6    UCJEPS    UCJEPS                      UCJEPS            JEPS
##   datasource_id
## 1          1021
## 2           102
## 3           102
## 4           102
## 5           102
## 6          1021

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)

str(Xanthium_strumarium_full)
## 'data.frame':    7719 obs. of  34 variables:
##  $ scrubbed_species_binomial   : chr  "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" "Xanthium strumarium" ...
##  $ verbatim_family             : chr  NA "Asteraceae" "asteraceae" NA ...
##  $ verbatim_scientific_name    : chr  "Xanthium strumarium" "Xanthium strumarium" "xanthium strumarium" "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" ...
##  $ scrubbed_taxonomic_status   : chr  "Accepted" "Accepted" "Accepted" "Accepted" ...
##  $ scrubbed_family             : chr  "Asteraceae" "Asteraceae" "Asteraceae" "Asteraceae" ...
##  $ scrubbed_author             : chr  "L." "L." "L." "L." ...
##  $ native_status               : chr  "UNK" "P" NA "UNK" ...
##  $ native_status_reason        : chr  "Status unknown, no checklists for region of observation" "Present in one or more checklists for region, status not indicated" NA "Status unknown, no checklists for region of observation" ...
##  $ native_status_sources       : chr  NA "usda" NA NA ...
##  $ is_introduced               : int  NA 0 NA NA 0 NA 0 NA NA NA ...
##  $ native_status_country       : chr  NA "P" NA NA ...
##  $ native_status_state_province: chr  NA "P" NA NA ...
##  $ native_status_county_parish : chr  NA NA NA NA ...
##  $ country                     : chr  "Sweden" "United States" NA "Austria" ...
##  $ state_province              : chr  NA "California" NA NA ...
##  $ county                      : chr  NA "San Diego" NA NA ...
##  $ locality                    : chr  "Kalmar, Fredriksskans" "San Diego; San Felipe Creek; sandy wash; San Felipe Valley, wash of San Felipe Creek" NA "sterreich, Burgenland, Neusiedler See, Seewinkel, knapp S Podersdorf-Ortsende" ...
##  $ latitude                    : num  56.7 NA NA NA 39.4 ...
##  $ longitude                   : num  16.4 NA NA NA -84.6 ...
##  $ date_collected              : Date, format: "1914-01-01" NA ...
##  $ datasource                  : chr  "GBIF" "GBIF" "GBIF" "GBIF" ...
##  $ dataset                     : chr  "OHN" "UCJEPS" "MNHN" "W" ...
##  $ dataowner                   : chr  "OHN" "UCJEPS" "MNHN" "W" ...
##  $ custodial_institution_codes : chr  "OHN" "UCJEPS" "MNHN" "W" ...
##  $ collection_code             : chr  "OHN" "JEPS" "p" "Herbarium W" ...
##  $ datasource_id               : num  209 1021 1008 669 102 ...
##  $ is_cultivated_observation   : int  0 NA NA NA 0 NA 0 NA NA 0 ...
##  $ is_cultivated_in_region     : int  0 0 NA 0 0 NA 0 NA NA 0 ...
##  $ is_new_world                : int  0 1 NA 0 1 NA 1 NA NA 0 ...
##  $ 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

points(cbind(Xanthium_strumarium_full$longitude,Xanthium_strumarium_full$latitude),col="red",pch=20,cex=1) 

# Plot the points from the default query in blue

points(cbind(Xanthium_strumarium$longitude,Xanthium_strumarium$latitude),col="blue",pch=20,cex=1) 

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
length(unique(Bahamas$scrubbed_species_binomial))
## [1] 948
#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")

points(cbind(Bahamas$longitude,Bahamas$latitude),col="blue",pch=20,cex=1) 

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(Xanthium_strumarium_range,col="green",add=T)

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(Xanthium_strumarium_range,col="green",add=T)
points(cbind(Xanthium_strumarium$longitude,Xanthium_strumarium$latitude),col="blue",pch=20,cex=1)

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")
head(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            <NA>
## 5 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
## 6 0.1 ha  transect, stems >= 2.5 cm dbh Alwyn H. Gentry
##   scrubbed_species_binomial individual_count latitude longitude
## 1         Dacryodes excelsa                1  18.1833  -65.8333
## 2           Guarea guidonia                1  18.1833  -65.8333
## 3         Paullinia pinnata                1  18.1833  -65.8333
## 4        Prestoea acuminata                4  18.1833  -65.8333
## 5     Schefflera morototoni                1  18.1833  -65.8333
## 6        Sloanea berteriana                5  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.

BIEN_trait_list()
##                                                                                    trait_name
## 1                                                                         aboveground biomass
## 2                                                                     Aboveground stem length
## 3                                                                           acoustic velocity
## 4                                                                        active growth period
## 5                                                                                        Amax
## 6                                                                               annual growth
## 7                                                        Annual relative basal area increment
## 8                                                                        annual transpiration
## 9                                                   annual transpiration per needle unit area
## 10                                                                              anther length
## 11                                                                               anther width
## 12                                                                             bark thickness
## 13                                                                        basal stem diameter
## 14                                                                        bee visitation rate
## 15                                                         Belowground:Aboveground mass ratio
## 16                                                                       Belowground dry mass
## 17                                                                          bending stiffness
## 18                                                                                    biomass
## 19                                                                            biomass density
## 20                                                                               branch count
## 21                                                                             breaking force
## 22                                                                    bundle sheath cell size
## 23                                                                               calyx length
## 24                                                                    calyx midpoint diameter
## 25                                                                                canopy area
## 26                                                                               canopy cover
## 27                                                                              Canopy Height
## 28                                                                            canopy openness
## 29                                                                        Canopy trasmittance
## 30                                                                               capsule mass
## 31                                                                        capsule seed weight
## 32                                                                              catkin number
## 33                                                                            cell population
## 34                                                                       cell radial diameter
## 35                                                                    cell tangental diameter
## 36                                                                              Cellulose 13C
## 37                                                                            Cellulose Cmass
## 38                                                                        cell wall thickness
## 39                                                                change in stem circumfrence
## 40                                                                        chlorophyll content
## 41                                                                          chlorophyll level
## 42                                                        circumfrence at breast height (CBH)
## 43                                                                               cluster size
## 44                                                  CO2 net exchange rate on area basis (NPa)
## 45                                            CO2 net exchange rate on dry weight basis (NPG)
## 46                                      CO2 net exchange rate on individual shoot basis (NPi)
## 47                                                                          condensed tannins
## 48                                                                              cone dry mass
## 49                                                                                core length
## 50                                                                           corolla diameter
## 51                                                  corolla diameter at the base of the calyx
## 52                                                     corolla diameter at the mouth openness
## 53                                                                             corolla length
## 54                                                                      corolla limb diameter
## 55                                                                        corolla tube length
## 56                                                                             cotton biomass
## 57                                                                                  C:P ratio
## 58                                                                       cross sectional area
## 59                                                                  cross sectional stem area
## 60                                                                                 crown area
## 61                                                                             crown diameter
## 62                                                                      crown projection area
## 63                                                                               crown radius
## 64                                                                     crown vector direction
## 65                                                                        crown vector length
## 66                                                                               crown volume
## 67                                                                          crystallite width
## 68                                                                                       d13C
## 69                                                                                       d15N
## 70                                                                             Daily sap flow
## 71                                                                        Daily transpiration
## 72                                                                      Dark respiration rate
## 73                                                                       DBH annual increment
## 74                                                                         DBH (without bark)
## 75                                                                    developed seeds in cone
## 76                                                        developed seeds with embryo in cone
## 77                                                                 diagonal length of a petal
## 78                                                          diameter at breast height (1.3 m)
## 79                                                                              diaspore area
## 80                                                                              diaspore mass
## 81                                                                   diaspore rate of descent
## 82  distance from center of mesophyll chlorenchyma cells to center of nearest vascular bundle
## 83                                       distance from center of vascular bundle to epidermis
## 84                  distance from center of vascular bundle to nearest intercellular airspace
## 85                                                                              dry leaf mass
## 86                                                                                   dry mass
## 87                                                                                    ECM 13C
## 88                                                                                    ECM 15N
## 89                                                                                  ECM Cmass
## 90                                                                                  ECM Nmass
## 91                                                                                embryo mass
## 92                                                              Estimated aboveground biomass
## 93                                                                             Feret-diameter
## 94                                                                           fibre courseness
## 95                                                                         floral tube length
## 96                                                                               flower color
## 97                                                                            flower diameter
## 98                                                                            flower dry mass
## 99                                                                              flower height
## 100                                                                            flowering time
## 101                                                               flower pollination syndrome
## 102                                                                         flower tube depth
## 103                                                                       fly visitation rate
## 104                                                                      follicles per flower
## 105                                                                          Frond narrowness
## 106                                                                               fruit color
## 107                                                                               fruit count
## 108                                                                         fruiting duration
## 109                                                                        fruiting intensity
## 110                                                                            fruiting month
## 111                                                                              fruit length
## 112                                                                                fruit type
## 113                                                                               fruit width
## 114                                                                     fuel moisture content
## 115                                                             gas exchange rate in the dark
## 116                                                            gas exchange rate in the light
## 117                                                                          Germination time
## 118                                                                                 greenness
## 119                                                                     growing season length
## 120                                                                              Growing time
## 121                                                              Height of first major branch
## 122                                                            height of living stump sprouts
## 123                                                                      height to crown base
## 124                                                                    height to first branch
## 125                                                                                 herkogamy
## 126                                                                      inflorescence length
## 127                                                                            initial height
## 128                                                                      inner bark thickness
## 129                                                        inner segment cross sectional area
## 130                                                                    inner segment dry mass
## 131                                                                  inner segment fresh mass
## 132                                                                inner segment fresh volume
## 133                                                                      inner segment length
## 134                                                       inner segment wood specific gravity
## 135                                                        instantaneous water use efficiency
## 136                                                                          Internode Length
## 137                         interveinal distance between centers of adjacent vascular bundles
## 138                                                            intrinsic water-use efficiency
## 139                                                                       Lateral Root Length
## 140                                                                                  Leaf 13C
## 141                                                                                  Leaf 15N
## 142                                                                                  Leaf 18O
## 143                                                                  leaf acid detergen fiber
## 144                                                                              Leaf Al mass
## 145                                                                    Leaf angle inclination
## 146                                                                                 leaf area
## 147                                                                 Leaf area per 5-20 leaves
## 148                                                               leaf area per leaf dry mass
## 149                                                                 leaf area per leaf volume
## 150                                                              leaf area:sapwood area ratio
## 151                                                                               Leaf B mass
## 152                                                                              leaf Ca mass
## 153                                                                              Leaf Ca mass
## 154                                                     leaf carbon content per leaf dry mass
## 155                                             leaf carbon content per leaf nitrogen content
## 156                                                                              Leaf Cd mass
## 157                                                  leaf cellulose content per leaf dry mass
## 158                                                                          Leaf Chlorophyll
## 159                                                                          leaf circularity
## 160                                                                         leaf compoundness
## 161                                                                        leaf crude protein
## 162                                                                              Leaf Cu mass
## 163                                                                              leaf density
## 164                                                                             leaf dry mass
## 165                                                               leaf dry mass of 1-8 leaves
## 166                                                             Leaf dry mass per 5-20 leaves
## 167                                                         leaf dry mass per leaf dry volume
## 168                                                         leaf dry mass per leaf fresh mass
## 169                                                                      Leaf elongation rate
## 170                                                                       Leaf emergence rate
## 171                                                                              Leaf Fe mass
## 172                                                                       leaf flame duration
## 173                                                                           leaf fresh mass
## 174     leaf fresh mass minus leaf dry mass per leaf water saturated mass minus leaf dry mass
## 175                                                     leaf fresh mass per leaf fresh volume
## 176                                                                  leaf fresh water content
## 177                                              leaf hemicellulose content per leaf dry mass
## 178                                                                        leaf ignition time
## 179                                                                               Leaf K mass
## 180                                                                       leaf lamina density
## 181                                               leaf lamina dry mass per leaf lamina volume
## 182                                                            Leaf lamina fracture toughness
## 183                                                    Leaf lamina fracture toughness (light)
## 184                                                    Leaf lamina fracture toughness (shade)
## 185                                                                     leaf lamina thickness
## 186                                                             Leaf lamina thickness (light)
## 187                                                             Leaf lamina thickness (shade)
## 188                                                                               leaf length
## 189                                                              leaf length:leaf width ratio
## 190                                                                            leaf life span
## 191                                                                               leaf lignin
## 192                                                     leaf lignin content per leaf dry mass
## 193                                                                                 Leaf Mass
## 194                                                                           Leaf Mass Ratio
## 195                                                                              Leaf Mg mass
## 196                                                                     leaf midrib thickness
## 197                                                                              leaf Mn mass
## 198                                                                              Leaf Mn mass
## 199                                                                      Leaf Molybdenum mass
## 200                                                                              Leaf Na mass
## 201                                                               leaf natural detergen fiber
## 202                                                       leaf nitrogen content per leaf area
## 203                                                   leaf nitrogen content per leaf dry mass
## 204                                                                            Leaf N:P ratio
## 205                                                                                leaf Parea
## 206                                                                            leaf perimeter
## 207                                                     leaf phosphorus content per leaf area
## 208                                                 leaf phosphorus content per leaf dry mass
## 209                                                    leaf photosynthetic rate per leaf area
## 210                                                leaf photosynthetic rate per leaf dry mass
## 211                                                                              Leaf Pi mass
## 212                                                                                leaf Pmass
## 213                                                                              Leaf Po mass
## 214                                                                          leaf punch force
## 215                                                                 leaf relative growth rate
## 216                                                                                leaf shape
## 217                                                                               Leaf S mass
## 218                                                                     leaf smolder duration
## 219                                                                           leaf:stem ratio
## 220                                           leaf stomatal conductance for H2O per leaf area
## 221                                                   leaf stomatal conductance per leaf area
## 222                                                                          Leaf tannin mass
## 223                                                                     leaf tensile strength
## 224                                                                     Leaf Tensile Strength
## 225                                                                            leaf thickness
## 226                                                                       leaf tissue density
## 227                                                                       Leaf tissue density
## 228                                                                            leaf toughness
## 229                                                                            Leaf toughness
## 230                                                                            Leaf Toughness
## 231                                                              Leaf vein fracture toughness
## 232                                                      Leaf vein fracture toughness (light)
## 233                                                      Leaf vein fracture toughness (shade)
## 234                                                                               leaf volume
## 235                                                                                leaf width
## 236                                                                              Leaf Zn mass
## 237                                                                          leaves per plant
## 238                                                             length of the largest stamens
## 239                                                            length of the smallest stamens
## 240                                                                  light compensation point
## 241                                    light saturated leaf photosynthetic rate per leaf area
## 242                                                                                Litter 13C
## 243                                                                                Litter 15N
## 244                                                                                  Litter C
## 245                                                                              litter Cmass
## 246                                                                              Litter Cmass
## 247                                                                          Litter C:N ratio
## 248                                                                              litter Nmass
## 249                                                                              Litter Nmass
## 250                                                                          Litter N:P ratio
## 251                                                                              Litter Pmass
## 252                                                                            Litter Po mass
## 253                                                             longest whole plant longevity
## 254                                                                          main root length
## 255                                                                 male inflorescence length
## 256                                                                             maturity time
## 257                                                           Maximum electron transport rate
## 258                                                                      maximum fruit length
## 259                                                                       maximum fruit width
## 260                                                                       maximum leaf length
## 261                                                                        maximum leaf width
## 262                                                             Maximum rate of carboxylation
## 263                                                           maximum whole plant canopy area
## 264                                                                maximum whole plant height
## 265                                                             maximum whole plant longevity
## 266                                                          maximum width of enlarging xylem
## 267                                                                          mean nodule mass
## 268                                                                     Mesophyll conductance
## 269                                                                         microfibril angle
## 270                                                       middle segment cross sectional area
## 271                                                                   middle segment dry mass
## 272                                                                 middle segment fresh mass
## 273                                                               middle segment fresh volume
## 274                                                                     middle segment length
## 275                                                      middle segment wood specific gravity
## 276                                                                      minimum fruit length
## 277                                                                       minimum fruit width
## 278                                                                       minimum leaf length
## 279                                                                        minimum leaf width
## 280                                             minimum length of whole plant juvenile period
## 281                                                                minimum whole plant height
## 282                                                                     modulus of elasticity
## 283                                                                          moisture content
## 284                                                                                Needle 13C
## 285                                                                                Needle 15N
## 286                                                                               needle area
## 287                                                                              Needle Nmass
## 288                                                                 Net CO2 assimilation rate
## 289                                                                                Nmass leaf
## 290                                                                                Nmass root
## 291                                                                               Node amount
## 292                                                                            Nodes per gram
## 293                                                                               nodule mass
## 294                                                                                 N:P ratio
## 295                                                                        number of branches
## 296                                                                     number of empty seeds
## 297                                                                    number of filled seeds
## 298                                                                         number of flowers
## 299                                                          number of flowers on main branch
## 300                                                                          number of fruits
## 301                                                                number of fruits per plant
## 302                                                                  number of inflorescences
## 303                                                                          number of leaves
## 304                                                             number of leaves per seedling
## 305                                                            number of living stump sprouts
## 306                                                                           number of nodes
## 307                                                                         number of nodules
## 308                                                                        number of rosettes
## 309                                                                 number of secondary stems
## 310                                                                           number of seeds
## 311                                                               number of seeds per capsule
## 312                                                                 number of seeds per fruit
## 313                                                                 number of seeds per plant
## 314                                                                           number of stems
## 315                                                                         number of stolons
## 316                                                                           number of teeth
## 317                                                                         number of tillers
## 318                                                                      outer bark thickness
## 319                                                                outer cross sectional area
## 320                                                                    outer segment dry mass
## 321                                                                  outer segment fresh mass
## 322                                                                outer segment fresh volume
## 323                                                                      outer segment length
## 324                                                       outer segment wood specific gravity
## 325                                                                      palisade cell length
## 326                                                                palisade cell SA:vol ratio
## 327                                                                        palisade cell size
## 328                                                                       palisade cell width
## 329                                                                        palisade thickness
## 330                                                                            Peak flowering
## 331                                                                             peak sap flow
## 332                                                                        Peak transpiration
## 333                                                               Perimeter:Leaf length ratio
## 334                                                                              petal length
## 335                                                                               petal width
## 336                                                                          Petiole dry mass
## 337                                                                Petiole dry matter content
## 338                                                                        Petiole fresh mass
## 339                                                                            petiole length
## 340                                                                             petiole width
## 341                                                                   phenolics concentration
## 342                                                                               phloem path
## 343                                                                             pistil length
## 344                                                                              pistil width
## 345                                                                               plant cover
## 346                                                                     plant flowering begin
## 347                                                      Plant flowering begin trait (Julien)
## 348                                                                  plant flowering duration
## 349                                                                   plant fruiting duration
## 350                                                                              Plant height
## 351                                                                          Plant narrowness
## 352                                                                              plant volume
## 353                                                                           pods per branch
## 354                                                                            pods per plant
## 355                                                                                pollinator
## 356                                                                pollinator visitation rate
## 357                                                  Predicted freezing vulnerability at -15C
## 358                                                                                     Rarea
## 359                                                              Relative biomass growth rate
## 360                                                                Relative growth daily rate
## 361                                                                      reproductive biomass
## 362                                                                    resistance to drilling
## 363                                                                             Ring porosity
## 364                                                                                ring width
## 365                                                                                     Rmass
## 366                                                                                Root Angle
## 367                                                                              root Ca mass
## 368                                                                              Root Ca mass
## 369                                                                                Root Cmass
## 370                                                                            Root C:N Ratio
## 371                                                                             root diameter
## 372                                                                             root dry mass
## 373                                                                             Root dry mass
## 374                                                                                root Kmass
## 375                                                                                Root Kmass
## 376                                                                               root length
## 377                                                                               Root length
## 378                                                             root length per root dry mass
## 379                                                                                 Root Mass
## 380                                                                        root mass fraction
## 381                                                                              root Mg mass
## 382                                                                              Root Mg mass
## 383                                                                                root Nmass
## 384                                                                                Root Nmass
## 385                                                                                root Pmass
## 386                                                                                Root Pmass
## 387                                                                          root:shoot ratio
## 388                                                                         root surface area
## 389                                                                     root tensile strength
## 390                                                                       root tissue density
## 391                                                                       Root Tissue Density
## 392                                            root total non-structural carbohydrate content
## 393                                                                               root volume
## 394                                                    sap flow under high evaporative demand
## 395                                                     sap flow under low evaporative demand
## 396                                                                              sapwood area
## 397                                                                             sapwood depth
## 398                                                            sapwood relative water content
## 399                                                                   sapwood water potential
## 400                                                                              seed density
## 401                                                                       seed dispersal mode
## 402                                                               Seed germination proportion
## 403                                                                               seed height
## 404                                                                               seed length
## 405                                                      Seedling Absolute Height Growth Rate
## 406                                                                   seedling basal diameter
## 407                                                                            seedling Cmass
## 408                                                                           seedling height
## 409                                                                     seedling leaf biomass
## 410                                                                            seedling Nmass
## 411                                                                     seedling root biomass
## 412                                                                     seedling stem biomass
## 413                                                                    seedling stem diameter
## 414                                                                      seedling stem height
## 415                                                                    seedling total biomass
## 416                                                                                 seed mass
## 417                                                                     seed number per plant
## 418                                                                         seeds per capsule
## 419                                                                          seeds per catkin
## 420                                                                            seed thickness
## 421                                                                            seed toughness
## 422                                                                               seed volume
## 423                                                                                seed width
## 424                                                                              sepal length
## 425                                                                               sepal width
## 426                                                                             shoot biomass
## 427                                                                             shoot density
## 428                                                                            shoot dry mass
## 429                                                                              Shoot Height
## 430                                                                                Shoot Mass
## 431                                           shoot total non-structural carbohydrate content
## 432                                                                       Shoot transpiration
## 433                                                                        shoot weight ratio
## 434                                                                          Single leaf area
## 435                                                                          Single Leaf Area
## 436                                                                    specific fibre surface
## 437                                                                       specific peak force
## 438                                                                        Specific Root Area
## 439                                                               specific root tip abundance
## 440                                                                   specific seed toughness
## 441                                                                     specific stem density
## 442                                                                           sprout dry mass
## 443                                                                             sprout length
## 444                                                                                  Stem 18O
## 445                                                                           stem basal area
## 446                                                                  stem basal area per area
## 447                                                                              stem Ca mass
## 448                                                                              Stem Ca mass
## 449                                                                         stem circumfrence
## 450                                                                              stem density
## 451                                                                             stem diameter
## 452                                                                             stem dry mass
## 453                                                                   stem dry matter content
## 454                                                                               stem height
## 455                                                                                stem Kmass
## 456                                                                   Stem:Leaf Biomass Ratio
## 457                                                                              stem Mg mass
## 458                                                                                Stem Nmass
## 459                                                                                Stem Pmass
## 460                                                                 stem relative growth rate
## 461                                                                         stem straightness
## 462                                                                               stem volume
## 463                                                                        Stem water content
## 464                                           stem wood carbon content per stem wood dry mass
## 465                                                                         stem wood density
## 466                                                                             stigma length
## 467                                                                              stigma width
## 468                                                                  Stomatal conductance CO2
## 469                                                                          stomatal density
## 470                                                                          Stomatal density
## 471                                                                            stomata length
## 472                                                                            stomatal index
## 473                                                                      stump basal diameter
## 474                                                                              style length
## 475                                                                      style midpoint width
## 476                                                                             Survival rate
## 477                                                                           syconium height
## 478                                                                           syconium volume
## 479                                                                            syconium width
## 480                                                                      tannin concentration
## 481                                                                             total biomass
## 482                                                                            total dry mass
## 483                                                                          total fresh mass
## 484                                                             total leaf area of 1-8 leaves
## 485                                                                         total nodule mass
## 486                                                                           total phenolics
## 487                                                                             transpiration
## 488                                                                      transversal porosity
## 489                                                                           tree basal area
## 490                                                                     Tree crown exposition
## 491                                                                               tree height
## 492                                                                         trichrome density
## 493                                                                              trunk height
## 494                                                                        vegetative biomass
## 495                                                                 vein length per unit area
## 496                                                                         vessel lumen area
## 497                                                                             vessel number
## 498                                                                   water storage cell size
## 499                                                                      water use efficiency
## 500                                                          whole plant aboveground dry mass
## 501                                                        whole plant aboveground fresh mass
## 502                                                        whole plant belowground fresh mass
## 503                                                                   whole plant canopy area
## 504                                                                whole plant crown dry mass
## 505                                                            whole plant dispersal syndrome
## 506                                                                    whole plant fresh mass
## 507                                                                   whole plant growth form
## 508                                                         whole plant growth form diversity
## 509                                                                        whole plant height
## 510                                                                     whole plant leaf area
## 511                                            whole plant leaf area per whole plant dry mass
## 512                                                               whole plant leaf fresh mass
## 513                                                               whole plant longevity range
## 514                                                whole plant primary juvenile period length
## 515                                                         whole plant reproductive lifespan
## 516                                                                 whole plant root dry mass
## 517                                                               whole plant root fresh mass
## 518                                                                 whole plant sexual system
## 519                                                                 whole plant stem dry mass
## 520                                                               whole plant stem fresh mass
## 521                                                          whole plant vegetative phenology
## 522                                                                     whole plant woodiness
## 523                                                                                     width
## 524                                                                                  Wood 15N
## 525                                                                  wood acid detergen fiber
## 526                                                                              wood Ca mass
## 527                                                                        wood crude protein
## 528                                                                              wood density
## 529                                                                               wood lignin
## 530                                                                              wood Mn mass
## 531                                                              wood neutral detergent fiber
## 532                                                                                wood Nmass
## 533                                                                                Wood Nmass
## 534                                                                                wood Pmass
## 535                                                                            wood stiffness
## 536                                                                     xylem vessel diameter
## 537                                                                                      <NA>

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")])

Phylogenies

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.

Arguments:

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:

political_names<-BIEN_metadata_list_political_names()

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

head(political_names)
##                  country country_iso                   state_province
## 1            South Sudan          SS                             <NA>
## 2              Argentina          AR Ciudad Autónoma de Buenos Aires
## 3                Austria          AT                  Oberösterreich
## 4 Bosnia and Herzegovina          BA                 Republika Srpska
## 5                 Brazil          BR                           Goiás
## 6                 Brazil          BR                           Goiás
##              state_province_ascii state_code county_parish
## 1                            <NA>         01    Yei County
## 2 Ciudad Autonoma de Buenos Aires         07     Comuna 11
## 3                 Oberoesterreich         04    Wels Stadt
## 4                Republika Srpska         02        Jezero
## 5                           Goias         29         Posse
## 6                           Goias         29         Caçu
##   county_parish_ascii county_code
## 1          Yei County    10345968
## 2           Comuna 11       02011
## 3          Wels Stadt         403
## 4              Jezero     3344112
## 5               Posse     5218300
## 6                Cacu     5204300
#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"))

Metadata

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):

BIEN_metadata_database_version()
##   db_version db_release_date
## 1        4.0      2018-05-08

** 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"),
                                      acknowledgement_file=file.path(temp_dir,"selaginella_selaginoides.txt"))

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"),
                                      acknowledgement_file=file.path(temp_dir,"selaginella_selaginoides.txt"))

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

Combining Queries

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