Summary

  1. Functional diversity is increasingly described as an essential trait of ecosystem functioning; hence, its temporal analyses may provide a basis to understand past, present, and future trajectories of ecological assemblages. In this article, we present the package FDSeries for R, seeking to contribute with an open-source tool to study temporal patterns in functional diversity.
  2. We developed a set of open-source functions, stored in FDSeries package, compatible with the platform R to analyse user’s records different temporal instances and compute functional diversity metrics. The package’s functions run over a data set containing the identification of functional traits at different time bins and abundance for each functional category.
  3. The package allows quantifying different estimates of functional diversity, the visualisation of functional space and the contrast of the observed metrics against user-customised null models alongside with visualisations of basic plots of the temporal trajectories.
  4. Extrinsic and intrinsic events leave a trace in the records of functional diversity and its relationship with ecosystem functioning. This package contributes to the quantification of functional diversity over a time series, allowing further studies of the functional dynamics of ecological communities and inferring how these may have responded to environmental changes.

Preamble

The FDSeries package is located in an open repository; it can be downloaded and installed directly from R/Rstudio by using


devtools::install_github("simonpcastillo/FDSeries", subdir="pkg")


#Or with the source packages

urlfrom <- "https://github.com/simonpcastillo/FDSeries/raw/master/FDSeries_0.1.0.tar.gz"
download.file(url=urlfrom, destfile = "FDSeries_0.1.0.tar.gz")
install.packages("FDSeries_0.1.0.tar.gz", repos = NULL, type="source")


#Then, loading it

library(FDSeries)

Start here: Input data

To run the functions in this package, the user needs to have loaded a data frame of abundances for different life-modes or ecocodes for more than one-time bin. If the user has data only for one-time bin, the FDSeries package works in the same way that the FD package. There are two startings points and which of them the user will choose depends on what is the data he/she has. The first starting point considers that the user has a list of records of individuals at different time bins and their corresponding ecological features (ecocodes). In the package, we have added the dataset data0 which represents a complitation of records to the level of genus (View(data0)). The second starting point considers that the user already has a dataframe with the estimation of occurrences for each ecocode over at east two time bins (View(data1)). If you have a dataset like data0, your strating point is the function 0 Fd_rarefaction(). Otherwise, if your dataset is like data1, your starting point is the function 1 FD_df().

Function 0 FD_rarefaction()

To transform a dataframe like data0 into a time x ecocode and occurrences dataframe, we create the FD_rarefaction(), a function that computes rarefaction analysis and saves two dataframes in your working directory named “EcoGenera.csv” and “EcoOccurrences.csv,” which can be used with the following function Fd_df(). The “EcoOccurrences.csv”: stores the number of ocurrences by ecocode over time; and “EcoGenera.csv”: stores the number of genera by ecocode over time. The function FD_rarefaction() has two arguments

  • data: a dataframe containing the database of ocurrences at a given taxonomic level. It must match column names of .
  • time: numeric. The number of iterations to run. Default 500.

Note that to complete a sucessful analysis, the data must match the colnames exemplified by the package dataset data0 (view (names(data0) or View(data0))).

For example, using the dataset data0 in the package, the user can run


FD_rarefaction(df = data0, times = 100)

Function 1 FD_df()

Once we have an input data like data1, this function transforms it into a functional diversity dataframe data2.The function has two arguments:

  • df: dataframe. Input dataframe with row names indicating time bins and column names indicating each life-mode or ecocode. The df values are estimates of the abundance of each life-mode at each time bin.
  • subcat: numeric vector. The number of subcategories that each trait has. Its length must be equal that the number of traits of each life-mode.

To be clear, an ecocode is defined by a numeric sequence of traits as integers (e.g., 153), hence, the length of the subcat argument must be three and its values cannot be numerically lower than the respective values in the ecocode’s traits.

For example, using the package dataset we call the function defining the arguments as follows


data2 <- FD_df(df=data1, subcat = c(6, 6, 6))

