Package 'BioFTF'

Biodiversity Assessment Using Hill-Number Functional Tools

Description

Hill-number diversity profiles are treated as functions of the order $q$ and summarised through functional tools: derivatives, curvature, radius of curvature, arc length, cumulative integral functions, areas, rankings, and biodiversity surfaces over time.

Details

Rows of the input matrix are communities, sites, or time points. Columns are species. Absolute and relative non-negative abundances are both accepted, because every row is rescaled to sum to one.

The main functions are hill_profile for the profiles, hill_derivative, hill_curvature, hill_area, hill_cum, hill_arc and hill_ranking for the functional tools, and hill_surface_plot and hill_surface_compare for static or rotatable three-dimensional surfaces.

Versions 1.x of the package computed the same functional tools on the Patil-Taillie beta profile. The relation between the two profiles is given in hill_profile. The function names of versions 1.x are still available but deprecated; see BioFTF-deprecated.

Author(s)

Fabrizio Maturo, Francesca Fortuna, Tonio Di Battista.

References

Di Battista, T., Fortuna, F. and Maturo, F. (2017). BioFTF: An R package for biodiversity assessment with the functional data analysis approach. Ecological Indicators, 73, 726–732. doi:10.1016/j.ecolind.2016.10.032

Maturo, F. and Di Battista, T. (2018). A functional approach to Hill's numbers for assessing changes in species variety of ecological communities over time. Ecological Indicators, 84, 70–81. doi:10.1016/j.ecolind.2017.08.016

Maturo, F. (2018). Unsupervised classification of ecological communities ranked according to their biodiversity patterns via a functional principal component decomposition of Hill's numbers integral functions. Ecological Indicators, 90, 305–315. doi:10.1016/j.ecolind.2018.03.013

Hill, M. O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54(2), 427–432. doi:10.2307/1934352

Patil, G. P. and Taillie, C. (1982). Diversity as a concept and its measurement. Journal of the American Statistical Association, 77(379), 548–561. doi:10.1080/01621459.1982.10477845

---

Data Summaries and Wrappers

Description

Relative abundances, species summaries, a wrapper that returns all the functional tools, and a wrapper that saves the profile plots to a PDF file.

Usage

datirel(x)
summary_species(x)
summary_species_relative(x)
alltools(x, from = 0, to = 2, n = 101)
export_plots(x, file, from = 0, to = 2, n = 101)

Arguments

x	A numeric matrix or data frame of non-negative abundances. Rows are communities, sites, or time points; columns are species.
from, to	Finite lower and upper endpoints of the grid of orders.
n	Number of equally spaced orders.
file	Path of the PDF file to create.

Value

datirel returns the matrix of relative abundances. summary_species returns a data frame with richness, total abundance, and smallest and largest abundance of each community, zeros included; summary_species_relative returns the same summaries for relative abundances. alltools returns a list with the relative abundances, the species summary, and the output of hill_profile, hill_first_derivative, hill_second_derivative, hill_curvature, hill_radius, hill_area, hill_cum, hill_arc, and hill_ranking. export_plots writes one page for each of profile, first derivative, second derivative, curvature, radius of curvature, and cumulative integral function, and invisibly returns file.

Examples

x <- matrix(c(3, 5, 5, 2, 1,
              2, 6, 8, 5, 1,
              7, 3, 2, 1, 0),
            nrow = 3, byrow = TRUE)
datirel(x)
summary_species(x)
summary_species_relative(x)

res <- alltools(x, from = 0, to = 5, n = 251)
names(res)
res$ranking

out <- file.path(tempdir(), "BioFTF-plots.pdf")
export_plots(x, file = out)
unlink(out)

---

Functional Tools Derived from Hill-Number Profiles

Description

Derivatives, curvature, radius of curvature, cumulative integral functions, areas, arc lengths, rankings, and changes between consecutive rows, all computed from Hill-number profiles.

Usage

hill_derivative(x, order = 1, from = 0, to = 2, n = 101,
                domain = NULL, allow_negative = FALSE)
hill_first_derivative(x, from = 0, to = 2, n = 101,
                      domain = NULL, allow_negative = FALSE)
hill_second_derivative(x, from = 0, to = 2, n = 101,
                       domain = NULL, allow_negative = FALSE)
hill_curvature(x, from = 0, to = 2, n = 101,
               domain = NULL, allow_negative = FALSE)
