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
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:
As a complete example, the function BIEN_occurrence_species returns occurrence records for a given species (or set of species).
Currently we have 9 function families in RBIEN. These are sets of functions that access a given type of data.
BIEN_occurrence_...)BIEN_ranges_...)BIEN_plot_...)BIEN_trait_...)BIEN_taxonomy_...)BIEN_phylogeny_...)BIEN_stem_...)BIEN_list_...)BIEN_metadata_...)We'll walk through each of the function families and take a look at some the options available within each.
These functions begin with the prefix BIEN_occurrence_... and allow you to query occurrences by either taxonomy or geography. Functions include:
BIEN_occurrence_country Returns all occurrence records within a given country
BIEN_occurrence_state Returns all occurrences records within a given state/province
BIEN_occurrence_county Returns all occurrences records within a given state/province
BIEN_occurrence_family Returns all occurrence records for a specified family
BIEN_occurrence_genus Returns all occurrence records for a specified genus
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:
cultivated If TRUE, records known to be cultivated will be returned.
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.
all.taxonomy If TRUE, the query will return additional taxonomic data, including the uncorrected taxonomic information for those records.
native.status If TRUE, additional information will be returned regarding whether a species is native in a given region.
natives.only If TRUE, the default, information for occurrences flagged as introduced will not be returned.
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.
political.boundaries If TRUE, the query will return information on which country, state, etc. that an occurrence is found within.
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)
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)
#Looks like some islands are considerably better sampled than others.
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:
BIEN_ranges_species Downloads range maps for given species and save them to a specified directory.
BIEN_ranges_genus Saves range maps for all species within a genus to a specified directory.
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:
directory This is where the function will be saving the shapefiles you download
matched If TRUE, the function will return a dataframe listing which species ranges were downloaded and which weren't.
match_names_only If TRUE, the function will check whether a map is available for each species without actually downloading it
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)
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)
These functions begin with the prefix “BIENplot” and return ecological plot data. Functions include:
BIEN_plot_list_sampling_protocol Returns the different plot sampling protocols found in the BIEN database.
BIEN_plot_list_datasource Returns the different datasources that are available in the BIEN database.
BIEN_plot_sampling_protocol Downloads data for a specified sampling protocol
BIEN_plot_datasource Downloads data for a specific datasource
BIEN_plot_country
BIEN_plot_state
BIEN_plot_dataset Downloads data for a given dataset (which is nested within a datasource)
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.
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:
BIEN_trait_list Start with this. It returns a dataframe of the traits available.
BIEN_trait_family Returns a dataframe of all trait data for a given family (or families).
BIEN_trait_genus
BIEN_trait_species
BIEN_trait_trait Downloads all records of a specified trait (or traits).
BIEN_trait_mean Estimates species mean trait values using genus or family level means where species-level data is absent.
BIEN_trait_traitbyfamily Downloads data for a given family (or families) and trait(s).
BIEN_trait_traitbygenus
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.
BIEN_taxonomy_family Downloads all taxonomic information for a given family.
BIEN_taxonomy_genus
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:
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.
BIEN_phylogeny_conservative This function returns the conservative phylogeny.
Arguments: The function BIEN_phylogeny_complete has a few arguments that are worth explaining:
n_phylogenies This is the number of replicated phylogenies that you want to download (between 1 and 100)
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.
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)
#If we just want to see which species are included
phylo_species <- phylo$tip.label
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):
BIEN_stem_species This function downloads all of the stem data for a given species (or set of species)BIEN_stem_genusBIEN_stem_familyBIEN_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")
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:
BIEN_list_country Returns all species found within a country.
BIEN_list_state Returns all species found within a given state/province or other 2nd level political division.
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"))
The BIEN metadata functions start with the prefix BIEN_metadata_... and provide useful metadata for the BIEN database.
BIEN_metadata_database_version Returns the current version number of the BIEN database and the release date.
BIEN_metadata_match_data Rudimentary function to check for changed records between old and current queries.
BIEN_metadata_citation Function to generate bibtex citations for use in reference managers.
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.
*Example 11: Putting it all together * Coming soon!