% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/assess_functional_space.R
\name{assess_functional_space}
\alias{assess_functional_space}
\title{Assess Functional Space Quality}
\usage{
assess_functional_space(
  traits,
  dist_method = "gower",
  dim_retention = c("variance", "broken_stick"),
  var_tol = 0.8
)
}
\arguments{
\item{traits}{A data frame or matrix of functional traits.}

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

\item{dim_retention}{Character. Method for dimensionality reduction.
Options are \code{"variance"} or \code{"broken_stick"}. Default is \code{"variance"}.}

\item{var_tol}{Numeric. Proportion of cumulative variance to retain (used
when \code{dim_retention = "variance"}). Default is 0.80.}
}
\value{
A list of class \code{ascfcd_space} with:
\describe{
\item{quality}{Numeric. PCoA quality index (\code{sum(positive_eig) / sum(abs(all_eig))}). Values above 0.80 are generally acceptable.}
\item{n_species}{Integer. Number of species in the trait matrix.}
\item{n_traits}{Integer. Number of traits.}
\item{k_retained}{Integer. Number of PCoA axes retained.}
\item{var_retained}{Numeric. Cumulative variance explained by retained axes.}
\item{axis_var}{Numeric vector. Relative variance per retained axis.}
\item{n_neg_eigenvalues}{Integer. Count of negative eigenvalues.}
\item{neg_eigenvalue_pct}{Numeric. Percentage of total absolute eigenvalue represented by negative eigenvalues.}
\item{eigenvalues}{Numeric vector. All raw eigenvalues from PCoA.}
}
}
\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 (\code{asc_paired}, \code{asc_pairwise}, etc.) to identify
potential distortion from negative eigenvalues or excessive dimensionality
reduction.
}
\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\\% of the total variation. In such cases, consider:
\itemize{
\item Reviewing the trait data for problematic variables.
\item Applying a Cailliez or Lingoes correction to the distance matrix before ordination.
\item Using a different distance metric (e.g., \code{"euclidean"} for purely continuous traits).
}
}
\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

}
