% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/asc_paired.R
\name{asc_paired}
\alias{asc_paired}
\title{Paired Functional Multidimensional Restructuring}
\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{
\item{traits}{A data frame or matrix of functional traits.}

\item{abund}{A data frame or matrix of species abundances.}

\item{sites}{A vector indicating the site identifier.}

\item{time}{A vector indicating the temporal state.}

\item{ref_time}{A character string specifying the reference state.}

\item{dist_method}{Distance metric for the trait matrix. Default is "gower".}

\item{dim_retention}{Character. Method for dimensionality reduction.}

\item{var_tol}{Numeric. Proportion of cumulative variance to retain. Default is 0.80.}

\item{na.rm}{Logical. Remove missing values? Default is TRUE.}
}
\value{
An S3 object of class \code{ascfcd}.
}
\description{
Calculates centroid displacement (Layer 1), dispersion shift (Layer 2 - FDis),
and volume shift (Layer 3 - FRic) between paired states.
}
\note{
\strong{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.

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

\strong{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)

}
