% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compnc.R
\name{compnc}
\alias{compnc}
\title{Estimate Phylogenetic Signal Across Multiple Communities}
\usage{
compnc(
  com,
  trait_data,
  phylo_tree,
  methods = "lambda",
  pca_axes = c("PC1", "PC2"),
  sig_levels = c(0.001, 0.01, 0.05),
  min_abundance = 0,
  nsim = 1000,
  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 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{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{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
  community-trait-method combination:
  \itemize{
    \item `plot`: community name.
    \item `trait`: name of the individual trait or PC axis.
    \item `coverage`: formatted percentage of species present in the
      community with an available value. For an individual trait, this is
      trait availability before phylogenetic matching. For a PC axis, it is
      the percentage of species with a score from the pooled PCA.
    \item `n_sp`: number of species included after matching the trait or PC
      score 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.
    \item `n_sp_in_plot`: number of species present in the original local
      community according to `min_abundance`, before trait and phylogenetic
      matching.
  }

  The returned data frame also stores `methods`, `pca_axes`, `pca_failed`,
  `sig_levels`, `min_abundance`, `nsim`, `total_plots`, and
  `analyzed_plots` as attributes. When PCA is successfully fitted, the
  pooled species scores and fitted model are stored in the `pca_results`
  and `pca_model` attributes, respectively.
}
\description{
`compnc()` estimates phylogenetic signal in quantitative traits across
multiple ecological communities. The function identifies the species
present in each community, matches them to a trait matrix and phylogenetic
tree, and estimates Pagel's lambda, Blomberg's K, or both within each
resulting local species pool.
}
\details{
When PC axes are requested, one principal component analysis (PCA) is
fitted using the pooled set of eligible species across all communities.
The resulting species scores are then used in every community, so that a
given PC axis represents the same dimension of trait variation across
communities.

Phylogenetic signal describes the tendency for related species to resemble
one another in measured trait values. The community-specific estimates can
be used to evaluate whether phylogenetic relatedness is informative about
trait similarity within each local species pool and to compare this
relationship among communities.


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

When PC axes are requested, the pooled PCA includes species that occur in
at least one community, are represented in both `trait_data` and
`phylo_tree`, and have complete observations across all supplied traits.
Trait values are centered and scaled before PCA. The PCA is fitted once,
and the same species scores are used in every community.

The output reports both `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.

Phylogenetic signal is estimated only when at least four matched species
have an observed value and the retained values show variation. Otherwise,
`signal` and `p` are returned as `NA`. The four-species threshold is a
computational minimum used by the function, not a general recommendation
for adequate sampling.

Community-specific estimates may be sensitive to the number and
phylogenetic composition of the retained species. Results from small or
phylogenetically restricted local pools should therefore be interpreted
together with the reported `n_sp` and the species retained in each
analysis.
}
\examples{
\donttest{
data(HimalayanBirds)
data(AVONET)

sp <- colnames(HimalayanBirds$com)

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

# Pagel's lambda using one pooled PCA across all communities
compnc(
  HimalayanBirds$com,
  subtraits,
  HimalayanBirds$phy_species,
  methods = "lambda"
)

# Pagel's lambda for individual traits only
compnc(
  HimalayanBirds$com,
  subtraits,
  HimalayanBirds$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}
}
