% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fwilcox_test.R
\name{f_wilcox_test}
\alias{f_wilcox_test}
\alias{f_wilcox_test.formula}
\alias{f_wilcox_test.default}
\title{Perform multiple Wilcoxon rank sum and signed rank tests with inspection and visualization.}
\usage{
f_wilcox_test(x, ...)

\method{f_wilcox_test}{formula}(
  formula,
  data = NULL,
  paired = FALSE,
  conf.level = NULL,
  mu = 0,
  alternative = "two.sided",
  norm_plots = TRUE,
  alpha = 0.05,
  intro_text = TRUE,
  close_generated_files = FALSE,
  open_generated_files = TRUE,
  output_type = "default",
  save_as = NULL,
  save_in_wdir = FALSE,
  ...
)

\method{f_wilcox_test}{default}(
  x,
  y = NULL,
  paired = FALSE,
  conf.level = NULL,
  mu = 0,
  alternative = "two.sided",
  norm_plots = TRUE,
  alpha = 0.05,
  intro_text = TRUE,
  close_generated_files = FALSE,
  open_generated_files = TRUE,
  output_type = "default",
  save_as = NULL,
  save_in_wdir = FALSE,
  ...
)
}
\arguments{
\item{x}{Numeric vector of data values (one-sample or first group for two-sample),
or a formula of the form \code{response ~ group} or \code{response ~ 1}.}

\item{...}{For the formula method: additional arguments forwarded to
the row-filtering step. The arguments \code{subset} and
\code{na.action} are honored: when supplied, they are spliced
(still unevaluated) into a \code{\link[stats]{model.frame}} call
built once before the per-response loop, so the \code{subset}
expression is evaluated in the data's column scope (e.g.
\code{subset = cyl == 6} works). All responses in a multi-response
call (\code{y1 + y2 ~ group}) are then tested on the identical row
set. For the default (vector) method, \code{...} is currently
unused.}

\item{formula}{A formula specifying the model (alternative to using x/y).
\itemize{
  \item \strong{Two-sample (Independent/Paired):} \code{response ~ group}
        (where group has exactly 2 levels).
  \item \strong{One-sample:} \code{response ~ 1} or \code{response ~ NULL}.
}
More response variables can be added using \code{+} (e.g., \code{y1 + y2 ~ group}).}

\item{data}{A data frame containing the variables when using the formula interface.}

\item{paired}{Logical. If \code{TRUE}, performs a paired Wilcoxon test.
  \strong{Note on row order:} For the formula interface, data must be
  sorted so that the observations in the two groups match row-for-row
  (i.e. row 1 of group 1 is paired with row 1 of group 2).
  For the vector interface, \code{x} and \code{y} must have the same length.

  \strong{Note on factor level order:} The formula interface computes
  differences as \code{level1 - level2} based on factor level order,
  which defaults to alphabetical. To control the direction, set the
  reference level explicitly:
  \preformatted{
  # Set levels at creation
  group <- factor(group, levels = c("pre", "post"))

  # Or relevel an existing factor
  group <- relevel(group, ref = "pre")
  }
  A reversed level order flips the sign of the estimate and CI but
  does not affect the W statistic or p-value.}

\item{conf.level}{Numeric. Confidence level of the interval.
Default is \code{1 - alpha}. If \code{conf.level} is specified, then
\code{alpha <- 1 - conf.level}.}

\item{mu}{Numeric. The hypothesised value of the pseudo-median (one-sample) or
location shift (paired/two-sample) under H0. Default is 0.}

\item{alternative}{Character string. \code{"two.sided"} (default),
\code{"greater"}, or \code{"less"}.}

\item{norm_plots}{Logical. If \code{TRUE}, descriptive diagnostic plots are
included in the output. Default is \code{TRUE}.}

\item{alpha}{Numeric. Significance level. Default is \code{0.05}.}

\item{intro_text}{Logical. If \code{TRUE}, includes explanation about Wilcoxon
test assumptions.}

\item{close_generated_files}{Logical. Closes open Excel/Word files before writing.
Works on Windows (taskkill), macOS (pkill) and Linux (pkill/soffice).
Default \code{FALSE}. \strong{WARNING:} Always save your work before using this option!}

\item{open_generated_files}{Logical. Whether to open the generated output
files after creation. Defaults to \code{TRUE} in an interactive R session
and \code{FALSE} otherwise (e.g. in scripts or automated pipelines).
Set to \code{TRUE} or \code{FALSE} to override this behaviour explicitly.}

\item{output_type}{Character string specifying the output format. Default is \code{"default"}.
\itemize{
  \item \code{"default"}: Returns the object and lets R decide whether
    to print; auto-prints if unassigned, silent if assigned to a variable.
    Use \code{print(result)} or \code{plot(result)} to display the
    returned object.
  \item \code{"console"}: Forces immediate printing to the console
    regardless of object assignment.
  \item \code{"pdf"}, \code{"word"}, \code{"excel"}: Saves results to a
    file of the corresponding format. See \code{save_as},
    \code{save_in_wdir}, and \code{open_generated_files} for file
    path and opening behavior.
  \item \code{"rmd"}: Stores the raw markdown string inside the returned
    object for use in R Markdown documents.
}}

\item{save_as}{Character. Specific path/filename for output.}

\item{save_in_wdir}{Logical. Save in working directory.}

\item{y}{Optional numeric vector (second group) for two-sample tests if using
the vector interface. Ignored when a formula is supplied.}
}
\value{
An object of class \code{'f_wilcox_test'}.
}
\description{
Performs One-sample (Wilcoxon signed rank), Two-sample independent (Wilcoxon rank sum /
Mann-Whitney U), or Paired (Wilcoxon signed rank) tests on a given dataset.
Several response parameters can be analysed in sequence (formula interface).
Additionally, a vector interface similar to stats::wilcox.test() is supported.
}
\section{Median vs Pseudo-median}{

By default this function calls \code{stats::wilcox.test(conf.int = TRUE)},
which bases its confidence interval and hypothesis test on the
\strong{Hodges-Lehmann estimator}, not the raw sample median. This is
standard behaviour of the Wilcoxon test, not something specific to this
function. This function explicitly labels the estimator for what it is,
because it is commonly mislabelled as "CI for the median" in textbooks
and software output.

The estimator works differently depending on the test type:

\strong{One-sample:} The \emph{pseudo-median} is the middle value of all
possible pairwise averages of your data points (including each value
paired with itself). For a perfectly symmetric distribution it equals the sample
median; for skewed data the two can differ.

\strong{Paired:} The paired differences (observation 1 minus observation 2
within each pair) are computed first, and the pseudo-median of those
differences is estimated. This is conceptually a one-sample problem
applied to the differences, not a comparison of two independent groups.
The CI is for the pseudo-median of the differences, \strong{not} for the difference
between the two separate sample medians.

\strong{Two-sample independent:} The \emph{location shift} is the median
of all \eqn{n_1 \times n_2} pairwise differences (one value from Group 1
minus one from Group 2). It answers: \emph{by how much does a randomly
chosen value from Group 1 tend to exceed a randomly chosen value from
Group 2?} When both groups have the same distributional shape it equals
the raw difference in sample medians; when shapes differ, the two values can
diverge.

In all three cases the sample median(s) are reported separately for
descriptive purposes only.
}