hill_radius(x, from = 0, to = 2, n = 101,
            domain = NULL, allow_negative = FALSE)
hill_area(x, from = 0, to = 2, n = 101, domain = NULL,
          baseline = 0, allow_negative = FALSE)
hill_cum(x, from = 0, to = 2, n = 101, domain = NULL,
         baseline = 0, allow_negative = FALSE)
hill_arc(x, from = 0, to = 2, n = 101,
         domain = NULL, allow_negative = FALSE)
hill_ranking(x, from = 0, to = 2, n = 101, domain = NULL,
             baseline = 0, allow_negative = FALSE)
hill_total_change(x, from = 0, to = 2, n = 101, domain = NULL,
                  baseline = 0, allow_negative = FALSE)
hill_derivative_plot(x, order = 1, from = 0, to = 2, n = 101,
                     domain = NULL, allow_negative = FALSE,
                     legend = "bottomright", ...)
hill_curvature_plot(x, from = 0, to = 2, n = 101,
                    domain = NULL, allow_negative = FALSE,
                    legend = "topright", ...)
hill_radius_plot(x, from = 0, to = 2, n = 101,
                 domain = NULL, allow_negative = FALSE,
                 legend = "topleft", ...)
hill_cum_plot(x, from = 0, to = 2, n = 101, domain = NULL,
              baseline = 0, allow_negative = FALSE,
              legend = "topleft", ...)

Arguments

x	A numeric matrix or data frame of non-negative abundances. Rows are communities, sites, or time points; columns are species.
order	Derivative order, 1 or 2.
from, to	Finite lower and upper endpoints of the grid of orders.
n	Number of equally spaced orders used when domain = NULL.
domain	Optional numeric vector of finite orders. Areas, cumulative integrals, and arc lengths require at least two strictly increasing values.
baseline	Constant subtracted from the profile before integration. With baseline = 1, the smallest value a Hill number can take, the area of a community with a single species is zero.
allow_negative	Logical. If FALSE (default), negative orders raise an error. See hill_profile.
legend	Position of the legend, as accepted by legend, or NULL for no legend.
...	Further arguments passed to matplot. hill_radius_plot uses a logarithmic vertical axis.

Details

