biomonitoR: an R package for managing ecological data and calculating biomonitoring indices

Import data

The first step consists in comparing user’s data to a reference taxonomic dataset with the function as_biomonitor. User’s data consists in a data.frame with taxa on the first column and occurrences/abundances on the following columns, while the taxonomic reference dataset includes the relationships of taxa among levels. biomonitoR comes with four built-in reference datasets for diatoms, macrophytes, macroinvertebrates and fish derived from Diat.barcode (Rimet et al., 2019), AlgaeBase (Guiry et al., 2014), freshwatercology.info (Schmidt-Kloiber & Hering, 2015), and FishBase (Froese & Pauly, 2019), respectively. To ensure an up-to date and global taxonomy information, several functions (e.g., get_gbif_taxa_tree) are already available, permitting the user to build a biomonitoR reference dataset from online resources such as the Global Biodiversity Information Facility (GBIF), World Register of Marine Species (WoRMS), National Biodiversity Network Atlas (NBN Atlas) and International Union for Conservation of Nature (IUCN) (SM1). Moreover, users can also provide their own reference dataset or build it from a taxonomic tree with the function ref_from_tree. This is a crucial step in data handling to organize and clean the dataset as well as unify writing styles (e.g., lexical variants). Taxa names that do not match with any taxon of the reference taxonomy are excluded to ensure consistency of further steps. Nonetheless, suggestions are proposed either silently or interactively by setting the correct_names argument to TRUE. To explore the general data structure, the object generated by as_biomonitor can be subsetted or plotted by leveraging on the interactive plotly package (Sievert, 2020). The second step consists in using the function aggregate_taxa to aggregate taxa at different taxonomic levels according to the user’s data resolution. The obtained object can be used to calculate all the indices implemented in biomonitoR at the desired taxonomic resolution.

Multiple taxonomic levels and back trace

biomonitoR calculates ecological indices at different taxonomic levels. The desired taxonomic level (e.g., species, family) can be specified with the argument tax_lev. This is a key feature to develop robust methods based on taxonomic sufficiency, the level of taxonomic detail to which organisms must be identified to recognize ecological patterns (Jones, 2008).

To keep track of the computations performed by biomonitoR, the original information can be obtained by setting the traceB argument to TRUE. This is especially useful when mismatches between taxonomic and sensitivity/traits datasets lead to the exclusion of some taxa. To further assure the transparency of the entire process, default scores are made available by using the show_scores function. biomonitoR is designed to be flexible, such that users can use their own scores or trait information. For example, in river biomonitoring, the calculation of the internationally used Average Score Per Taxon index (ASPT; Hawkes, 1998, see SM2) can be adapted to user-defined scores and taxonomic aggregation rules (e.g., combining taxa with similar stressor-specific responses). This feature can be extremely helpful when users want to test indices sensitivity or for simulation studies.

Tools for managing trait-based information and indices availability

biomonitoR allows users to overcome problems frequently arising during the computation of trait-based indices. The package includes several functions to manage functional traits information allowing the calculation of a range of functional metrics most of which are based on the FD (Laliberté & Legendre, 2010) and ade4 packages (Dray & Dufour, 2007). For example, the function assign_traits matches the taxa to those of the traits dataset. This is particularly useful when traits of several taxa in the trait dataset (e.g., species- and genus-level) can be assigned to a higher taxonomic level (e.g., family level). Currently, biomonitoR comes with a built-in macroinvertebrate trait dataset (European fauna: Schmidt-Kloiber & Hering, 2015; Tachet et al., 2010) but users can also add their own (see an example of loading a dataset including North American insect traits in SM3). A finer control over trait information can be achieved with the manage_traits function, that allows users to select the traits belonging to the nearest taxon in the taxonomic tree (e.g., SM3). Finally, traits at fine levels (e.g., species or genus) can be averaged at coarser levels (family) (average_traits) or a random taxon (e.g., genus) can be selected as representative (sample_traits). The calculation of some functional indices (e.g., functional richness, dispersion and evenness) requires summarizing trait variation into a low dimensional trait space. This can be achieved through a principal coordinate analysis based on a matrix of Euclidean distances or Gower dissimilarities. The quality of the trait space can be evaluated and adjusted using the function select_pcoa_axes to avoid poor representations (Maire et al., 2015). This function implements three ways of evaluating the quality of the functional space: (i) the correlation between the Euclidean distance of the n selected axis and the overall distance; (ii) the r² proposed by Legendre & Legendre (2012) and (iii) the mean squared deviation approach proposed by Maire et al. (2015). If the species-by-species distance matrix is not Euclidean, select_pcoa_axes calculates the performance of four widely used transformations (Cailliez, Lingoes, square root and quasi-Euclidean; see Legendre & Legendre, 2012). Sometimes, data transformation is not enough to make the species-by-species matrix Euclidean (e.g., when two or more taxa share the same traits) with potential negative effects on downstream data analysis. To resolve this issue, biomonitoR comes with two approaches. The first option aggregates the abundance of taxa with the same traits (zerodist_rm). The second option (add_bias_to_traits) differentiates taxa with identical trait profiles by adding a small amount (random bias) to the traits of each taxon (see R code and examples in SM3).