head(data1)
#>            111     115    261 266    311    312    315    321    322    324
#> -270.55 0.0000 10.5002 1.9364   0 0.4209 0.9531 0.1889 0.0000 0.4581 0.8169
#> -266.95 0.0000  8.2779 1.1165   0 0.3732 0.3857 0.2317 5.0112 5.4310 2.8344
#> -262.45 0.0000  2.0814 2.0708   0 1.1786 0.6955 0.0000 0.6648 4.2823 5.9083
#> -257.1  0.1334  9.3056 1.5605   0 0.8339 0.4937 0.3599 1.8926 8.0796 2.1219
#> -253.3  0.0000  8.4060 0.1980   0 0.7890 0.0000 1.6276 0.1892 4.9156 2.5069
#> -251.9  0.0000 22.5945 0.0000   0 0.0000 0.0000 2.9897 1.0563 1.5597 1.5343
#>            325    331 335    336    341     351 352    356      361 365 366
#> -270.55 0.3665 4.3202   0 0.2820 0.0903  5.8618   0 0.2515 131.5343   0   0
#> -266.95 0.9178 5.0435   0 0.4673 0.0753  5.0080   0 0.0000 100.8842   0   0
#> -262.45 2.8540 7.5305   0 0.9219 1.8390  5.6273   0 0.0000 102.6099   0   0
#> -257.1  2.3756 5.0468   0 0.3548 0.6650  6.7659   0 0.0000 125.1008   0   0
#> -253.3  2.4731 9.7987   0 0.1940 1.1490 10.3891   0 0.0000 110.5907   0   0
#> -251.9  0.2928 0.9671   0 0.0000 0.0000  3.8479   0 0.0000   3.6502   0   0
#>            422 431    441    451    461    525    531    532    533 535 536 541
#> -270.55 0.2681   0 1.6313 0.5086 0.6126 0.3222 1.5745 0.9093 0.2559   0   0   0
#> -266.95 0.0803   0 1.1148 0.7013 0.2788 1.1493 0.8768 1.8515 0.2870   0   0   0
#> -262.45 0.2666   0 1.7453 0.6730 0.3640 1.2363 1.8992 2.5364 0.6147   0   0   0
#> -257.1  0.8114   0 1.5120 0.1467 0.4967 1.6787 1.9930 1.0871 0.3573   0   0   0
#> -253.3  1.1866   0 1.5220 0.7531 0.0000 1.9677 3.6596 1.1092 0.4821   0   0   0
#> -251.9  0.0000   0 0.8339 0.0000 0.9489 0.9578 2.3147 0.6854 0.2991   0   0   0
#>            542    631 632    636    646
#> -270.55 0.0000 3.3870   0 0.0000 0.3240
#> -266.95 0.0794 6.2457   0 0.0000 0.1510
#> -262.45 0.1457 7.0260   0 0.0000 0.0000
#> -257.1  0.0000 1.6090   0 0.0708 0.1975
#> -253.3  0.0000 2.6772   0 0.1980 0.1949
#> -251.9  0.0000 0.0000   0 0.0000 0.0000

We create data2 (a dataframe), a functional diversity dataframe (it is not a special object type, it is just to differentiate them). The dataframe data2 is an extended version of data1, showing an extension of the functional traits for the next analyses.
The next two functions allow us to quantify different measures associated to the functional diversity (Villéger, Mason, and Mouillot (2008)),; hence, to expound the temporal dynamics of multidimensional functional traits within a community.

Empirical functional diversity estimates

Function 2 FD_Rao()

One of the estimations used to characterise the functional diversity of a community is the Rao’s quadraic entropy (Rao (1982)). This functions calculates the Rao’s quadratic entropy, Simpson’s index and functional redundancy for each time bin along the temporal series. Its argument is

  • df: dataframe. A functional diversity dataframe obtained by using the function FD_df.

RaoSummary <- FD_Rao(df=data2)

head(RaoSummary)
#>            Time           Simpson            FunRao     FunRedundancy
#> -270.55 -270.55 0.378683859457612  0.18981696578351 0.188866893674102
#> -266.95 -266.95  0.53037712635285 0.260334101835751 0.270043024517099
#> -262.45 -262.45 0.550861548537347 0.262993881709145 0.287867666828202
#> -257.1   -257.1 0.480947800994248 0.237843550043117 0.243104250951131
#> -253.3   -253.3 0.548931004554903 0.265836754197044 0.283094250357859
#> -251.9   -251.9 0.716138117547658  0.38324588609151 0.332892231456147

