% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pnc.R
\name{pnc}
\alias{pnc}
\title{Estimate Phylogenetic Signal in Quantitative Traits}
\usage{
pnc(
  trait_data,
  phylo_tree,
  methods = "lambda",
  pca_axes = c("PC1", "PC2"),
  sig_levels = c(0.001, 0.01, 0.05),
  nsim = 1000,
  verbose = TRUE
)
}
\arguments{
\item{trait_data}{A data frame or matrix containing quantitative trait
values, with taxa as rows and traits as columns. Taxon 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 unique
tip labels.}

\item{methods}{Character vector specifying the phylogenetic signal metrics
to calculate. Available options are `"lambda"` and `"K"`. The default is
`"lambda"`.}

\item{pca_axes}{Character vector naming the PC axes to include in the
phylogenetic signal analysis. The default is `c("PC1", "PC2")`. Set to
`NULL` to skip PCA.}

\item{sig_levels}{Numeric vector of three increasing P-value thresholds
used to assign significance symbols. The default is
`c(0.001, 0.01, 0.05)`.}

\item{nsim}{Number of randomizations used to test Blomberg's K. This
argument is ignored when only Pagel's lambda is requested. The default
is 1000.}

\item{verbose}{Logical. If `TRUE`, warnings about skipped or failed PCA and
phylogenetic signal analyses are reported.}
}
\value{
A data frame with one row for each trait-method combination:
  \itemize{
    \item `trait`: name of the individual trait or PC axis.
    \item `coverage`: formatted percentage of input taxa with an available
      value. For an individual trait, this is trait availability before
      phylogenetic matching. For a PC axis, it represents complete-case
      coverage among taxa matched to the phylogeny.
    \item `n_sp`: number of taxa included after matching non-missing trait
      values to the phylogeny.
    \item `signal`: estimated Pagel's lambda or Blomberg's K.
    \item `p`: P-value for the phylogenetic signal estimate.
    \item `significance`: significance symbol assigned using `sig_levels`.
    \item `method`: phylogenetic signal metric used.
  }

  The returned data frame also stores `methods`, `pca_axes`, `pca_failed`,
  `sig_levels`, and `nsim` as attributes. When PCA is successfully fitted,
  the PCA scores and fitted model are stored in the `pca_results` and
  `pca_model` attributes, respectively.
}
\description{
`pnc()` estimates phylogenetic signal in quantitative traits for a focal
set of taxa. The function matches trait data to a phylogenetic tree and
estimates Pagel's lambda, Blomberg's K, or both for individual traits and,
when requested, principal component (PC) axes.
}
\details{
Phylogenetic signal describes the tendency for related taxa to resemble
one another in measured trait values. The resulting estimates can be used
to evaluate whether phylogenetic relatedness is informative about trait
similarity in the analyzed taxon pool. Their ecological interpretation
depends on the traits supplied and the taxa retained in the analysis.


Individual traits are analyzed separately. Missing values in one trait
therefore do not alter the taxa included in the analysis of another trait.

When PC axes are requested, PCA is performed once using taxa represented
in both `trait_data` and `phylo_tree` and having complete observations
across all supplied traits. Trait values are centered and scaled before
PCA. The requested PC scores are then analyzed in the same way as
individual traits.

PCA is skipped if fewer than four matched taxa have complete trait data or
if the PCA cannot be fitted. This does not prevent the individual traits
from being analyzed.

For each individual trait or PC axis, phylogenetic signal is estimated only
when at least four taxa have both an observed value and a matching
phylogenetic tip, and when the retained values show variation. Otherwise,
`signal` and `p` are returned as `NA`. The four-taxon threshold is a
computational minimum used by the function, not a general recommendation
for adequate sampling.
}
\examples{
\donttest{
data(BCI)
data(TRY)

sp <- colnames(BCI$com)

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

# Pagel's lambda for individual traits and PC1 and PC2
pnc(
  subtraits,
  BCI$phy_species,
  methods = "lambda"
)

# Pagel's lambda for individual traits only
pnc(
  subtraits,
  BCI$phy_species,
  methods = "lambda",
  pca_axes = NULL
)
}

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

Blomberg, S. P., Garland, T., Jr., and Ives, A. R. (2003). Testing for
phylogenetic signal in comparative data: Behavioral traits are more
labile. Evolution, 57, 717-745.
\doi{10.1111/j.0014-3820.2003.tb00285.x}

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}
}
