% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/taxon_effect.R
\name{taxon_effect}
\alias{taxon_effect}
\title{Taxon-level leave-out contributions for split-lines}
\usage{
taxon_effect(obj)
}
\arguments{
\item{obj}{A \code{hespdiv} object.}
}
\value{
A list of class \code{taxon_effect_result} with:
\describe{
\item{\code{elim.comp.vals}}{
Performance after removing each taxon; dimension
\code{[n_splits x n_taxa]}.
}
\item{\code{delta}}{
Signed contribution \eqn{\Delta} as defined above; dimension
\code{[n_splits x n_taxa]}.
}
\item{\code{n_per_pol}}{
Counts of the focal taxon per split and polygon.
}
\item{\code{baseline}}{
The original performance vector.
}
}
}
\description{
For each unique taxon label in \code{obj$call.info$Call_ARGS$data}
(for example, species or genus), remove all of its occurrences from both
child polygons of every split, recompute split-line performance, and record
both the resulting value and its difference from the original.
}
\details{
Let \eqn{P} be the split-line performance stored in
\code{obj$split.stats$performance}. For a focal taxon \eqn{t}, we compute
\eqn{P^{-t}} by removing all occurrences of \eqn{t}. We report \eqn{\Delta}
so that \eqn{\Delta > 0} always indicates a \strong{positive contributor}
(that is, removal worsens performance):
\itemize{
\item If \code{obj$call.info$Call_ARGS$maximize = FALSE} (lower is better,
for example similarity), \eqn{\Delta = P^{-t} - P}.
\item If \code{obj$call.info$Call_ARGS$maximize = TRUE} (higher is better,
for example distance), \eqn{\Delta = P - P^{-t}}.
}
If a taxon is absent from a split's parent polygons, elimination is a no-op
and \eqn{\Delta = NA}.
}
\seealso{
Other functions for hespdiv results post-processing: 
\code{\link{cross_comp}()},
\code{\link{hsa}()},
\code{\link{hsa_detailed}()},
\code{\link{hsa_quant}()},
\code{\link{hsa_sample_constrained}()},
\code{\link{nulltest}()}
}
\concept{functions for hespdiv results post-processing}