This function returns a dataframe with the Rao’s complexity, Simpson’s diversity, and functional redundancy estimates calculated using the SYNCSA::rao.diversity function for each time bin.

Function 3 FD_metrics()

This function computes other functional diversity metrics. This function is based on Villéger, Mason, and Mouillot (2008), and the code is an edited version of Villeger’s code. Its argument is

  • df: dataframe. A functional diversity dataframe obtained by using the function FD_df.

FDSummary <- FD_metrics(df=data2)

head(FDSummary)
#>      time     FEve     FDiv             FSpe      FRic       chull_PC12
#> 1 -270.55 0.577572  0.98229 1.95243171254855 36.863141 13.1659113635074
#> 2 -266.95  0.59307 0.945219 1.93037543666628 36.748695 13.5068403229266
#> 3 -262.45 0.660154 0.920743 1.84046552568333 34.897932 13.8611645635014
#> 4  -257.1 0.562985 0.933646 1.92551216847947 36.093038 13.2835230628728
#> 5  -253.3 0.579267 0.946244 2.02539987579784 33.827874 12.9693920094878
#> 6  -251.9 0.717383 0.938177  2.2746897894888 24.232251 12.3279051677803
#>         chull_PC13
#> 1 11.0586207054292
#> 2 10.8930399202957
#> 3 11.5229219220032
#> 4 10.4942827558744
#> 5 10.2519857158861
#> 6 10.1657274752509
#> 
#> Attaching package: 'zoo'
#> The following objects are masked from 'package:base':
#> 
#>     as.Date, as.Date.numeric
#>      time     FEve     FDiv             FSpe      FRic       chull_PC12
#> 1 -270.55 0.577572  0.98229 1.95243171254855 36.863141 13.1659113635074
#> 2 -266.95  0.59307 0.945219 1.93037543666628 36.748695 13.5068403229266
#> 3 -262.45 0.660154 0.920743 1.84046552568333 34.897932 13.8611645635014
#> 4  -257.1 0.562985 0.933646 1.92551216847947 36.093038 13.2835230628728
#> 5  -253.3 0.579267 0.946244 2.02539987579784 33.827874 12.9693920094878
#> 6  -251.9 0.717383 0.938177  2.2746897894888 24.232251 12.3279051677803
#>         chull_PC13
#> 1 11.0586207054292
#> 2 10.8930399202957
#> 3 11.5229219220032
#> 4 10.4942827558744
#> 5 10.2519857158861
#> 6 10.1657274752509

The function returns a dataframe FDsummary, which contains the estimated parameters for functional diversity for each time bin. FEve functional evenness, FDiv functional divergence, FSpe functional specialisation, and FRic functional richness. Also, several objects will be created in the global environment:

  • FuncSpace: list to the Global Environment. Stores the functional space for each time bin.
  • ch1_list: list to the Global Environment. Stores convex hull coordinates. Graphical use in FD_plotPC.
  • ch2_list: list to the Global Environment. Stores convex hull coordinates. Graphical use in FD_plotPC.
  • pc1_list: list to the Global Environment. Stores principal component coordinates. Graphical use in FD_plotPC.
  • pc2_list: list to the Global Environment. Stores principal component coordinates. Graphical use in FD_plotPC.
  • pc3_list: list to the Global Environment. Stores principal component coordinates. Graphical use in FD_plotPC.

Function 4 FD_plotRao()

The next two functions allow to make simple plots (based on ggplot2) of the functional metrics (Simpson, Rao’s quadratic Entropy and Funcional redundancy) over time from empirical data calculated previously with FD_Rao. The arguments of the function are:

  • df: dataframe obtained after running FD_Rao.
  • save.plot: TRUE or FALSE. Default TRUE.
  • ext: extension for the saved figures admitted by ggplot2::ggsave (e.g., ".png", ".svg"). Default ".png".

