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

Deprecated Functions

Description

Function names of BioFTF 1.x, kept so that existing code still runs. Each function issues a warning and calls its replacement.

Usage

beta(x, n = 101, ...)
beta_plot(x, n = 101, ...)
betaprime(x, n = 101, ...)
betaprime_plot(x, n = 101, ...)
betasecond(x, n = 101, ...)
betasecond_plot(x, n = 101, ...)
curvature(x, n = 101, ...)
curvature_plot(x, n = 101, ...)
radius(x, n = 101, ...)
radius_plot(x, n = 101, ...)
arc(x, n = 101, ...)
area(x, n = 101, ...)
ranking(x, n = 101, ...)

Arguments

Details

In BioFTF 1.x these functions were computed on the Patil-Taillie beta profile over -1 \le \beta \le 1. They now return the corresponding tool for the Hill-number profile over 0 \le q \le 2, so their values differ from those of BioFTF 1.x. The relation between the two profiles is described in hill_profile.

beta masks beta of package base while BioFTF is attached; the Beta function remains available as base::beta.

Value

The value of the replacement function.

See Also

hill_profile, hill_derivative.

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

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

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

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

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")
}