---
title: "ascent: A multi-layer framework for decomposing functional community restructuring into positional, dispersive and boundary components under hierarchical null models."
author: "Rogelio R. Muñoz-Li & Flavia Alvarez-Denis"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ascent: A multi-layer framework for decomposing functional community restructuring into positional, dispersive and boundary components under hierarchical null models.}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.width = 10,
  fig.height = 5.5
)
```

## Part I - Conceptual Framework

The `ascent` package implements the **ASC-CFD** (Assemblage Shift Characterization — Community Functional Dynamics) framework. Communities can exhibit identical levels of functional turnover while following fundamentally different ecological trajectories. One community may experience a directional shift in its functional equilibrium, another may simply reorganize biomass internally, and a third may expand into previously unoccupied regions of trait space. Traditional metrics often collapse these distinct processes into a single value. `ascent` instead uses a multi-layer topological approach to decompose community restructuring into three orthogonal geometric components:

1. **Positional Shift ($r\Delta C_{\%}$):** The net directional displacement of the community centroid.
2. **Dispersive Shift ($\Delta FDis$):** The internal demographic reorganization (expansion or contraction of niche variance).
3. **Boundary Shift ($\Delta FRic$):** The multidimensional Convex Hull volume (expansion or collapse of extreme phenotypes).


**Table 1**. Functional diversity metrics used in ASC-CFD frameworks.

| Layer      | Metric | Ecological Question                                |
| ---------- | ------ | -------------------------------------------------- |
| Position   | ΔC     | Where is the community moving?                     |
| Dispersion | ΔFDis  | How is biomass being redistributed?                |
| Boundary   | ΔFRic  | Are functional boundaries expanding or collapsing? |


To isolate deterministic environmental filtering from stochastic noise, `ascent` triggers a hierarchical triad of null models: **Structural** (Incidence), **Quantitative** (Demographic), and **Identity** (Trait Shuffle).

### Simulating an Avian Metacommunity
We simulate a bird community experiencing habitat degradation. Functional matrices often contain mixed data types. Here, we combine quantitative traits (body mass, beak length) and binary traits (diet, habitat specialization). Binary traits MUST be encoded as `factor` to correctly apply the **Gower** distance metric.

```{r data_simulation}
library(ascent)

# 1. Functional Trait Space
set.seed(42)
aves_traits <- data.frame(
  Body_Mass   = c(15, 20, 30, 45, 60, 90, 150, 250, 400, 600),
  Beak_Length = c(10, 12, 15, 22, 28, 35,  45,  60,  85, 120),
  Frugivore   = factor(c(0, 0, 1, 1, 1, 0,  1,  1,  1,  0)),
  Forest_Dep  = factor(c(0, 0, 0, 0, 1, 1,  1,  1,  1,  1))
)
rownames(aves_traits) <- paste0("Av_sp", 1:10)

# 2a. Temporal Matrix (Deforestation)
abund_time <- rbind(
  Site1_Ref = c( 0,  0, 10, 15, 25, 20, 10, 8, 4, 2), # Mature forest
  Site1_Imp = c(40, 35, 15,  5,  0,  0,  0, 0, 0, 0)  # Logged area
)

# 2b. Spatial Matrix (Landscape Gradient)
abund_space <- rbind(
  Primary   = c( 0,  0,  5, 10, 20, 25, 15, 10, 5, 2),
  Secondary = c( 0,  5, 10, 20, 35, 20, 10,  0, 0, 0),
  Agri      = c( 0,  0,  0,  5, 45, 45,  5,  0, 0, 0)
)
```

---

## Part II - Temporal Restructuring

We start with the core engine: evaluating the functional restructuring driven by deforestation in Site 1 using `asc_paired()`. We simultaneously trigger the triad of null models using `asc_null()`. *(Note: `n_perm = 99` is used for CRAN vignette compilation speed. Use 999 or 9999 for research).*

```{r temporal_shift}
res_paired <- asc_paired(
  traits = aves_traits, abund = abund_time, 
  sites = c("Site1", "Site1"), time = c("Reference", "Impacted"),
  ref_time = "Reference", dist_method = "gower"
)
res_paired <- asc_null(res_paired, n_perm = 99, seed = 123)
summary(res_paired)
```

**Ecological Interpretation:** The community experienced a displacement of the functional centroid (42.42% of the regional functional diameter), while changes in dispersion and volume were small and consistent with random expectations. The only component that exceeded the null models was position under the identity filter, indicating that the observed restructuring was associated with a non-random selection of combinations of functional traits. Consequently, the results suggest a directional functional filtering process without evidence of significant contraction of the functional niche or internal reorganization of biomass.

---

## Part III - Species Leverage

To dissect the biological drivers behind this geometric shift, we extract the **Functional Leverage**. This algorithm projects the multidimensional demographic shift ($\Delta p_i$) of each species onto the unit directional vector of the ecosystem.

```{r leverage}
# Extract the specific topological drivers
drivers_time <- asc_transitions(res_paired)
head(drivers_time$Site1$species_leverage, 4)

# Plot the PCoA trajectory and the leverage divergence
plot(res_paired, contrast = "Site1", type = "both", n_sp = 5)
```

**Ecological Interpretation:** Species Av_sp1 (small, open-area generalist) exhibited the highest positive leverage, indicating that its demographic expansion strongly pulled the community centroid toward the degraded state. In contrast, Av_sp6 showed negative leverage because it declined despite occupying a position aligned with the direction of change, partially opposing the overall displacement. Conversely, the decline of Av_sp5 generated a small positive leverage effect by removing biomass from a region of trait space located opposite to the observed trajectory, thereby facilitating the centroid shift.

---

## Part IV - Spatial Networks

For landscape ecology or beta-diversity studies, `ascent` computes the bidirectional spatial divergence between all possible community pairs using `asc_pairwise()`.

```{r spatial_network}
res_pw <- asc_pairwise(traits = aves_traits, abund = abund_space, dist_method = "gower")
res_pw <- asc_null(res_pw, n_perm = 99, seed = 42)
summary(res_pw)

