% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pnc_robustness.R
\name{pnc_robustness}
\alias{pnc_robustness}
\title{Assess Sensitivity of Pagel's Lambda Inference to Missing Trait Data}
\usage{
pnc_robustness(
  trait_data,
  phylo_tree,
  n_simulations = 100,
  alpha_level = 0.05,
  verbose = TRUE
)
}
\arguments{
\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 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{n_simulations}{Number of paired simulations performed for each
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 individual trait. It contains
  the observed Pagel's lambda results from `pnc()` and the simulation based
  sensitivity metrics:
  \itemize{
    \item `trait`: trait name.
    \item `coverage`: formatted percentage of input species with an
      observed value for the focal trait.
    \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 `simulation_lambda`: lambda used to transform the reference
      phylogeny for simulation. This normally equals the observed lambda
      but may be reduced when the observed value exceeds the maximum
      supported by the 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 `n_simulations` and `alpha_level` as
  attributes.
}
\description{
`pnc_robustness()` uses paired simulations to assess how the observed
pattern of missing data for each individual quantitative trait affects
Pagel's lambda estimates and their significance classifications within a
focal species pool.
}
\details{
For each trait, the observed lambda is first estimated using `pnc()`. The
corresponding reference phylogeny is then transformed according to this
estimate, and a complete set of trait values is simulated under Brownian
motion. Each simulated realization is analyzed twice: first using all
species in the reference pool and then after applying the observed missing
data pattern of the focal trait.

Because the complete and incomplete analyses use the same simulated
realization, their paired difference measures the change associated with
applying the observed missing data pattern within that simulation.


The analysis is performed separately for each individual trait. The
reference species pool consists of species represented in both
`trait_data` and `phylo_tree`. Species without an observed value for the
focal trait are retained in the complete simulated dataset and excluded
only when the observed missing data pattern is applied.

For each trait, the simulation is conditional on the Pagel's lambda
estimated from the observed data. The 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 the 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
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 reference phylogeny. In this case, the largest valid
lambda for the reference phylogeny is used for simulation, while the
observed lambda estimate 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 species have observed
values for the focal trait, or a valid transformed reference phylogeny
cannot be constructed.

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 a cached likelihood
calculation 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(BCI)
data(TRY)

sp <- colnames(BCI$com)

subtraits <- extract_traits(
  sp,
  TRY,
  rank = "species",
  traits = c("LA", "LMA", "LeafN", "PlantHeight")
)

set.seed(123)

pnc_robustness(
  subtraits,
  BCI$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}
}
