The aim of the funbiogeopackage is to help users
streamline the workflows in functional
biogeography (Violle et al.
2014). It helps filter sites, species, and traits based on their
trait coverages. It also provide default diagnostic plots and standard
tables summarizing input data. This vignette aims to be an introduction
to the most commonly used functions.
The vignette is a worked through real world example of a functional
biogeography workflow using the internal dataset on European mammals
provided in funbiogeo.
Provided data
We are interested in mapping the functional traits of mammals of Europe. We used range maps data from the IUCN and trait data from the PanTHERIA database (Jones et al. 2009). The initial extraction scripts are available on GitHub.
The functions in funbiogeo mostly leverage three
different objects:
- the species x traits
data.frame, which describes the traits (in columns) of the species (in rows) (species_traitsdataset infunbiogeo); - the site x species
data.frame, which describes the presence/absence, the abundance, or the cover of species (in columns) across sites (in rows) (site_speciesdataset infunbiogeo); - the site x locations object, which describes the
physical location of sites through an
sfobject (site_locationsdataset infunbiogeo).
You can load the example data using the
data(..., package = "funbiogeo") call:
data("site_species", package = "funbiogeo")
data("site_locations", package = "funbiogeo")
data("species_traits", package = "funbiogeo")In the following sections we’ll describe in detail these three provided datasets in the package.
Species x Traits
This object contains traits values for multiple traits (as columns)
for studied species (as rows). It should be a data.frame.
The first column should contain species names and the other columns
contain trait values.
Note that we’ll be talking about species throughout
this vignette and in the arguments of funbiogeo, but the
package doesn’t make any assumption on the biological level. It can be
individuals, populations, strains, species, genera, families, etc. The
important fact is that you should have trait data for the level at which
you want to work.
Let’s examine the species_traits data included in the
package:
| species | adult_body_mass | gestation_length | litter_size | max_longevity | sexual_maturity_age | diet_breadth |
|---|---|---|---|---|---|---|
| sp_001 | 461900.76 | 235.00 | 1.25 | 324 | 668.20 | 1 |
| sp_002 | 21.11 | 19.89 | 5.64 | 48 | 76.04 | NA |
| sp_003 | NA | NA | NA | NA | NA | NA |
| sp_004 | NA | NA | NA | NA | NA | NA |
The first column "species" contains
species names, while the next 6 columns contain different traits for all
species. Note that the species names are anonymized because the IUCN
data cannot
be redistributed.
Let’s look at a summary of the trait dataset:
summary(species_traits)
#> species adult_body_mass gestation_length litter_size
#> Length:149 Min. : 2.3 Min. : 19.50 Min. :0.980
#> Class :character 1st Qu.: 11.2 1st Qu.: 26.61 1st Qu.:1.500
#> Mode :character Median : 35.9 Median : 41.99 Median :3.055
#> Mean : 18809.7 Mean : 69.93 Mean :3.369
#> 3rd Qu.: 2573.2 3rd Qu.: 76.70 3rd Qu.:4.970
#> Max. :675876.7 Max. :265.99 Max. :8.990
#> NA's :26 NA's :61 NA's :35
#> max_longevity sexual_maturity_age diet_breadth
#> Min. : 12.0 Min. : 25.37 Min. :1.000
#> 1st Qu.: 58.8 1st Qu.: 106.67 1st Qu.:1.000
#> Median :180.0 Median : 348.44 Median :1.000
#> Mean :171.3 Mean : 392.01 Mean :2.458
#> 3rd Qu.:252.0 3rd Qu.: 549.05 3rd Qu.:4.000
#> Max. :600.0 Max. :1542.25 Max. :8.000
#> NA's :68 NA's :65 NA's :66From there we can see that there are 149 included species and some missing trait values. For example, we don’t have body mass information for 26 species.
Note that to use your own species by traits data.frame,
it should follow similar structure with the first column being named
"species" and the other ones containing
traits.
Site x Species
This object contains species occurrences/abundance/coverage at
sites
of the study area. It is a data.frame. The first column,
"site", contains site names while the
other columns contains the abundance of each species across sites.
Note that here we are talking about sites in an abstract way. These can be plots, assemblages, of whatever collections of species you’re interested in.
The package funbiogeo comes with the example dataset on
European mammals site_species. Let’s look at it:
| site | sp_001 | sp_002 | sp_003 |
|---|---|---|---|
| 1 | 1 | 0 | 0 |
| 2 | 1 | 0 | 0 |
| 3 | 1 | 0 | 0 |
| 4 | 1 | 0 | 0 |
| 5 | 1 | 0 | 0 |
| 6 | 1 | 0 | 0 |
| 7 | 1 | 0 | 0 |
| 8 | 1 | 0 | 0 |
| 9 | 1 | 0 | 0 |
| 10 | 1 | 0 | 0 |
The example dataset contains the occurrence of the 149 mammal species across 1,505 sites (grid cells of 0.5° x 0.5° resolution).
Note that to use your own site by species data.frame, it
should follow similar structure with the first column being named
"sites" and the other ones containing
presence information of species across sites.
Site x Locations
This object contains the geographical location of the sites. It
should be an sf object from the sf
package. These are spatial R objects that describe geographical
locations. The sites can have arbitrary shapes: points, regular
polygons, irregular polygons, or even line transects! To make sure that
your data is well plotted you should specify the Coordinate Reference
System (CRS) of this object.
The package funbiogeo comes with the example dataset
site_locations defining the location of the 1,505 sites
(grid cells of 0.5° x 0.5° resolution) as polygons. It contains the
names of the site in its first column
"site":
site_locations
#> Simple feature collection with 1505 features and 1 field
#> Geometry type: POLYGON
#> Dimension: XY
#> Bounding box: xmin: -9.978179 ymin: 35.84736 xmax: 23.02182 ymax: 59.84736
#> Geodetic CRS: WGS 84
#> First 10 features:
#> site geom
#> 1 1 POLYGON ((5.521821 59.84736...
#> 2 2 POLYGON ((6.521821 59.84736...
#> 3 3 POLYGON ((7.021821 59.84736...
#> 4 4 POLYGON ((7.521821 59.84736...
#> 5 5 POLYGON ((8.021821 59.84736...
#> 6 6 POLYGON ((8.521821 59.84736...
#> 7 7 POLYGON ((9.021821 59.84736...
#> 8 8 POLYGON ((9.521821 59.84736...
#> 9 9 POLYGON ((10.02182 59.84736...
#> 10 10 POLYGON ((10.52182 59.84736...Note that to use your own site locations object, it should follow
similar structure, being an sf object with the first column
being named "sites".
Visualizing the data (diagnostic plots)
funbiogeo provides many functions to display the data to
help the user select specific traits, species, and/or sites. We are
going to detail some of them in this section (see the full list in the
diagnostic plots vignette. We call
them diagnostic plots because they help us to have an overview
of our dataset prior to the analyses.
Trait completeness per species
A first way to visualize our data.frame is to look at
the proportion of species with non-missing traits using the
fb_plot_number_species_by_trait() function. It takes the
species by trait data.frame as input.
fb_plot_number_species_by_trait(species_traits)
This plot shows us the number of species (along the x-axis) in function of the trait name (along the y-axis). The number of concerned species is shown at the bottom of the plot while the corresponding proportion of species (compared to all the species included in the trait dataset) is indicated as a secondary x-axis at the top. The proportion of species concerned is shown at the right of each point. For example, in our example dataset, 82.6% species have a non-NA adult body mass.
The function also include a way to provide a target proportion of species as the second argument. It will display the proportion as a dark red dashed line.
For example, if we want to visualize which traits cover more than 75% of the species:
fb_plot_number_species_by_trait(species_traits, threshold_species_proportion = 0.75)
The top number shows the corresponding number of species.
Number of Traits per Species
Another way to filter the data would be to select certain species
that have at least a certain number of traits. This can be visualized
using the fb_plot_number_traits_by_species() function.
Similarly to the above-mentioned function, it takes the species x traits
data.frame as the first argument:
fb_plot_number_traits_by_species(species_traits)
The plot shows the number (bottom x-axis) and the proportion (top x-axis) of species covered by a specific number of traits (0 to 6 in our example).
Filtering the data
Now that we displayed the diagnostic plots, we can decide thresholds and filter our data for our following analyses.
Filter trait by species coverage
We want to select the traits that are available for at least 75% of
the species. To do so we can use the
fb_filter_traits_by_species_coverage() function. The
function takes the species by traits data.frame and outputs
the same dataset but with the traits filtered (so with less columns).
The second argument threshold_species_proportion is the
threshold proportion of species covered:
# Initial dimension of the input data
dim(species_traits)
#> [1] 149 7
# Filter traits
red_sp_traits <- fb_filter_traits_by_species_coverage(
species_traits, threshold_species_proportion = 0.75
)
dim(red_sp_traits)
#> [1] 149 3
# The reduced data set now has fewer trait columns
head(red_sp_traits)
#> species adult_body_mass litter_size
#> 1 sp_001 461900.76 1.25
#> 2 sp_002 21.11 5.64
#> 3 sp_003 NA NA
#> 4 sp_004 NA NA
#> 5 sp_005 31.60 4.94
#> 6 sp_006 21.90 5.16The function outputs a filtered species-traits dataset retaining only traits covering at least 75% of the species. In the end this keep two traits: body mass and litter size.
Filter species by trait coverage
Similarly you could filter species by their trait coverage. For
example we would like to make sure that the species we filtered
previously so that they show at least one of the two traits selected
above and thus exclude species for which neither of the traits are
available. We can use the function
fb_filter_species_by_trait_coverage() with the species x
traits data.frame as the first argument and the second
argument the proportion of traits covered by species.
# Filter species with at least 50% of included (two traits)
# at least one trait
red_sp_traits_2 <- fb_filter_species_by_trait_coverage(
red_sp_traits, threshold_traits_proportion = 0.5
)
head(red_sp_traits_2)
#> species adult_body_mass litter_size
#> 1 sp_001 461900.76 1.25
#> 2 sp_002 21.11 5.64
#> 5 sp_005 31.60 4.94
#> 6 sp_006 21.90 5.16
#> 7 sp_007 18.26 5.72
#> 9 sp_009 903.98 2.50
dim(red_sp_traits_2)
#> [1] 127 3We thus have selected 2 traits that cover at least 75% of the initial species list and 127 species which have known values for these two traits.
Filter sites by trait coverage
Now that we have filtered our traits and species of interest we need
to filter the sites, that contain enough species for which the traits
are available. Similarly to above the function is
fb_filter_sites_by_trait_coverage() it takes as two first
arguments the site x species data.frame and the species x
traits data.frame. The third argument is
threshold_traits_proportion that indicates the percent
coverage of traits to filter each site. Note that this coverage is
weighted by the occurrence, abundance, or cover depending on the content
of the site x species data.frame.
Let’s say here we’re interested in sites for which our species with available traits represent at least 90% of the species present:
# Initial site x species data
dim(site_species)
#> [1] 1505 150
# Filter sites with at least 90% species covered
filt_sites <- fb_filter_sites_by_trait_coverage(
site_species, red_sp_traits_2, threshold_traits_proportion = 0.9
)
# Filtered sites
dim(filt_sites)
#> [1] 1268 150
filt_sites[1:4, 1:4]
#> site sp_001 sp_002 sp_003
#> 1 1 1 0 0
#> 2 2 1 0 0
#> 3 3 1 0 0
#> 4 4 1 0 0The output of the function is a site x species
data.frame with selected sites and species. Now we selected
1,268 sites out of 1,505, for our 2 traits and 127 species.
Computing Functional Diversity metrics
The funbiogeo functions helped us filter our data
appropriately with enough available trait information for species and
sites.
We can use the filtered datasets to proceed with our analyses using
other readily available tools for functional diversity indices. This
where you should use your preferred packages to compute functional
diversity indices like fundiversity,
betapart,
or hypervolume.
For the sake of the example we included a function in
funbiogeo to compute Community-Weighted Mean (CWM, Garnier et al. 2004) named
fb_cwm(). The CWM is the abundance-weighted average trait
per site. We’ll be using it in the following section we’ll then show
another example computing functional diversity indices using the
fundiversity package.
Community-Weighted Mean (CWM)
We’re interested to look at the spatial distribution of the average
body mass and litter size of European mammals. To do so, we can compute
the community-weighted mean of both traits. We’ll use the
fb_cwm() function to do so, it takes the site x species
data.frame and species x traits data.frame as
arguments.
# Note that we're reusing our filtered data to compute CWM
cwm <- fb_cwm(filt_sites, red_sp_traits_2)
#> Some species had NA trait values, removing them from CWM computation
head(cwm)
#> site trait cwm
#> 1 1 adult_body_mass 31974.15
#> 2 2 adult_body_mass 39911.51
#> 3 3 adult_body_mass 39912.54
#> 4 4 adult_body_mass 39912.54
#> 5 5 adult_body_mass 41389.44
#> 6 6 adult_body_mass 39912.37It outputs a data.frame with 3 columns: the first one,
site, shows the site name as provided in the input site x
species data.frame, trait which indicates the
trait name on which the CWM is computed, and cwm which
shows the value of the CWM.
Compute functional diversity indices
We can also integrate our filtered datasets in other functional
diversity computation pipeline. We’ll show an example by computing
functional richness with fundiversity.
## To install 'fundiversity' uncomment the following line
# install.packages("fundiversity")
# Functional richness in 'fundiversity' requires all the traits to be known
# so we need to filter the traits
filt_traits <- subset(
red_sp_traits, !is.na(adult_body_mass) & !is.na(litter_size)
)
# We need to transform species and site names as row names for species-traits
# and site-species data.frames, as required by 'fundiversity'
rownames(filt_traits) <- filt_traits$species
filt_traits <- filt_traits[, -1]
rownames(filt_sites) <- filt_sites$site
filt_sites <- filt_sites[, -1]
# Scale traits
filt_traits <- scale(filt_traits)
# Compute Functional Richness
fric <- fundiversity::fd_fric(filt_traits, filt_sites)
#> Differing number of species between trait dataset and site-species matrix
#> Taking subset of species
#> Warning in fundiversity::fd_fric(filt_traits, filt_sites): Some sites had less
#> species than traits so returned FRic is 'NA'
head(fric)
#> site FRic
#> 1 1 10.78778
#> 2 2 10.78778
#> 3 3 10.78778
#> 4 4 10.78778
#> 5 5 10.78778
#> 6 6 10.78778We now have a table with Functional Richness computed for all of our sites.
Putting variables on the map
Map of environmental raster
If we want to display the environment associated with our sites of
interest, we can leverage environmental raster layers, like the mean
annual temperature. Fortunately, we have access to an example raster of
mean annual temperature through funbiogeo. The package
provides a helper function display a raster layer easily (without any
assumption about the projection) named fb_map_raster():
# Read raster
tavg <- system.file(
"extdata", "annual_mean_temp.tif", package = "funbiogeo"
)
tavg <- terra::rast(tavg)
# Map raster
fb_map_raster(tavg) +
scale_fill_distiller("Temperature", palette = "Spectral") +
theme(legend.position = "bottom") +
ggtitle("Mean annual temperature in Europe")
We can also combine that with the annual precipitation information available as an example
library("patchwork")
# Read raster ------------------------------------------------------------------
tavg <- system.file("extdata", "annual_mean_temp.tif", package = "funbiogeo")
tavg <- terra::rast(tavg)
prec <- system.file("extdata", "annual_tot_prec.tif", package = "funbiogeo")
prec <- terra::rast(prec)
# Individual Maps --------------------------------------------------------------
map_temperature <- fb_map_raster(tavg, legend.position = "none") +
scale_fill_distiller("Temperature", palette = "Spectral")
map_precipitation <- fb_map_raster(prec) +
scale_fill_distiller("Precipitation", direction = 1)
# Plot composition -------------------------------------------------------------
(map_temperature / map_precipitation) +
plot_annotation(title = "Europe",
theme = theme(plot.title = element_text(face = "bold"))) &
theme_classic() &
theme(text = element_text(family = "mono"))
This function allows the visualization of a raster in a simple fashion, but it doesn’t tell us anything about the environmental variable at the sites. In the next section we will follow the example of mapping an environmental variable.
Map of average environmental variable in site
To get the average environmental variable in the site we can use the
fb_get_environment() function, it takes as arguments the
site-locations object and an environmental raster from the
terra package. By default, it takes the average of the
raster values per site.
site_mat <- fb_get_environment(site_locations, tavg)
head(site_mat)
#> site annual_mean_temp
#> 1 1 6.6755822
#> 2 2 1.6836227
#> 3 3 0.6628264
#> 4 4 1.4940648
#> 5 5 2.6325313
#> 6 6 3.0806597The variable names in columns are based on the names of the provided
raster. To put these values on the map we can use the
fb_map_site_data() function, which allows mapping arbitrary
site-level variables. It takes three needed arguments: the first of
which, site_locations, which is the sf object
describing sites’ geographic locations; the second argument is
site_data, which is a data.frame giving
additional data indexed by site; and selected_col, which is
a character giving the name of the column to plot from the
site_data argument.
We can thus plot the mean annual temperature of sites through the following commands:
fb_map_site_data(site_locations, site_mat, "annual_mean_temp") +
labs(title = "Mean Annual Temperature per Site")
Map of functional diversity indices
We can leverage the same functions to map our functional diversity indices. For example, with the body mass CWM:
body_mass_cwm <- subset(cwm, trait == "adult_body_mass")
fb_map_site_data(site_locations, body_mass_cwm, "cwm") +
scale_fill_viridis_c(trans = "log10") +
labs(title = "Mammals Body Mass CWM")
We can do similarly for functional richness:
fb_map_site_data(site_locations, fric, "FRic") +
scale_fill_viridis_c(option = "magma") +
labs(title = "Mammals Functional Richness")
Conclusion
This concludes our tutorial to introduce funbiogeo. The
packages contains many more features, especially diagnostic plots, which
are explained in detail in a dedicated
vignette. There is also a specific vignette about transforming raw data from long to wide
format. Finally, if you’re interested in learning about up-scaling
your sites, you can refer to the specific
vignette