% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hespdiv_nullltest.R
\name{nulltest}
\alias{nulltest}
\title{Test significance of split-lines in spatial subdivision}
\usage{
nulltest(
  obj,
  n = 999,
  maintain.n = TRUE,
  shuffle.scope = "within",
  shuffle.type = "localities"
)
}
\arguments{
\item{obj}{An object of class \code{hespdiv}.}

\item{n}{Integer. Number of permutations used to form the null distribution.}

\item{maintain.n}{Logical. Only honored when \code{shuffle.scope = "within"} and \code{shuffle.type = "localities"}. If \code{TRUE}, attempts to keep the randomized child polygon occurrence counts close to the observed (maximum discrepancy up to \code{max_n/2}, where \code{max_n} is the largest locality size). Ignored otherwise.}

\item{shuffle.scope}{Character. Either \code{"all"} (shuffle across the full study area) or \code{"within"} (shuffle only within each parent polygon).}

\item{shuffle.type}{Character. Either \code{"localities"} (shuffle whole localities, preserving assemblages) or \code{"occurrences"} (shuffle individual occurrences). \code{"localities"} is generally preferred.}
}
\value{
Invisibly returns an object of class \code{nullhespdiv}, a list with:
\itemize{
\item \code{$stats}, a data frame summarizing each split-line with:
\itemize{
\item \code{performance}: observed performance.
\item \code{mean.random}: mean of null performances.
\item \code{sd.random}: standard deviation of null performances.
\item \code{p.val}: empirical one-sided p-value (ties included).
\item \code{z.score.random}: standardized effect size.
}
\item \code{$null}, a matrix or data frame containing all null performance
values for every split-line across permutations.
}
}
\description{
Assess the statistical significance of each split-line (bioregion boundary) identified by \code{hespdiv} by comparing its observed performance to a null distribution. The null is generated by permuting the data \code{n} times and recomputing the split-line performance after each permutation. Multiple shuffling strategies are supported to probe the influence of spatial structure on delineation.
}
\details{
Two shuffling scopes are available:
\describe{
\item{\strong{"all"}:}{Shuffle across the entire study area, ignoring polygonal subdivisions.}
\item{\strong{"within"}:}{Shuffle only within each parent polygon (the region in which the split-line is nested), preserving local spatial structure.}
}

Two shuffling types are available:
\describe{
\item{\strong{"localities"}:}{Shuffle whole localities, preserving each site's assemblage (recommended, since occurrences within a locality are not independent).}
\item{\strong{"occurrences"}:}{Shuffle individual occurrences across sites (use with caution; may violate within-locality independence).}
}

For each split-line, the function reports the observed performance, the mean and standard deviation of the permuted (null) performances, an empirical one-sided p-value (proportion of permuted values \emph{as or more extreme} than observed; ties included), and a z-score quantifying departure from the null.
}
\examples{
# if split-line is strongly significant, the choice of parameters should not
# matter. For example (look at p-value, z.score.random, sd.random and
# mean.random):
(nulltest(example_hespdiv, maintain.n = FALSE, shuffle.type = "occurrences"))
(nulltest(example_hespdiv, maintain.n = FALSE, shuffle.type = "localities"))
(nulltest(example_hespdiv, maintain.n = TRUE, shuffle.type = "localities"))

}
\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{taxon_effect}()}
}
\concept{functions for hespdiv results post-processing}