Overall, both taxonomic-based indices and more novel measures still pending to be fully incorporated in national or international biomonitoring schemes are available in the package. biomonitoR currently allows the calculation of more than 30 indices (including diversity, biomonitoring, and functional measures) as well as a wide range of complementary taxonomic measures (e.g., richness or abundance of a specific taxon, pair and combination of taxa, see Table 2 and examples of applications in SM2).

Data visualization

biomonitoR relies on the plotly package for providing flexible and high-quality graphs. Three types of plots are currently available to visualize the data. The first is a Sankey diagram that links indicator taxa (De Cáceres & Legendre, 2009) from a desired to an upper taxonomic level through groups provided by the user or identified by a cluster analysis (e.g., Fig. 2). The second plots the prevalence of a taxonomic level (e.g., family) within an upper taxonomic level (e.g., order, see SM4a-c). The third is an interactive barplot reporting the proportion of taxa within a desired taxonomic level, with sites ordered according to the results of a cluster analysis (see examples and codes in SM4d).

Package installation and basic usage example

The biomonitoR package (version 0.9.3) is available on GitHub (https://github.com/alexology/biomonitoR). The package can be installed as follows:

library(devtools)

install_github(“alexology/biomonitoR”, ref = “main”, build_vignettes = TRUE)

An R Shiny implementation (Chang et al., 2021), as interactive app of the package, is available from the R console running the command line:

library(shiny)

runGitHub(“biomonitoR_app”, “TommasoCanc”, ref = “main”, subdir = “biomonitoR_app”)

as well as in the webpage (https://tcanceco.shinyapps.io/biomonitoR_app/).

These complementary options allow working with a user-friendly graphical interface that will benefit different audiences (either familiar or not with R programming language), thus making biomonitoR widely accessible and interactive.

Usage example

# Load the package

library(biomonitoR)

# Load one of the built-in macroinvertebrate datasets (mi_prin)

data(mi_prin)

# Details about the dataset

?mi_prin

# Import data in the biomonitoR format

data_asb <- as_biomonitor(mi_prin, group = “mi”)

# Inspect the overall community structure by plotting the object

plot(data_asb)

# Aggregate taxa at different taxonomic levels

data_agg <- aggregate_taxa(data_asb)

# Calculate a taxonomic index

# e.g., Shannon index at taxa and family level

shannon(data_agg, tax_lev = “Taxa”)

shannon(data_agg, tax_lev = “Family”)

# Calculate a biomonitoring index

# e.g., ASPT index with function aspt (see ?aspt for details)

aspt(data_agg)

Detailed scripts for running further analyses (e.g., data manipulation, biomonitoring indices calculations, function customization, plots) are provided in SM2-3-4. The package is being regularly updated and we encourage interested users to look for the latest version in GitHub and to report any suggestion for further development.

Limitations and perspectives

Despite its flexibility, biomonitoR may presents some punctual limitations. The reference dataset needs to be implemented according to the taxonomic levels that are currently available in the package. This can be an issue in the occasional cases where species-groups, life stage information or operational taxonomic units are needed. With minor adjustments (e.g., considering species groups as species) their use is still possible with the current implementation. Moreover, according to Tables 1–2, one of the main biomonitoR assets (i.e., multiple index calculation) is biased towards the biomonitoring of running waters. This is due to the unparalleled pressures affecting freshwater biodiversity worldwide and the long history of biological monitoring in rivers, that date back to the beginning of the 20th century (Bonada et al., 2006). Nonetheless, a detailed biomonitoring toolbox, not constrained at local scale, is still missing (see Table 1) and biomonitoR aspires to fill this gap. It should be noted that, despite the primary focus at European level, the package can potentially achieve a more international perspective after further customizations. Most of the river biomonitoring metrics tested in Africa, South-Central America, Mexico, Australia, and Asia are, in fact, directly related to the Biological Monitoring Working Party scoring systems (BMWP/ASPT, Aschalew & Moog, 2015; Eriksen et al., 2021; Feio et al., 2021) originally developed in the UK and already available in biomonitoR (Table 2).

Regardless of the primary freshwater focus, the package can instantly manage biological data from other domains (e.g., marine, terrestrial) and communities (e.g., non-aquatic plants, vertebrates) if a reference dataset is uploaded by the users or specifically built from online sources with the internal functions. In addition, general-purpose indices for biodiversity analysis and assessment (e.g., taxonomic and functional measures) can be already computed.