% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/group_effect.R
\name{group_effect}
\alias{group_effect}
\title{Investigate Group Effects on Split-Line Performance}
\usage{
group_effect(obj, group, perm.n = 999, maxdif = NULL, plot = TRUE, ...)
}
\arguments{
\item{obj}{A \code{hespdiv} object.}

\item{group}{A factor (or coercible to factor) giving the group label for each observation (row) in
\code{obj$call.info$Call_ARGS$xy.dat}.}

\item{perm.n}{Integer (\eqn{>0}). Number of permutations in the locality-block permutation test. Default \code{999}.}

\item{maxdif}{Numeric. The performance value representing a maximal between-polygons difference for the chosen metric.
If \code{NULL} and the metric is one of \code{c("pielou","morisita","sorensen","horn.morisita")},
\code{maxdif} is set automatically. Otherwise, it must be provided.}

\item{plot}{Logical. If \code{TRUE} (default), stores a \code{\link{plot_hespdiv}} output per group with
\code{performance = TRUE} and a group-specific subtitle.}

\item{...}{Additional arguments passed to \code{\link{plot_hespdiv}}. Note that \code{obj},
\code{performance}, and \code{subtitle} are set internally.}
}
\value{
A list of class \code{"group_effect"} with elements:
\itemize{
\item \code{within = list(est, delta)} where \code{est} and \code{delta} are \code{[n_splits x n_groups]} matrices;
\item \code{elim   = list(est, delta)} as above (group removed);
\item \code{perm   = list(est, delta)} where each is a nested list \code{[[split]][[group]]} of numeric vectors (length \code{perm.n}).  If permutations are uninformative (e.g., one-sided/absent), the corresponding entries are \code{NA};
\item \code{baseline}: the original performance vector;
\item \code{n_per_pol}: \code{data.frame} with columns \code{split.id}, \code{group}, \code{pol.id}, \code{n};
\item \code{plots}: list of \code{plot_hespdiv} outputs by group (or \code{NULL} if \code{plot = FALSE}).
}
}
\description{
For every level of \code{group}, the function:
\enumerate{
\item subsets \code{data} and \code{xy.dat} to the focal group's observations;
\item recomputes split-line performance using \code{compare.f} and \code{generalize.f};
\item runs two contribution assessments:
\itemize{
\item \emph{group-removal}: removes the group's observations and recomputes performance;
\item \emph{group-permutation (locality-block shuffle)}: shuffles intact within-locality assemblages of the focal group
among the set of localities where the group occurs within the split’s parent polygons (non-group observations fixed).
}
\item optionally re-plots the object for that group via \code{\link{plot_hespdiv}} (with a group-specific subtitle).
}
}
\details{
Re-evaluates split-line performance within each level of a grouping factor and
tests how much each group influences the detected split-lines in a \code{hespdiv} object.

\strong{Within-group recomputation (agreement).}
For each split, the group's observations are partitioned by the two child polygons and
performance is recomputed as \code{compare.f(generalize.f(pol1), generalize.f(pol2))}.
If the group's points fall on only one side, \code{within$est} is set to \code{maxdif};
if absent from both sides, it is \code{NA}.

\strong{Elimination test.}
All observations of the focal group are removed from both polygons and performance is recomputed on the remaining data.
If the group's points fall on only one side, \code{elim$est} is computed normally;
if absent from both sides, it is \code{NA} (if desired, you could identify these cases afterwards from \code{n_per_pol}, changing to baseline performance and zero delta).

\strong{Permutation test (locality-block shuffle).}
Localities are defined by identical coordinate pairs among the focal group's occurrences.
For each permutation, whole localities (blocks) are reassigned via a one-to-one mapping within the split’s parent polygons.
For speed, polygon membership of unique locality coordinates is precomputed once per split and then locality memberships are shuffled in each permutation.
If the group's points fall on only one side, \code{perm$est} is set to NA;
if absent from both sides, it is also \code{NA}.

\strong{Baseline and deltas.}
The baseline vector is \code{baseline <- obj$split.stats$performance}.
Let \code{maximize <- obj$call.info$Call_ARGS$maximize}.
Deltas are defined so that \emph{positive values always indicate a positive contributor} (removal/permutation worsens performance):
\itemize{
\item if \code{maximize == FALSE} (lower is better; e.g. similarity): \code{delta = est - baseline};
\item if \code{maximize == TRUE}  (higher is better; e.g. distance):  \code{delta = baseline - est}.
}
}
\section{Notes}{

\itemize{
\item Localities are defined by exact duplicate coordinate pairs among the group's observations
(harmonise coordinates upstream if needed).
\item The locality-block permutation preserves the \emph{number of group-present localities per polygon};
only identities of the locality blocks are shuffled. The number of group occurrences per side can vary if block sizes differ.
}
}

\examples{
data <- example_hespdiv$call.info$Call_ARGS$data
# See the hespdiv() example; lowercase letters represent widespread taxa:
endemic_l <- !data \%in\% letters[1:5]
group <- factor(ifelse(endemic_l, "endemic", "widespread"))

gr_ef <- group_effect(obj = example_hespdiv, group = group, plot = FALSE)

barplot(
  gr_ef$within$est,
  main = "Split-line similarity within each group",
  ylab = "Performance"
)

barplot(
  gr_ef$within$delta,
  main = "Group contribution to similarity within each group",
  ylab = "Contribution"
)
abline(h = 0)

barplot(
  gr_ef$elim$est,
  main = "Split-line similarity with group eliminated",
  ylab = "Performance"
)

barplot(
  gr_ef$elim$delta,
  main = "Group contribution to similarity with group eliminated",
  ylab = "Contribution"
)
abline(h = 0)

boxplot(
  gr_ef$perm$est$`1`,
  main = "Split-line similarity with group spatially permuted",
  ylab = "Performance"
)

boxplot(
  gr_ef$perm$delta$`1`,
  main = "Group contribution to similarity with group spatially permuted",
  ylab = "Contribution"
)
abline(h = 0)
}
\seealso{
\code{\link{plot_hespdiv}}
}
\concept{functions for hespdiv post-processing}