head(RaoSummary) # dataframe returned by DF_Rao
#>            Time           Simpson            FunRao     FunRedundancy
#> -270.55 -270.55 0.378683859457612  0.18981696578351 0.188866893674102
#> -266.95 -266.95  0.53037712635285 0.260334101835751 0.270043024517099
#> -262.45 -262.45 0.550861548537347 0.262993881709145 0.287867666828202
#> -257.1   -257.1 0.480947800994248 0.237843550043117 0.243104250951131
#> -253.3   -253.3 0.548931004554903 0.265836754197044 0.283094250357859
#> -251.9   -251.9 0.716138117547658  0.38324588609151 0.332892231456147

FD_plotRao(RaoSummary, save.plot=FALSE, ext=".png")

This function returns two plots of Rao’s quadratic entropy, functional redundancy and Simpson’s richness estimates over time (raw and normalised). If save.plot is TRUE, the plots will be saved too. If the function is assigned it returns a list with two plots plot1 and plot2, with the raw and normalised plots, respectively. The normalisation is performed within each variable according to its minimum and maximum values.
The user can make their own plots with the dataframe returned by FD_Rao.

Function 5 FD_plotFS()

Another method to visualise the functional diversity is by plotting the functional space. This function plots the functional space for each time bin as paired coordinates PC1 vs PC2 and PC1 vs PC3, where each point is a life-mode or ecocode and its size is proportional to its abundance at that time.
The argumentsof this function are:

  • dfFD: dataframe. A functional diversity dataframe created with the function FD_df.
  • sumRao: dataframe. Empirical estimates obtained after running the function FD_Rao.
  • sumFD: dataframe. Empirical estimates obtained after running the function FD_metrics.
  • plot.window: TRUE or FALSE if the plots will appear in the Rstudio plot window. Default TRUE.
  • cols: colour palette (e.g., rainbow, viridis, plasma). Default viridis.
  • save.plot: TRUE or FALSE. Default TRUE.
  • add.labs: TRUE or FALSE. It adds the label corresponding to each life-mode or ecocode. Default FALSE.
  • ext: extension of the plot to be saved. Only an extension admitted by ggplot2::ggsave (e.g., ".svg", ".png"). Default ".png".

FD_plotFS(dfFD=data2, sumRao=RaoSummary, sumFD=FDSummary, plot.window=FALSE, cols= viridis, save.plot= FALSE, add.labs=F, ext=".png" ) #plotsFS is a list

plot(plotsFS[[5]]) # to visualise the plot for the fifth time bin. 'plotsFS' is the list containing all the plots

The function returns a list named plotsFS with a plot for each time bin to your global environment. If plot.window is TRUE the plot will appear in the IDE plot window. If save.plot is TRUE plots will be saved with a ".png" (by default) extension in your wd.

Comparing the observed metrics against null models

Function 6 FD_nullCom()

This function simmulates random communities from a resampling of the abundances in the empirical data. The function have the following arguments:

  • df: dataframe. Input dataframe with rows indicating time bins and columns indicating each life-mode or ecocode. The df values are estimates of abundance. This is your original dataframe, the same used by DF_fd.
  • nNull: numeric. Number of null replicates (communities) to compute. Default 10.
  • subcat: numeric vector. The number of subcategories that each trait has. Its length must be equal that the number of traits of each life-mode.
  • type: character.Type of randomisation. It allows one of the following options Default “all,” Default “col-wise,” Default “row-wise.” Default “all.”
  • call.nullsummary:TRUE or FALSE. Do you want to call the FD_nullsummary function of this package and summarise the output? Default FALSE.
  • plot.null: TRUE or FALSE. It works ONLY if call.nullsummary is TRUE and it passes arguments to the function FD_nullPlot. Default FALSE.

data1[1:5,1:5] # original dataframe, it is not a functional diversity dataframe
#>            111     115    261 266    311
#> -270.55 0.0000 10.5002 1.9364   0 0.4209
#> -266.95 0.0000  8.2779 1.1165   0 0.3732
#> -262.45 0.0000  2.0814 2.0708   0 1.1786
#> -257.1  0.1334  9.3056 1.5605   0 0.8339
#> -253.3  0.0000  8.4060 0.1980   0 0.7890

