% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/permutation.r
\name{perm_test_pv}
\alias{perm_test_pv}
\title{Permutation Test}
\usage{
perm_test_pv(
  x,
  y,
  statistic = c("diff_mean", "diff_median", "diff_t", "diff_welch", "diff_hl",
    "ratio_var", "ratio_sd"),
  mu = NULL,
  alternative = "two.sided",
  exact = NULL,
  max_exact_combs = 10L^7,
  MC_sims = 10L^5,
  seed = NULL,
  simple_output = FALSE
)
}
\arguments{
\item{x}{numerical vector or list of numerical vectors of
observations in the first group.}

\item{y}{numerical vector or list of numerical vectors of
observations in the second group.}

\item{statistic}{single character giving the type of test statistic
to be used; must be one of \code{"diff_mean"},
\code{"diff_median"}, \code{"diff_t"}, \code{"diff_welch"},
\code{"diff_hl"}, \code{"ratio_var"} or \code{"ratio_sd"}
(see Details).}

\item{mu}{numerical vector giving the hypothesised values
under the null; if \code{is.null(mu)} (the default) it
is set to 0 for test statistics that are based on
differences (\code{diff_}\emph{) or 1 for ratio-based tests
statistics (\code{ratio_}}).}

\item{alternative}{character vector that indicates the alternative hypotheses; each value must be one of \code{"two.sided"} (the default), \code{"less"} or \code{"greater"}.}

\item{exact}{logical value that indicates whether \eqn{p}-values
are to be calculated by exact computation (\code{TRUE})
or by simulation (\code{FALSE}); if \code{NULL} (the default)
exact computation is performed if the number of
possible sample combinations (see Details) is below
or equal to \code{max_exact_combs}; otherwise the
respective \eqn{p}-values are obtained by
simulation.}

\item{max_exact_combs}{maximum number of allowed combinations for exact
computation of the permutation distribution (see
details).}

\item{MC_sims}{positive integer or \code{NULL}. The number of Monte
Carlo permutations to draw when \code{exact = FALSE}.
Ignored when \code{exact = TRUE}. Default is \code{10000L}.}

\item{seed}{single integer or \code{NULL}. Random seed passed to
\code{\link[=set.seed]{set.seed()}} before Monte Carlo sampling to ensure
reproducibility. Use \code{NULL} to skip seed setting.
Ignored when \code{exact = TRUE}.}

\item{simple_output}{logical value that indicates whether an R6 class object, including the tests' parameters and support sets, i.e. all observable p-values under each null hypothesis, is to be returned (see below).}
}
\value{
If \code{simple.output = TRUE}, a vector of computed p-values is returned.
Otherwise, the output is a \code{\link{DiscreteTestResults}} R6 class object, which
also includes the p-value supports and testing parameters. These have to be
accessed by public methods, e.g. \verb{$get_pvalues()}.
}
\description{
\code{perm_test_pv()} performs a permutation test for the comparison of two
independent samples using a user-supplied test statistic. It is vectorised
over multiple test problems: by passing lists of sample vectors for \code{x} and
\code{y}, several tests can be evaluated simultaneously. The function can compute
exact \emph{p}-values (by enumerating all permutations) or approximate \emph{p}-values
via Monte Carlo sampling. It is capable of returning the discrete \emph{p}-value
supports, i.e. all observable \emph{p}-values under the null hypothesis.
}
\details{
Under the null hypothesis of exchangeability (i.e. both samples come from
the same distribution), all \eqn{\binom{n_x + n_y}{n_x}} partitions of the
pooled sample into groups of sizes \eqn{n_x} and \eqn{n_y} are equally
likely. \code{perm_test_pv()} exploits this by:

\enumerate{
\item Computing the observed test statistic \eqn{T_\text{obs}} from
\code{x} and \code{y} using the function selected by \code{statistic} (see the
\emph{Test Statistics} section below).
\item Enumerating (if \code{exact = TRUE}) or randomly sampling (if
\code{exact = FALSE}) permutations of the pooled sample.
\item Evaluating the selected test statistic on each permuted split.
\item Deriving the \emph{p}-value as the fraction of permutation statistics
that are at least as extreme as \eqn{T_\text{obs}}, where \emph{extreme}
is defined by \code{alternative}:
\describe{
\item{\code{"less"}}{fraction with permuted statistic
\eqn{\le T_\text{obs}}}
\item{\code{"greater"}}{fraction with permuted statistic
\eqn{\ge T_\text{obs}}}
\item{\code{"two.sided"}}{fraction with
\eqn{|\text{permuted statistic}| \ge |T_\text{obs}|}}
}
}

Exact computation is only feasible for small pooled samples; the total
number of permutations grows as \eqn{\binom{n_x + n_y}{n_x}}. If
\code{exact = NULL}, exact computation is applied when the number of computations
is below or equal to \code{max_exact_combs} (default \eqn{10{,}000{,}000}).
Otherwise, the distribution of the test statistics is approximated by Monte
Carlo simulation. When \code{exact = TRUE} and the number of permutations exceeds
\code{max_exact_combs}, an error is raised. Set \code{exact = FALSE} to use Monte Carlo
sampling in such cases.

The parameters \code{x}, \code{y}, \code{alternative}, and \code{MC_sims} are vectorised via
lists: if \code{x} and \code{y} are lists of the same length, each pair
\verb{(x[[i]], y[[i]])} defines one test. Scalars and single vectors are
recycled to the required length.
\subsection{Test Statistics}{

The \code{statistic} argument selects among seven built-in test statistics for
comparing two groups. Let \eqn{\bar{x}}, \eqn{\bar{y}} denote the group
means, \eqn{s_x^2}, \eqn{s_y^2} the sample variances, and \eqn{n_x},
\eqn{n_y} the group sizes.

\describe{
\item{\code{"diff_mean"} — Difference of means
\eqn{T = \bar{x} - \bar{y} - \mu_0}}{
The most common choice for location comparisons. Tests whether the
population means differ by \eqn{\mu_0} (default: 0).\cr
\emph{Advantages}: Intuitive interpretation; optimal power under normality
and equal variances (Pitman efficiency 1 vs. the two-sample
\eqn{t}-test).\cr
\emph{Disadvantages}: Sensitive to outliers; less powerful than
\code{"diff_hl"} or \code{"diff_t"} under heavy-tailed distributions.}
\item{\code{"diff_median"} — Difference of medians
\eqn{T = \text{median}(x) - \text{median}(y) - \mu_0}}{
Tests for a shift in the median rather than the mean (default:
\eqn{\mu_0 = 0)}.\cr
\emph{Advantages}: Robust to outliers and skewed distributions; directly
interpretable in terms of the median.\cr
\emph{Disadvantages}: The sample median is a step function of the data,
leading to a coarser permutation distribution with many ties; can
have lower power than \code{"diff_hl"} for continuous data.}
\item{\code{"diff_t"} — Pooled two-sample \eqn{t}-statistic
\eqn{T = \frac{\bar{x} - \bar{y} - \mu_0}{s_p \sqrt{1/n_x + 1/n_y}}}
where
\eqn{s_p = \sqrt{\frac{(n_x-1)s_x^2 + (n_y-1)s_y^2}{n_x+n_y-2}}}}{
Scales the mean difference by the pooled standard deviation,
analogous to the classical Student \eqn{t}-test.\cr
\emph{Advantages}: Studentisation makes the statistic (approximately)
scale-free; useful when group variances are expected to be equal;
the permutation \eqn{p}-value is valid even without normality.\cr
\emph{Disadvantages}: Assumes equal variances (homoscedasticity);
sensitive to outliers; no power gain over \code{"diff_mean"} in the
permutation setting when sample sizes are equal.}
\item{\code{"diff_welch"} — Welch \eqn{t}-statistic
\eqn{T = \frac{\bar{x} - \bar{y} - \mu_0}{\sqrt{s_x^2/n_x + s_y^2/n_y}}}}{
Scales the mean difference by the unpooled standard error, analogous
to Welch's two-sample \eqn{t}-test. Unlike \code{"diff_t"}, the variances
of the two groups are estimated separately rather than pooled.\cr
\emph{Advantages}: Does not assume equal variances; retains more power
than \code{"diff_t"} when group variances are unequal and sample sizes
differ; in the permutation setting the \eqn{p}-value remains exactly
valid regardless of the variance ratio, just as with \code{"diff_t"}.\cr
\emph{Disadvantages}: No power gain over \code{"diff_t"} when variances are
equal; estimating two separate variances instead of one pooled
variance introduces additional estimation uncertainty, which can
slightly reduce power compared to \code{"diff_t"} in balanced designs with
equal variances.}
\item{\code{"diff_hl"} — Hodges–Lehmann estimator
\eqn{T = \text{median}_{i,j}\,(x_i - y_j) - \mu_0}}{
Tests for a shift in the median of all \eqn{n_x \cdot n_y} pairwise
differences between the two groups (default: \eqn{\mu_0 = 0}). It is
the natural companion statistic to the Wilcoxon–Mann–Whitney test and
estimates the location shift \eqn{\Delta} under a shift model.\cr
\emph{Advantages}: Highly robust to outliers; produces fewer ties in the
permutation distribution than \code{"diff_median"}.\cr
\emph{Disadvantages}: \eqn{O(n_x \cdot n_y)} computation; the
interpretation as a median shift requires a location-shift model.}
\item{\code{"ratio_var"} — Ratio of variances
\eqn{T = s_x^2 / (s_y^2 \cdot \mu_0)}}{
Tests for differences in spread (scale) rather than location.
Under the null \eqn{H_0\colon \sigma_x^2 / \sigma_y^2 = \mu_0}
(default: \eqn{\mu_0 = 1}).\cr
\emph{Advantages}: Direct measure of relative variability; permutation
validity does not require normality (unlike the classical
\eqn{F}-test).\cr
\emph{Disadvantages}: Highly sensitive to outliers and non-normality
(the variance itself is not robust); should be interpreted with
caution if the distributions differ in shape as well as scale.}
\item{\code{"ratio_sd"} — Ratio of standard deviations
\eqn{T = s_x / (s_y \cdot \mu_0)}}{
Equivalent to \code{"ratio_var"} on the standard deviation scale
(\eqn{T = \sqrt{s_x^2 / (s_y^2 \cdot \mu_0^2)}}); tests the same null
hypothesis \eqn{H_0 \colon \sigma_x / \sigma_y = \mu_0} (default:
\eqn{\mu_0 = 1}).\cr
\emph{Advantages}: Same unit as the original data, which can aid
interpretation; monotone transformation of \code{"ratio_var"}, so the
\eqn{p}-values are identical (note that \eqn{\mu_0} needs to be
squared for the variance-based statistic to be equivalent).\cr
\emph{Disadvantages}: Same sensitivity to outliers as \code{"ratio_var"};
the monotone relationship means it carries no additional statistical
information compared to \code{"ratio_var"}.
}
}
}
}
\examples{
set.seed(42)
x1 <- rnorm(8)
y1 <- rnorm(10, mean = 1)

# Two-sided test for difference of means = 0
results_ex <- perm_test_pv(x1, y1)
print(results_ex)
results_ex$get_pvalues()

# Hodges Lehmann statistic with Monte Carlo approximation
results_hl <- perm_test_pv(x1, y1, "diff_hl", exact = FALSE, seed = 1L)
results_hl$print()
results_hl$get_pvalues()

# Multiple tests simultaneously, one-sided alternative (mu = 0.5),
# using t-statistic, forced exact computation
xs <- list(rnorm(12), rnorm(9, 1))
ys <- list(rnorm(11, 1), rnorm(10, 2))
results_multi <- perm_test_pv(xs, ys, "diff_t", c(0.5, -1.5), "greater", TRUE)
results_multi$print()
results_multi$get_pvalues()

}
\references{
Pitman, E. J. G. (1937). Significance tests which may be applied to
samples from any populations. \emph{Supplement to the Journal of the Royal
Statistical Society}, \strong{4}(1), pp. 119–130. \doi{10.2307/2984124}

Good, P. (2000). \emph{Permutation Tests: A Practical Guide to Resampling
Methods for Testing Hypotheses}. Second Edition. New York: Springer.
\doi{10.1007/978-1-4757-3235-1}
}
\seealso{
\code{\link[=mann_whitney_test_pv]{mann_whitney_test_pv()}}, \code{\link[stats:wilcox.test]{stats::wilcox.test()}}
}
