Diversity Profile

Compute Hill numbers across a continuous range of diversity orders (q), producing a diversity profile for each site and the regional pool.

Usage

diversityProfile(
  x,
  q = seq(0, 3, by = 0.1),
  type = c("both", "per_site", "regional"),
  traits = NULL,
  tree = NULL,
  dist_method = c("euclidean", "gower"),
  normalize = TRUE,
  coords = NULL
)

diversityProfilePhylo(
  x,
  tree,
  q = seq(0, 3, by = 0.1),
  type = c("both", "per_site", "regional"),
  coords = NULL
)

diversityProfileFunc(
  x,
  traits,
  q = seq(0, 3, by = 0.1),
  type = c("both", "per_site", "regional"),
  dist_method = c("euclidean", "gower"),
  normalize = TRUE,
  coords = NULL
)

Arguments

x: A site-by-species matrix (abundance data). Column names must match trait row names / tree tip labels when traits / tree is supplied.
q: Numeric vector. Orders of diversity to evaluate. Default seq(0, 3, by = 0.1).
type: Character. What to compute: "per_site" (per-site profiles), "regional" (pooled gamma), or "both" (default).
traits: Optional species-by-traits data.frame (row names matching species). When supplied, functional Hill numbers (Leinster & Cobbold 2012) are computed.
tree: Optional ape::phylo object. When supplied, phylogenetic Hill numbers (Chao et al. 2010) are computed. Supply at most one of traits or tree.
dist_method: Character. Trait distance for the functional profile: "euclidean" (default) or "gower". Ignored unless traits is supplied.
normalize: Logical. Normalize trait distances to [0, 1]? Default TRUE. Ignored unless traits is supplied.
coords: Optional data.frame with columns x and y for spatial mapping. When provided, enables plot(type = "map").

Value

An object of class spacc_profile containing:

per_site: Matrix of per-site diversity (sites x q values), or NULL
regional: Named numeric vector of gamma diversity per q, or NULL
q: Vector of diversity orders used
coords: Coordinates if provided
n_sites: Number of sites
n_species: Number of species

Details

A diversity profile plots effective number of species as a function of the order q. The key property is that Hill numbers are non-increasing in q: \(D_q \ge D_{q'}\) for \(q \le q'\).

q = 0: Species richness (insensitive to abundance)
q = 1: Exponential of Shannon entropy (all species weighted equally by their proportional abundance)
q = 2: Inverse Simpson concentration (emphasizes dominant species)
q > 2: Increasingly dominated by common species

Supplying traits computes functional Hill numbers via a trait-similarity matrix (Leinster & Cobbold 2012); supplying tree computes phylogenetic Hill numbers weighted by branch length (Chao et al. 2010). Both return a spacc_profile whose profile_type records which was computed.

References

Leinster, T. & Cobbold, C.A. (2012). Measuring diversity: the importance of species similarity. Ecology, 93, 477-489.

Chao, A., Chiu, C.H. & 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.

Examples

species <- matrix(rpois(50 * 30, 2), nrow = 50)
prof <- diversityProfile(species)
print(prof)

# \donttest{
plot(prof)

# Functional profile (pass a species-by-traits data.frame)
colnames(species) <- paste0("sp", 1:30)
traits <- data.frame(size = rnorm(30), row.names = paste0("sp", 1:30))
fp <- diversityProfile(species, traits = traits)
# }