Package {ascent}

Baseline Functional Topology of Entities

Description

Calculates the absolute functional centroid (CWM), functional dispersion (FDis), and convex hull volume (FRic) for each community or site independently.

Usage

asc_baseline(
  traits,
  abund,
  dist_method = "gower",
  dim_retention = c("variance", "broken_stick"),
  var_tol = 0.8,
  na.rm = TRUE
)

Arguments

Value

An S3 object of class ascfcd_base.

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85)
)
rownames(traits) <- paste0("Sp", 1:5)

abund <- rbind(
  Forest = c(0,  5, 25, 20, 10),
  Field  = c(30, 20, 10,  0,  0)
)

base <- asc_baseline(traits, abund, dist_method = "euclidean")
summary(base)

Identify Functional Entities (Species Clustering)

Description

Clusters species into discrete functional entities based on shared morphological, physiological, or ecological traits.

Usage

asc_entities(
  traits,
  dist_method = "gower",
  hclust_method = "ward.D2",
  k = NULL,
  h = NULL
)

Arguments

Value

An S3 object of class ascfcd_entities.

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85),
  Diet = factor(c(0, 1, 1, 1, 0))
)
rownames(traits) <- paste0("Sp", 1:5)

ent <- asc_entities(traits, k = 2)
summary(ent)

Multi-Level Null Models for Multidimensional Functional Shifts

Description

Evaluates the statistical significance of functional shifts using three null models: Structural (Curveball), Quantitative (SAD Reshuffle), and Identity (Trait Shuffle).

Usage

asc_null(x, n_perm = 999, seed = NULL)

Arguments

Value

The original object with an appended null_models data frame.

Note

Model A (Structural): After curveball permutation, all species present receive uniform relative abundance (1/S_local). This means the null distribution for FDis conflates the effect of taxonomic identity with the assumption of equitability. The SES tests whether the observed shift is extreme given random species composition, not given random composition with the observed SAD.

Model B (Quantitative): Because incidence is held fixed, the convex hull is invariant across permutations. Delta FRic under Model B is reported as NA (not applicable), not zero.

Model C (Identity): Statistical power is limited when the regional species pool is small (< 15 species). With few species, the number of unique trait permutations is small, reducing the resolution of the null distribution. Consider increasing n_perm and interpreting marginal p-values (0.05 < p < 0.10) with caution.

Scope: When multiple contrasts are evaluated simultaneously, the curveball operates on the full stacked matrix, assuming a shared regional species pool. For biogeographically independent sites, run asc_null() on each contrast separately.

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85),
  Diet = factor(c(0, 1, 1, 1, 0))
)
rownames(traits) <- paste0("Sp", 1:5)

abund <- rbind(
  Reference = c(0, 10, 25, 20, 5),
  Impacted  = c(30, 15,  5,  0, 0)
)

res <- asc_paired(
  traits, abund,
  sites = c("S1", "S1"),
  time = c("Reference", "Impacted"),
  ref_time = "Reference"
)
res <- asc_null(res, n_perm = 99, seed = 42)
res$null_models

Paired Functional Multidimensional Restructuring

Description

Calculates centroid displacement (Layer 1), dispersion shift (Layer 2 - FDis), and volume shift (Layer 3 - FRic) between paired states.

Usage

asc_paired(
  traits,
  abund,
  sites,
  time,
  ref_time,
  dist_method = "gower",
  dim_retention = c("variance", "broken_stick"),
  var_tol = 0.8,
  na.rm = TRUE
)

Arguments

Value

An S3 object of class ascfcd.

Note

Normalization: Delta FDis and Delta FRic are absolute differences, not normalized by the regional pool. Values are not directly comparable across studies with different species pools or trait scales. Only rDelta_C (position) is normalized by Dmax_regional.

FRic = NA: When a community has fewer species than retained PCoA axes, the convex hull is geometrically undefined and FRic is set to NA, which propagates to Delta_FRic.

Temporal replicates: When multiple rows share the same site and temporal state (e.g., three reference plots), their relative abundances are averaged (column means) before computing the centroid. This is equivalent to treating replicates as a single pooled community. Intra-state variability is not propagated to downstream metrics.

Examples

# Simulate deforestation impact on a bird community
traits <- data.frame(
  Mass  = c(15, 30, 60, 150, 400),
  Beak  = c(10, 15, 28,  45,  85),
  Diet  = factor(c(0, 1, 1, 1, 0))
)
rownames(traits) <- paste0("Sp", 1:5)

abund <- rbind(
  Reference = c(0, 10, 25, 20, 5),
  Impacted  = c(30, 15,  5,  0, 0)
)

res <- asc_paired(
  traits, abund,
  sites = c("Site1", "Site1"),
  time = c("Reference", "Impacted"),
  ref_time = "Reference"
)
summary(res)

Pairwise Functional Spatial Divergence

Description

Calculates spatial functional divergence across three layers: position (Delta C), dispersion (FDis), and volume (FRic).

Usage

asc_pairwise(
  traits,
  abund,
  dist_method = "gower",
  dim_retention = c("variance", "broken_stick"),
  var_tol = 0.8,
  na.rm = TRUE
)

Arguments

Value

An S3 object of class ascfcd_pw.

Note

Leverage direction: In pairwise mode, leverage is computed from Community_A toward Community_B. Reversing the pair order reverses the leverage signs. The direction is determined by alphabetical ordering of community names.

Normalization: Delta FDis and Delta FRic are absolute differences (see asc_paired for details).

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85)
)
rownames(traits) <- paste0("Sp", 1:5)

