% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compnc_robustness.R
\name{compnc_robustness}
\alias{compnc_robustness}
\title{Assess Sensitivity of Pagel's Lambda Inference to Missing Trait Data
Across Multiple Communities}
\usage{
compnc_robustness(
  com,
  trait_data,
  phylo_tree,
  min_abundance = 0,
  n_simulations = 100,
  alpha_level = 0.05,
  verbose = TRUE
)
}
\arguments{
\item{com}{A numeric community matrix or data frame with communities as
rows and species as columns. Cell values represent species abundance or
occurrence and must be non-negative. Species names must be stored as
unique column names. Row names are used as community names; when they are
absent, names are generated automatically. Missing values are treated as
absence.}

\item{trait_data}{A data frame or matrix containing quantitative trait
values, with species as rows and traits as columns. Species names must be
stored as unique row names and are matched exactly to the species names
in `com` and the tip labels of `phylo_tree`. Trait columns must be
numeric. Missing values may be `NA`; all other values must be finite.}

\item{phylo_tree}{A phylogenetic tree object of class `"phylo"` with finite,
non-negative branch lengths and unique tip labels.}

\item{min_abundance}{Minimum abundance required for a species to be treated
as present in a community. A species is considered present when its value
is greater than `min_abundance`. The default is 0.}

\item{n_simulations}{Number of paired simulations performed for each
combination of community and individual trait. The default is 100.}

\item{alpha_level}{P-value threshold used to classify the complete and
incomplete analyses as statistically significant or non-significant.
The default is 0.05.}

\item{verbose}{Logical. If `TRUE`, a progress bar and warnings are shown.
The default is `TRUE`.}
}
\value{
A data frame with one row for each combination of community and
  individual trait. It contains the observed Pagel's lambda results from
  `compnc()` and the simulation based sensitivity metrics:
  \itemize{
    \item `plot`: community name.
    \item `trait`: trait name.
    \item `coverage`: formatted percentage of species present in the
      community with an observed value for the focal trait, before
      phylogenetic matching.
    \item `n_sp`: number of species included in the observed Pagel's lambda
      analysis after trait and phylogenetic matching.
    \item `signal`: Pagel's lambda estimated from the observed data.
    \item `p`: P-value for the observed lambda estimate.
    \item `significance`: significance symbol for the observed estimate.
    \item `method`: phylogenetic signal metric, always `"lambda"`.
    \item `n_sp_in_plot`: number of species present in the original local
      community according to `min_abundance`, before trait and phylogenetic
      matching.
    \item `simulation_lambda`: lambda used to transform the local reference
      phylogeny for simulation. This normally equals the observed lambda
      but may be reduced when the observed value exceeds the maximum
      supported by the local reference phylogeny.
    \item `consistency`: formatted percentage of successful paired
      simulations in which the complete and incomplete analyses produced
      the same significance classification at `alpha_level`.
    \item `signal_bias`: mean paired difference
      `lambda_missing - lambda_complete`. Positive values indicate that
      applying the missing data pattern produced a higher lambda estimate
      on average, whereas negative values indicate a lower estimate.
    \item `signal_sd`: standard deviation of the paired lambda differences.
      This is `NA` when fewer than two paired simulations are successful.
    \item `n_successful`: number of simulations in which both the complete
      and incomplete analyses produced finite lambda estimates and
      P-values.
  }

  The returned data frame stores `min_abundance`, `n_simulations`, and
  `alpha_level` as attributes.
}
\description{
`compnc_robustness()` uses paired simulations to assess how observed
patterns of missing data for individual quantitative traits affect Pagel's
lambda estimates and their significance classifications across multiple
ecological communities.
}
\details{
For each combination of community and trait, the observed lambda is first
estimated using `compnc()`. A local reference phylogeny is then constructed
from species present in the community and represented in both the trait
data and phylogeny. Complete trait values are simulated under Brownian
motion on this phylogeny after it has been transformed according to the
observed lambda.

Each simulated realization is analyzed twice: first using the complete
local reference species pool and then after applying the observed missing
data pattern of the focal trait. Because both analyses use the same
simulated realization, their paired difference measures the change
associated with applying that missing data pattern within the simulation.


The analysis is performed separately for each community and individual
trait. For a given community, the local reference species pool consists of
species that are present according to `min_abundance` and represented in
both `trait_data` and `phylo_tree`. Species without an observed value for
the focal trait remain in the complete simulated dataset and are excluded
only when the observed missing data pattern is applied.

The output includes `n_sp_in_plot` and trait-specific `n_sp`, allowing users
to compare the original local pool with the species retained after trait
and phylogenetic matching.

For each combination of community and trait, the simulation is conditional
on the Pagel's lambda estimated from the observed data. The local reference
phylogeny is transformed according to this lambda, and complete trait
values are simulated under Brownian motion on the transformed tree.
Simulated lambda estimates are not forced to equal the observed value, so
stochastic variation among simulated realizations is retained.

Within each simulation, the complete and incomplete analyses use identical
trait values for species retained in both datasets. Their paired difference
therefore compares the two data conditions within the same simulated
realization rather than between independently simulated datasets.

The maximum valid lambda depends on the branch length structure of the
local reference phylogeny. An observed lambda estimated from a smaller,
trait-specific tree may occasionally exceed the maximum value that can be
applied to the larger local reference phylogeny. In this case, the largest
valid lambda for the local reference phylogeny is used for simulation,
while the observed lambda reported in the output remains unchanged.

Sensitivity metrics are returned as `NA` with `n_successful = 0` when the
observed lambda cannot be estimated, fewer than four matched species have
observed values for the focal trait, the retained trait values show no
variation, or a valid transformed local reference phylogeny cannot be
constructed. The four-species threshold is a computational minimum, not a
general recommendation for adequate sampling.

The current robustness assessment is applied to individual traits only;
PC axes are not included because their paired comparison would require a
separate multivariate simulation framework.

For repeated lambda estimation, the function uses cached likelihood
calculations for the local phylogenies and falls back to
`phytools::phylosig()` when necessary.

The resulting assessment is conditional on the observed lambda and the
Brownian motion simulation model.
}
\examples{
\donttest{
data(HimalayanBirds)
data(AVONET)

sp <- colnames(HimalayanBirds$com)

subtraits <- extract_traits(
  sp,
  AVONET,
  rank = "species"
)

set.seed(123)

compnc_robustness(
  HimalayanBirds$com,
  subtraits,
  HimalayanBirds$phy_species,
  n_simulations = 10
)
}

}
\references{
Pagel, M. (1999). Inferring the historical patterns of biological
evolution. Nature, 401, 877-884.
\doi{10.1038/44766}

Münkemüller, T., Lavergne, S., Bzeznik, B., Dray, S., Jombart, T.,
Schiffers, K., and Thuiller, W. (2012). How to measure and test
phylogenetic signal. Methods in Ecology and Evolution, 3, 743-756.
\doi{10.1111/j.2041-210X.2012.00196.x}
}