FD_nullCom(df = data1, nNull= 50, subcat = c(6, 6, 6), type= "all", call.nullsummary = FALSE, plot.null = FALSE) 
# Note: in this case it doesn't summarise nor plot the data.

The function returns to the Global Environment two dataframes null_Rao and null_FDmetrics with the estimated functional diversity metrics for each replicate calculated by the function FD_rao and FD_metrics. If call.nullsummary is TRUE, the function FD_nullsummary is called internally and returns to the environment two dataframes summarynullrao and summarynullFD. Finally, if plot.null is TRUE, the function FD_plotnull is called internally returning the respective plots.

Function 7 FD_nullSummary()

Now, it is necessary tu summarise the data estimated for the null communities. This function summarises the dataframes returned by the function FD_nullCom, it reports the mean, variance, and confidence intervals. This function can be called directly from FD_nullCom.

The arguments of the function are:

  • nullrao: dataframe obtained after computing the function FD_nullCom.
  • nullFD: dataframe obtained after computing the function FD_nullCom.
  • nNull: numeric. The number of null replicates. This must be the same that those in FD_nullCom.
  • plot.null: TRUE or FALSE. It works ONLY if call.nullsummary is TRUE and it passes arguments to the function FD_nullSummary. Default FALSE.

FD_nullSummary(nullrao = null_Rao, nullFD = null_FDmetrics, nNull = 500, plot.null = FALSE)

head(summarynullRao)
#>    mSimpson   mFunRao mFunRedun   vSimpson     vFunRao   vFunRedun Simpson.ic95
#> 1 0.7788613 0.4024130 0.3764483 0.01069475 0.002516335 0.003325138   0.02873446
#> 2 0.7537277 0.3881687 0.3655590 0.01489938 0.003558833 0.004425306   0.03391578
#> 3 0.7522602 0.3893336 0.3629266 0.02088014 0.005373306 0.005583541   0.04014990
#> 4 0.8027511 0.4113600 0.3913911 0.01102061 0.002845760 0.003085288   0.02916894
#> 5 0.7769221 0.3955879 0.3813342 0.01335602 0.003563019 0.003805717   0.03211118
#> 6 0.7670387 0.3901530 0.3768858 0.01264526 0.003395718 0.003975223   0.03124508
#>    Simpson.ic5 FunRao.ic95   FunRao.ic5 FunRed.ic95   FunRed.ic5    Time
#> 1 0.0009175574  0.01393805 0.0004450740  0.01602221 0.0005116261 -270.55
#> 2 0.0010830089  0.01657569 0.0005292998  0.01848372 0.0005902277 -266.95
#> 3 0.0012820785  0.02036754 0.0006503823  0.02076216 0.0006629836 -262.45
#> 4 0.0009314313  0.01482234 0.0004733115  0.01543354 0.0004928284  -257.1
#> 5 0.0010253837  0.01658543 0.0005296110  0.01714099 0.0005473513  -253.3
#> 6 0.0009977272  0.01619137 0.0005170276  0.01751856 0.0005594080  -251.9