# Visualize the functional gap between Primary and Secondary Forest
plot(res_pw, contrast = "Primary_vs_Secondary", type = "both", n_sp = 5)

# Visualize the severe functional gap between Secondary Forest and Agriculture
plot(res_pw, contrast = "Secondary_vs_Agri", type = "both", n_sp = 5)
```

**Ecological Interpretation:** The spatial analysis revealed relatively small functional differences among communities. None of the observed shifts exceeded the expectations generated by the hierarchical null models, suggesting that the apparent variation among habitats can be explained by stochastic fluctuations in species composition and abundance. In this simulated example, agricultural intensification produced only modest changes in community topology, resulting in limited displacement of the functional centroid and minor reductions in functional volume. This example illustrates how ASC-CFD can distinguish between apparent community differences and statistically supported functional restructuring. Although the communities differ in composition, none of the observed topological shifts were stronger than expected under the null models, indicating weak evidence for deterministic functional filtering.

---

## Part V - Baseline Topology

Sometimes, a researcher only needs to report the absolute structural metrics of isolated communities without computing directional networks. `asc_baseline()` calculates the absolute functional topology of isolated communities.

```{r baseline}
base_topo <- asc_baseline(traits = aves_traits, abund = abund_space, dist_method = "gower")
summary(base_topo)
```

The baseline metrics reveal a gradual reduction in both functional richness and functional dispersion from `Primary` forest to `Agri` habitat, indicating that agricultural communities occupy a somewhat smaller and less dispersed region of the functional space.

---

## Part VI - Functional Entities

As a supplementary utility, the package provides `asc_entities()`, an algorithm that clusters the regional species pool into discrete functional entities based on morphological and ecological trait distances, regardless of spatial abundance.

```{r entities, fig.width=7, fig.height=5}
# Cluster the species into 3 functional entities using Gower distance
func_ent <- asc_entities(traits = aves_traits, dist_method = "gower", k = 3)
summary(func_ent)

# Visualize the functional dendrogram
plot(func_ent)
```

This classification helps researchers map continuous traits into discrete ecological guilds prior to mapping community-level dynamics.

**Choosing the Appropriate Function**

**Table 2**. Functions included in `ascent` package and its purposes.

| Objective              | Function            |
| ---------------------- | ------------------- |
| Temporal restructuring | `asc_paired()`      |
| Spatial divergence     | `asc_pairwise()`    |
| Species drivers        | `asc_transitions()` |
| Baseline topology      | `asc_baseline()`    |
| Functional entities    | `asc_entities()`    |
| Null model inference   | `asc_null()`        |

---

## Part VII - Methodological Notes

### Interpreting FRic ($\Delta FRic$)

FRic is computed as the volume of the convex hull in the retained PCoA axes. It captures the **outer boundary** of the functional space and has the following properties:

- It is driven exclusively by **extreme species** (hull vertices). Internal species, regardless of abundance, do not alter FRic.
- It is **not abundance-weighted.** A species that increases from 1% to 90% will not change FRic unless it lies on the hull boundary.
- When a community has fewer species than retained axes ($S < k$), the hull is geometrically undefined. In this case, ascent reports `FRic = NA` rather than `FRic = 0`, because a zero-volume hull is a meaningful geometric statement (collinear species), while `NA` signals that the metric cannot be computed.

**Recommendation:** Interpret $\Delta FRic$ as a topological descriptor of the functional boundary, complementary to (but not substituting for) the abundance-weighted $\Delta FDis$.

### Normalization and Cross-Study Comparisons

- **$r\Delta C_{\%}$** (positional shift) is normalized by the regional functional diameter ($D_{max,regional}$) and is directly comparable across studies.
- **$\Delta FDis$** and **$\Delta FRic$** are absolute differences in the retained PCoA space. Their magnitude depends on the number of retained axes, the trait set, and the Gower distance matrix. Direct comparison across studies with different trait pools requires caution.

### Null Model Scope

`asc_null()` operates on the full stacked community matrix and assumes a **shared regional species pool.** The curveball algorithm permutes species across all rows simultaneously. For biogeographically independent sites, run `asc_null()` on each contrast separately.

Model A assigns **uniform relative abundances** ($1/S_{local}$) to all species present after the curveball permutation. This means the null distribution for FDis under Model A tests whether the shift is extreme given random species composition with equitable abundances, not with the observed SAD.

### Functional Leverage: Additive Decomposition

The Functional Leverage satisfies a strict mathematical identity:

$$\sum_{i=1}^{S} \text{Leverage}_i = \|\Delta C\|$$

Each species' leverage is the product of its demographic change and its alignment with the centroid trajectory:

$$\text{Leverage}_i = \Delta p_i \cdot \text{proj}(\mathbf{f}_i, \hat{v})$$

where $\Delta p_i = p_{i,\text{comp}} - p_{i,\text{ref}}$ is the change in relative abundance, and $\text{proj}(\mathbf{f}_i, \hat{v})$ is the scalar projection of the species' PCoA coordinates onto the unit directional vector $\hat{v}$ of the centroid shift. Species with positive leverage **drive** the shift; species with negative leverage **resist** it.
