Computes Hill numbers of order q for each site from the observed
relative abundances. Order 0 is species richness, order 1 is the
exponential of Shannon entropy and order 2 is the inverse Simpson index.
Arguments
- data
A data frame in long format, with one row per record.
- site, species
<
tidy-select> The column holding site identifiers and the column holding species names.- abundance
<
tidy-select> The column holding counts. IfNULL(the default), a column calledabundanceis used when present, otherwise every row counts as one individual.- q
Orders of diversity, non-negative numbers.
- type
Diversity dimension:
"TD"(taxonomic, the default),"PD"(phylogenetic, needstree) or"FD"(functional, needsdistance). Give several, such asc("TD", "PD"), or"all"for all three, to analyse the dimensions together: the results are stacked in one tibble with atypecolumn, andautoplot()shows them side by side. All three are Hill numbers of the same orderq, in units of effective numbers of species (Chao, Chiu and Jost 2014), and reproduce iNEXT.3D.- tree
For
type = "PD", a rooted ape::phylo tree with branch lengths whose tip labels include every species.- reftime
For
type = "PD", the reference time (tree depth) at which diversity is measured. Defaults to the age of the root of the tree pruned to the species indata.- pd_unit
For
type = "PD","mean"(the default) divides phylogenetic diversity byreftime, giving the effective number of lineages on the same scale as species;"total"gives effective total branch length.- distance
For
type = "FD", a species-by-species distance matrix (or stats::dist object) with names matching the species, scaled to lie between 0 and 1, for example from Gower distances of traits.- tau
For
type = "FD", the distance threshold below which species are treated as functionally identical. Defaults to the mean distance between two individuals in the pooled data. Use"auc"to integrate over all thresholds from 0 to 1 (Chao et al. 2019).- unit
For incidence data, the column naming the sampling unit (a trap, bait, plot or survey day) in which each species was detected. Each site is then described by the number of units in which each species was found and the number of units sampled, and every estimate is incidence-based (Chao et al. 2014), for TD, PD and FD alike. Leave
NULLfor abundance data.- n_units
For incidence data, a column giving the number of units sampled at each site, constant within a site. Use it when some units detected no species and so do not appear in the data. By default the number of distinct units in the data is used.
- .by
<
tidy-select> Optional grouping columns, kept in the output. Grouped data frames are also respected.
Value
A tibble with the grouping columns, the site column, q,
n (number of individuals, or of sampling units for incidence data)
and diversity. Phylogenetic and
functional results also have type and reftime or tau.
References
Hill, M. O. (1973). Diversity and evenness: a unifying notation and its consequences. Ecology, 54, 427-432. doi:10.2307/1934352
Chao, A., Chiu, C.-H. and Jost, L. (2014). Unifying species diversity, phylogenetic diversity, functional diversity, and related similarity and differentiation measures through Hill numbers. Annual Review of Ecology, Evolution, and Systematics, 45, 297-324. doi:10.1146/annurev-ecolsys-120213-091540
Chao, A., Chiu, C.-H., Villeger, S., Sun, I.-F., Thorn, S., Lin, Y.-C., Chiang, J.-M. and Sherwin, W. B. (2019). An attribute-diversity approach to functional diversity, functional beta diversity, and related (dis)similarity measures. Ecological Monographs, 89, e01343. doi:10.1002/ecm.1343
Examples
div_hill(png_ants, .by = season)
#> # A tibble: 30 x 5
#> season site q n diversity
#> <chr> <chr> <dbl> <dbl> <dbl>
#> 1 dry MW0200 0 47 16
#> 2 dry MW0200 1 47 12.3
#> 3 dry MW0200 2 47 9.91
#> 4 wet MW0200 0 76 21
#> 5 wet MW0200 1 76 10.9
#> 6 wet MW0200 2 76 6.99
#> 7 dry MW0700 0 23 15
#> 8 dry MW0700 1 23 11.8
#> 9 dry MW0700 2 23 8.67
#> 10 wet MW0700 0 58 28
#> # i 20 more rows
# Grouped data frames work too
png_ants |>
dplyr::group_by(season) |>
div_hill(q = c(0, 0.5, 1, 2))
#> # A tibble: 40 x 5
#> season site q n diversity
#> <chr> <chr> <dbl> <dbl> <dbl>
#> 1 dry MW0200 0 47 16
#> 2 dry MW0200 0.5 47 14.0
#> 3 dry MW0200 1 47 12.3
#> 4 dry MW0200 2 47 9.91
#> 5 wet MW0200 0 76 21
#> 6 wet MW0200 0.5 76 15.2
#> 7 wet MW0200 1 76 10.9
#> 8 wet MW0200 2 76 6.99
#> 9 dry MW0700 0 23 15
#> 10 dry MW0700 0.5 23 13.5
#> # i 30 more rows
# Incidence data: each bait is a sampling unit, 60 baits per site
div_hill(png_ants, unit = bait, n_units = baits, .by = season)
#> # A tibble: 30 x 5
#> season site q n diversity
#> <chr> <chr> <dbl> <int> <dbl>
#> 1 dry MW0200 0 60 16
#> 2 dry MW0200 1 60 12.3
#> 3 dry MW0200 2 60 9.91
#> 4 wet MW0200 0 60 21
#> 5 wet MW0200 1 60 10.9
#> 6 wet MW0200 2 60 6.99
#> 7 dry MW0700 0 60 15
#> 8 dry MW0700 1 60 11.8
#> 9 dry MW0700 2 60 8.67
#> 10 wet MW0700 0 60 28
#> # i 20 more rows
# TD, PD and FD together, here for a functional distance matrix only
d <- as.matrix(stats::dist(c(s1 = 0, s2 = 0.1, s3 = 0.5, s4 = 1)))
toy <- data.frame(
site = rep(c("a", "b"), each = 4), species = paste0("s", 1:4),
n = c(10, 5, 2, 1, 3, 3, 1, 1)
)
div_hill(toy, abundance = n, type = c("TD", "FD"), distance = d)
#> # A tibble: 12 x 6
#> site q n diversity type tau
#> <chr> <dbl> <dbl> <dbl> <fct> <dbl>
#> 1 a 0 18 4 TD NA
#> 2 a 1 18 2.97 TD NA
#> 3 a 2 18 2.49 TD NA
#> 4 b 0 8 4 TD NA
#> 5 b 1 8 3.51 TD NA
#> 6 b 2 8 3.2 TD NA
#> 7 a 0 18 3.23 FD 0.245
#> 8 a 1 18 2.07 FD 0.245
#> 9 a 2 18 1.71 FD 0.245
#> 10 b 0 8 3.26 FD 0.245
#> 11 b 1 8 2.48 FD 0.245
#> 12 b 2 8 2.09 FD 0.245