head(summarynullFD)
#>       mFEve     mFDiv    mFSpe    mFRic mchull_PC12 mchull_PC13       vFEve
#> 1 0.5699521 0.8329292 1.626785 32.15979    12.09163    11.16489 0.009073307
#> 2 0.5793254 0.8278448 1.648642 31.89564    11.97278    11.09758 0.007737085
#> 3 0.5892779 0.7949591 1.538860 31.74253    12.05164    10.89013 0.009390475
#> 4 0.5808239 0.8235442 1.599254 31.82251    11.97105    10.88611 0.008343250
#> 5 0.5624262 0.8215595 1.579585 31.20177    12.01498    10.97135 0.011924272
#> 6 0.5927330 0.8390365 1.621867 31.70568    11.99587    10.93576 0.009790396
#>         vFDiv      vFSpe    vFRic vchull_PC12 vchull_PC13  FEve.ic95
#> 1 0.004590299 0.03269750 8.290243   0.3654437   0.3968018 0.02646675
#> 2 0.010891145 0.06014993 7.192609   0.2853010   0.3865641 0.02444029
#> 3 0.009503874 0.05582109 7.310506   0.3025671   0.4850790 0.02692536
#> 4 0.004992591 0.02927012 7.093035   0.3062195   0.3458495 0.02537964
#> 5 0.008901111 0.03069958 7.517781   0.2930610   0.3939465 0.03034126
#> 6 0.007102806 0.03749210 7.179854   0.3334663   0.4564898 0.02749273
#>       FEve.ic5  FDiv.ic95     FDiv.ic5  FSpe.ic95    FSpe.ic5 FRic.ic95
#> 1 0.0008451440 0.01882514 0.0006011300 0.05024294 0.001604373 0.8000210
#> 2 0.0007804347 0.02899710 0.0009259439 0.06814520 0.002176033 0.7451796
#> 3 0.0008597886 0.02708745 0.0008649644 0.06564731 0.002096269 0.7512620
#> 4 0.0008104301 0.01963273 0.0006269182 0.04753681 0.001517960 0.7400035
#> 5 0.0009688663 0.02621440 0.0008370859 0.04868374 0.001554584 0.7618379
#> 6 0.0008779061 0.02341708 0.0007477611 0.05380066 0.001717979 0.7445186
#>     FRic.ic5 chull_PC12.ic95 chull_PC12.ic5 chull_PC13.ic95 chull_PC13.ic5
#> 1 0.02554651       0.1679685    0.005363622       0.1750268    0.005589008
#> 2 0.02379530       0.1484121    0.004739141       0.1727542    0.005516438
#> 3 0.02398952       0.1528370    0.004880437       0.1935192    0.006179512
#> 4 0.02363001       0.1537568    0.004909807       0.1634035    0.005217849
#> 5 0.02432723       0.1504169    0.004803159       0.1743959    0.005568863
#> 6 0.02377419       0.1604515    0.005123584       0.1877298    0.005994645
#>      Time
#> 1 -270.55
#> 2 -266.95
#> 3 -262.45
#> 4  -257.1
#> 5  -253.3
#> 6  -251.9

Function 8 FD_nullPlot()

Finally, a useful tool is to visualise the empirical trajectory in the empirical functional diversity estimates in contrast with the obtained by the null models and randomisation of the abundance. This function plots the summary data returned by the function FD_nullSummary and the data returned by FD_metrics and FD_Rao. This function can be called directly from FD_nullcom and from FD_nullsummary.
The arguments of the function are:

  • d.rao: a dataframe obtained after running the function FD_nullSummary.
  • d.FD: a dataframe obtained after running the function FD_nullSummary.
  • sumRao: dataframe. Empirical estimates obtained after running the function FD_Rao.
  • sumFD: dataframe. Empirical estimates obtained after running the function FD_metrics.
  • plotRao: TRUE or FALSE. Do wou want to plot the Rao’s, Simpson’s and functional redundancy estimates with the null models. Default TRUE.
  • saveRao: TRUE or FALSE. Do wou want to save the Rao’s, Simpson’s and functional redundancy estimates with the null models. Default TRUE.
  • plotFRic: TRUE or FALSE. Do wou want to plot the functional richness (FRic) estimates with the null models? Default TRUE.
  • saveFRic: TRUE or FALSE. Do wou want to save the Rao’s, Simpson’s and functional redundancy estimates with the null models. Default TRUE.

FD_nullPlot(d.rao = summarynullRao, d.FD = summarynullFD, sumRao = RaoSummary, sumFD = FDSummary, plotRao = TRUE, saveRao = FALSE, plotFRic = TRUE, saveFRic = FALSE)

The function plot a named list with each plot made with ggplot2 and prints in the plot window (if plotRao and/or plotFRic are TRUE); and will save the corresponding plots in png format in the wd.

Literature cited

Rao, C. Radhakrishna. 1982. “Diversity and Dissimilarity Coefficients: A Unified Approach.” Theoretical Population Biology 21 (1): 24–43. https://doi.org/10.1016/0040-5809(82)90004-1.
Villéger, Sébastien, Norman W. H. Mason, and David Mouillot. 2008. “New Multidimensional Functional Diversity Indices for a Multifaceted Framework in Functional Ecology.” Ecology 89 (8): 2290–2301. https://doi.org/10.1890/07-1206.1.