Derivatives. First and second derivatives are analytical. Writing $L(q) = \log \sum_i p_i^q$ and $g(q) = L(q)/(1 - q)$, the Hill number is $D = \exp(g)$, so that $D' = D g'$ and $D'' = D (g'^2 + g'')$. The derivatives of $L$ are the mean and the variance of $\log p_i$ under the weights $p_i^q / \sum_j p_j^q$. Near $q = 1$, where the closed form is numerically unstable, a Taylor expansion is used. The derivatives therefore do not depend on the spacing of the grid.

Curvature and radius. The curvature is $|D''| / (1 + D'^2)^{3/2}$ and the radius of curvature is its reciprocal. Where the curvature is numerically zero (below $10^{-8}$), as for a community whose species are equally abundant or far along the flat tail of a profile, the radius is returned as NA.

Area and cumulative integral. hill_cum returns $\int_{q_1}^{q} (D(u) - b)\,du$, with $b$ the baseline, at each order of the grid, and hill_area its value at the last order. Both use the trapezoidal rule, whose error decreases with the square of the grid spacing. With the default n = 101 the relative error of the area is of order $10^{-4}$ on $[0, 2]$ and grows with wider domains, so n should be increased together with to.

Arc length. hill_arc returns the length of the polygonal line through the profile. It is bounded below by to - from, attained by a flat profile. The arc length depends on the units of both axes.

Ranking. hill_ranking reports the Hill numbers of order 0, 1, and 2 together with area and arc length. area_rank is 1 for the largest area. arc_rank is 1 for the shortest arc, that is, for the flattest profile; it orders communities by how little the profile changes along the domain and is not a ranking by diversity. A larger area does not imply that one profile lies above the other at every order: when two profiles cross, the communities are not ordered in an intrinsic sense and the area ranking depends on the chosen domain. As to increases, the area is progressively dominated by $D(\infty) = 1/\max_i p_i$.

Change. hill_total_change compares the area of each row with the area of the previous one, which is meaningful when rows are ordered, for instance in time.

Value

hill_derivative, hill_first_derivative, hill_second_derivative, hill_curvature, hill_radius, and hill_cum return matrices with orders in rows and communities in columns; the exact orders are stored in the attribute "q". hill_area and hill_arc return one-column data frames with one row per community. hill_ranking returns a data frame with columns richness, shannon, simpson, hill_area, area_rank, arc_length, and arc_rank. hill_total_change returns a data frame with columns from, to, area_from, area_to, absolute_change, and relative_change. Plot functions return the plotted matrix invisibly.

References

Di Battista, T., Fortuna, F. and Maturo, F. (2017). BioFTF: An R package for biodiversity assessment with the functional data analysis approach. Ecological Indicators, 73, 726–732. doi:10.1016/j.ecolind.2016.10.032

Maturo, F. and Di Battista, T. (2018). A functional approach to Hill's numbers for assessing changes in species variety of ecological communities over time. Ecological Indicators, 84, 70–81. doi:10.1016/j.ecolind.2017.08.016

Maturo, F. (2018). Unsupervised classification of ecological communities ranked according to their biodiversity patterns via a functional principal component decomposition of Hill's numbers integral functions. Ecological Indicators, 90, 305–315. doi:10.1016/j.ecolind.2018.03.013

See Also

hill_profile, hill_surface_plot.

Examples

x <- matrix(c(54, 20, 17,  6,  3,
              25, 25, 25, 25,  0,
              35, 35, 30,  0,  0),
            nrow = 3, byrow = TRUE)
rownames(x) <- c("A", "B", "C")

## Derivatives at selected orders.
hill_first_derivative(x, domain = c(0, 0.5, 1, 2))
hill_second_derivative(x, domain = c(0, 0.5, 1, 2))
head(hill_curvature(x))

## Area, cumulative integral function, arc length, and ranking on [0, 2].
hill_area(x)
tail(hill_cum(x))
hill_arc(x)
hill_ranking(x)

## Area above the minimum value of a Hill number on a wider domain.
hill_area(x, from = 0, to = 10, n = 1001, baseline = 1)

## Plots.
hill_derivative_plot(x, order = 1)
hill_curvature_plot(x)
hill_cum_plot(x, from = 0, to = 10, n = 501)

## Change in area between consecutive surveys.
surveys <- matrix(c(40, 30, 15, 10,  5,
                    35, 30, 18, 12,  5,
                    30, 28, 20, 15,  7,
                    25, 25, 22, 18, 10,
                    20, 24, 24, 20, 12,
                    15, 22, 25, 22, 16),
                  nrow = 6, byrow = TRUE)
rownames(surveys) <- 2018:2023
hill_total_change(surveys)

---

Hill-Number Diversity Profiles

Description

Compute and plot Hill-number diversity profiles for ecological communities, sites, or time points.

Usage

hill_profile(x, from = 0, to = 2, n = 101, domain = NULL,
             allow_negative = FALSE)
hill(x, from = 0, to = 2, n = 101, domain = NULL,
     allow_negative = FALSE)
hill_profile_plot(x, from = 0, to = 2, n = 101, domain = NULL,
                  allow_negative = FALSE, legend = "topright", ...)
hill_plot(x, from = 0, to = 2, n = 101, domain = NULL,
          allow_negative = FALSE, legend = "topright", ...)

Arguments

x	A numeric matrix or data frame of non-negative abundances. Rows are communities, sites, or time points; columns are species. A numeric vector is treated as a single community.
from, to	Finite lower and upper endpoints of the grid of orders. The default is $0 \le q \le 2$. Larger upper endpoints, such as 10, 20, or 100, extend the profile towards the dominance end.
n	Number of equally spaced orders between from and to, used when domain = NULL.
domain	Optional numeric vector of orders at which the profile is evaluated. When supplied, from, to and n are ignored. It may contain a single order and may contain Inf.
allow_negative	Logical. If FALSE (default), negative orders raise an error. See Details.
legend	Position of the legend, as accepted by legend, or NULL for no legend.
...	Further arguments passed to matplot.

Details

For relative abundances $p_1, \dots, p_S$, the Hill number of order $q$ is

$D(q) = \left(\sum_{i: p_i > 0} p_i^q\right)^{1/(1-q)}, \qquad q \ne 1,$

with $D(1) = \exp(-\sum_i p_i \log p_i)$ defined by continuity. $D(0)$ is species richness, $D(1)$ is the exponential of Shannon entropy, $D(2)$ is the inverse Simpson concentration, and $D(\infty) = 1/\max_i p_i$ is the reciprocal of the Berger-Parker dominance. $D(q)$ is expressed in effective numbers of species and is non-increasing in $q$; it is constant only when all the species present are equally abundant.

Range of the order. Most of the variation of the profile lies between $q = 0$ and $q = 2$, which is the default. Increasing to adds the part of the curve that converges to $D(\infty)$; the limit itself is obtained with domain = Inf.

Negative orders. For $q < 0$ the Hill number is larger than species richness, so it can no longer be read as an effective number of species out of the $S$ observed, and it is driven by the smallest positive abundances: $D(-\infty) = 1/\min_i p_i$. These are the abundances most affected by sampling error, and the value changes abruptly when a rare species goes undetected. Negative orders are therefore rejected unless allow_negative = TRUE.

Relation with the Patil-Taillie profile. Versions 1.x of the package used the beta profile of Patil and Taillie (1982),

$\Delta(\beta) = \frac{1 - \sum_i p_i^{\beta + 1}}{\beta}, \qquad -1 \le \beta \le 1,$

which equals $S - 1$ at $\beta = -1$, Shannon entropy as $\beta \to 0$, and the Gini-Simpson index at $\beta = 1$. With $q = \beta + 1$ the two profiles are linked by

$\Delta(\beta) = \frac{1 - D(q)^{-\beta}}{\beta},$

so the interval $[-1, 1]$ for $\beta$ corresponds to $[0, 2]$ for $q$. The two profiles induce the same ordering of communities at each order, but they are measured on different scales: the beta profile is an entropy, whereas the Hill number is its numbers equivalent. Derivatives, curvature, arc length, and areas are not invariant to this transformation, so functional tools computed on the two profiles differ and may rank communities differently.

Value

hill_profile and hill return a matrix with orders in rows and communities in columns. The exact orders are stored in the attribute "q". Plot functions return the profile invisibly.

References

Hill, M. O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54(2), 427–432. doi:10.2307/1934352

Patil, G. P. and Taillie, C. (1982). Diversity as a concept and its measurement. Journal of the American Statistical Association, 77(379), 548–561. doi:10.1080/01621459.1982.10477845

Di Battista, T., Fortuna, F. and Maturo, F. (2017). BioFTF: An R package for biodiversity assessment with the functional data analysis approach. Ecological Indicators, 73, 726–732. doi:10.1016/j.ecolind.2016.10.032

Maturo, F. and Di Battista, T. (2018). A functional approach to Hill's numbers for assessing changes in species variety of ecological communities over time. Ecological Indicators, 84, 70–81. doi:10.1016/j.ecolind.2017.08.016

Maturo, F. (2018). Unsupervised classification of ecological communities ranked according to their biodiversity patterns via a functional principal component decomposition of Hill's numbers integral functions. Ecological Indicators, 90, 305–315. doi:10.1016/j.ecolind.2018.03.013

See Also

hill_derivative, hill_area, hill_surface_plot.

Examples

x <- matrix(c(54, 20, 17,  6,  3,
              25, 25, 25, 25,  0,
              35, 35, 30,  0,  0,
              70, 10, 10,  5,  5),
            nrow = 4, byrow = TRUE)
rownames(x) <- c("A", "B", "C", "D")

## Default grid: 101 orders between 0 and 2.
p <- hill_profile(x)
head(p)

## Selected orders, including the limit for q tending to infinity.
hill_profile(x, domain = c(0, 1, 2, 5, 10, 100, Inf))

## A wider domain.
hill_profile_plot(x, from = 0, to = 10, n = 201)

## Negative orders exceed species richness.
hill_profile(x, domain = c(-1, 0), allow_negative = TRUE)

---

Hill-Number Biodiversity Surfaces

Description

Compute, plot, and compare surfaces obtained by placing the Hill-number profiles of ordered rows side by side. Plots are either rotatable or static.

Usage

hill_surface(x, from = 0, to = 2, n = 101, domain = NULL,
             time = NULL, allow_negative = FALSE)
hill_surface_plot(x, from = 0, to = 2, n = 101, domain = NULL,
                  time = NULL, plot = c("interactive", "static"),
                  allow_negative = FALSE,
                  xlab = "Order q", ylab = "Time",
                  zlab = "Hill number",
                  main = "Hill-number surface",
                  theta = 40, phi = 25, ...)
hill_surface_compare(x, y, from = 0, to = 2, n = 101,
                     domain = NULL, time = NULL,
                     labels = c("Surface 1", "Surface 2"),
                     plot = c("interactive", "static"),
                     mode = c("overlay", "difference"),
                     allow_negative = FALSE,
                     main = "Comparison of Hill-number surfaces",
                     theta = 40, phi = 25, ...)

Arguments

x, y	Numeric abundance matrices or data frames with at least two rows. Rows are ordered time points or sites along a gradient; columns are species. x and y must have the same number of rows; the species may differ.
from, to	Finite lower and upper endpoints of the grid of orders.
n	Number of equally spaced orders used when domain = NULL.
domain	Optional vector of finite, strictly increasing orders.
time	Optional numeric vector of strictly increasing values, one for each row. If NULL, row names are used when they can be read as increasing numbers, for example years; otherwise rows are numbered from 1.
plot	"interactive" (default) returns a plotly surface that can be rotated and zoomed in the viewer or in a browser. "static" draws a perspective plot on the current graphics device.
allow_negative	Logical. If FALSE (default), negative orders raise an error. See hill_profile.
xlab, ylab, zlab, main	Axis labels and title.
theta, phi	Viewing angles of the static plot, as in persp.
labels	Names of the two surfaces.
mode	"overlay" shows the two surfaces together (interactive) or side by side on a common vertical scale (static). "difference" shows the pointwise difference y minus x.
...	Further arguments passed to plot_ly for interactive plots or to persp for static plots.

Details

The surface has the order $q$ on one horizontal axis, time on the other, and the Hill number on the vertical axis. Profiles are observed only at the rows of the data: between two consecutive rows the surface is a linear interpolation drawn for display, not an estimate of diversity at intermediate times.

Interactive plots require the suggested package plotly. In the static plot the colour of each facet follows the height of the surface, and lines mark the observed profiles and a subset of the orders.

Value

hill_surface returns a list with components q (orders), time, and z, a matrix of Hill numbers with orders in rows and time points in columns. With plot = "interactive", hill_surface_plot and hill_surface_compare return a plotly object. With plot = "static", hill_surface_plot invisibly returns the surface, and hill_surface_compare invisibly returns a list with the two surfaces and their difference.

References

Maturo, F. and Di Battista, T. (2018). A functional approach to Hill's numbers for assessing changes in species variety of ecological communities over time. Ecological Indicators, 84, 70–81. doi:10.1016/j.ecolind.2017.08.016

See Also

hill_profile, hill_total_change.

Examples

years <- 2018:2027
x <- matrix(c(40, 35, 15,  5,  5,  0,
              38, 34, 16,  6,  4,  2,
              35, 30, 18,  8,  5,  4,
              30, 28, 20, 10,  7,  5,
              25, 26, 21, 12,  9,  7,
              20, 24, 22, 14, 11,  9,
              16, 21, 23, 16, 13, 11,
              12, 18, 24, 18, 15, 13,
               9, 15, 24, 20, 17, 15,
               6, 12, 23, 22, 19, 18),
            nrow = length(years), byrow = TRUE)
rownames(x) <- years

## A second set of surveys on the same years.
y <- x
y[, 1] <- x[, 1] + 15
y[, 6] <- x[, 6] + 4

## Surface between q = 0 and q = 10.
s <- hill_surface(x, from = 0, to = 10, n = 121)
str(s)

## Static figures.
hill_surface_plot(x, from = 0, to = 10, n = 121, plot = "static")
hill_surface_plot(x, from = 0, to = 10, n = 121, plot = "static",
                  theta = 130, phi = 20,
                  main = "Hill-number surface, 2018-2027")
hill_surface_compare(x, y, from = 0, to = 10, n = 121,
                     labels = c("Area 1", "Area 2"), plot = "static")
hill_surface_compare(x, y, from = 0, to = 10, n = 121,
                     labels = c("Area 1", "Area 2"), plot = "static",
                     mode = "difference")

## Rotatable figures.
if (interactive() && requireNamespace("plotly", quietly = TRUE)) {
  hill_surface_plot(x, from = 0, to = 10, n = 121)
  hill_surface_compare(x, y, from = 0, to = 10, n = 121,
                       labels = c("Area 1", "Area 2"))
  hill_surface_compare(x, y, from = 0, to = 10, n = 121,
                       labels = c("Area 1", "Area 2"),
                       mode = "difference")
}

---