abund <- rbind(
  Forest  = c(0,  5, 25, 20, 10),
  Field   = c(30, 20, 10,  0,  0),
  Wetland = c(5, 10, 15, 15,  5)
)

res_pw <- asc_pairwise(traits, abund, dist_method = "euclidean")
summary(res_pw)

Extract Functional Transitions and Species Leverage

Description

Calculates the multidimensional Functional Leverage of each species, quantifying their direct contribution to the positional shift (Layer 1 - Delta C) of the ecosystem.

Usage

asc_transitions(x, ...)

Arguments

Value

An S3 object of class ascfcd_transitions.

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85)
)
rownames(traits) <- paste0("Sp", 1:5)

abund <- rbind(
  Ref = c(0, 10, 25, 20, 5),
  Imp = c(30, 15,  5,  0, 0)
)

res <- asc_paired(
  traits, abund,
  sites = c("S1", "S1"),
  time = c("R", "I"), ref_time = "R",
  dist_method = "euclidean"
)
drivers <- asc_transitions(res)
drivers$S1$species_leverage

Assess Functional Space Quality

Description

Diagnostic tool to evaluate the quality of the PCoA-based functional space constructed from a trait matrix. Intended for use before running core analyses (asc_paired, asc_pairwise, etc.) to identify potential distortion from negative eigenvalues or excessive dimensionality reduction.

Usage

assess_functional_space(
  traits,
  dist_method = "gower",
  dim_retention = c("variance", "broken_stick"),
  var_tol = 0.8
)

Arguments

Details

The Gower distance is not strictly Euclidean, which means PCoA may produce negative eigenvalues. This function reports the full eigenvalue spectrum and computes a quality index so users can decide whether the functional space is an adequate representation of the original distance matrix.

A quality below 0.80 indicates that negative eigenvalues represent more than 20\

• Reviewing the trait data for problematic variables.

• Applying a Cailliez or Lingoes correction to the distance matrix before ordination.

• Using a different distance metric (e.g., "euclidean" for purely continuous traits).

Value

A list of class ascfcd_space with:

quality

Numeric. PCoA quality index (sum(positive_eig) / sum(abs(all_eig))). Values above 0.80 are generally acceptable.

n_species

Integer. Number of species in the trait matrix.

n_traits

Integer. Number of traits.

k_retained

Integer. Number of PCoA axes retained.

var_retained

Numeric. Cumulative variance explained by retained axes.

axis_var

Numeric vector. Relative variance per retained axis.

n_neg_eigenvalues

Integer. Count of negative eigenvalues.

neg_eigenvalue_pct

Numeric. Percentage of total absolute eigenvalue represented by negative eigenvalues.

eigenvalues

Numeric vector. All raw eigenvalues from PCoA.

Examples

traits <- data.frame(
  Mass = c(15, 30, 60, 150, 400),
  Beak = c(10, 15, 28,  45,  85),
  Diet = factor(c(0, 1, 1, 1, 0))
)
rownames(traits) <- paste0("Sp", 1:5)

diag <- assess_functional_space(traits)
diag

Plot Multidimensional Functional Restructuring

Description

Visualizes the functional trajectory (Centroid shift) and volume shift (Convex Hull) of a specific site/contrast in the PCoA space, alongside the species leverage.

Usage

## S3 method for class 'ascfcd'
plot(x, contrast, type = c("both", "pcoa", "leverage"), n_sp = 10, ...)

Arguments

Value

A ggplot object (or patchwork object if type = "both").

Plot Functional Entities Dendrogram

Description

Plots the hierarchical clustering dendrogram of the functional entities.

Usage

## S3 method for class 'ascfcd_entities'
plot(x, ...)

Arguments

Value

No return value, called for side effects (plots a dendrogram).

Plot Pairwise Functional Spatial Divergence

Description

Visualizes spatial functional restructuring (Centroid & Hull) between two communities.

Usage

## S3 method for class 'ascfcd_pw'
plot(x, contrast, type = c("both", "pcoa", "leverage"), n_sp = 10, ...)

Arguments

Value

A ggplot object.

Plot Functional Leverage

Description

Visualizes the top species driving functional centroid displacement.

Usage

## S3 method for class 'ascfcd_transitions'
plot(x, contrast, n_sp = 10, ...)

Arguments

Value

A ggplot object.

Summary for Paired Functional Centroid Displacement

Description

Provides a concise, multi-layer overview of the paired ASC-CFD analysis, including null models and top functional drivers.

Usage

## S3 method for class 'ascfcd'
summary(object, ...)

Arguments

Value

Invisibly returns a data frame with the displacement metrics.

Summary for Baseline Functional Entities

Description

Provides an overview of the baseline functional topology of the evaluated entities.

Usage

## S3 method for class 'ascfcd_base'
summary(object, ...)

Arguments

Value

Invisibly returns the entities results data frame.

Summary for Functional Entities Classification

Description

Provides an overview of the species clustering into functional entities.

Usage

## S3 method for class 'ascfcd_entities'
summary(object, ...)

Arguments

Value

Invisibly returns the classification data frame.

Summary for Pairwise Functional Spatial Divergence

Description

Provides a comprehensive overview of the spatial network ASC-CFD analysis.

Usage

## S3 method for class 'ascfcd_pw'
summary(object, ...)

Arguments

Value

Invisibly returns the pairwise results data frame.

Summary for Functional Leverage Analysis

Description

Provides an overview of the species leverage for each contrast.

Usage

## S3 method for class 'ascfcd_transitions'
summary(object, n_sp = 5, ...)

Arguments

Value

Invisibly returns the object.