% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fisher.R
\name{fisher_test_pv}
\alias{fisher_test_pv}
\alias{fisher.test.pv}
\title{Fisher's Exact Test for Count Data}
\usage{
fisher_test_pv(
  x,
  alternative = "two.sided",
  ts_method = "minlike",
  exact = TRUE,
  correct = TRUE,
  simple_output = FALSE
)

fisher.test.pv(
  x,
  alternative = "two.sided",
  ts.method = "minlike",
  exact = TRUE,
  correct = TRUE,
  simple.output = FALSE
)
}
\arguments{
\item{x}{integer vector with four elements, a 2-by-2 matrix or an integer
matrix (or data frame) with four columns, where each line
represents a 2-by-2 table to be tested.}

\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{ts_method, ts.method}{single character string that indicates the two-sided p-value computation method (if any value in \code{alternative} equals \code{"two.sided"}) and must be one of \code{"minlike"} (the default), \code{"blaker"}, \code{"absdist"} or \code{"central"} (see details). Ignored, if \code{exact = FALSE}.}

\item{exact}{logical value that indicates whether \eqn{p}-values are to be calculated by exact computation (\code{TRUE}; the default) or by a continuous approximation (\code{FALSE}).}

\item{correct}{logical value that indicates if a continuity correction is to be applied (\code{TRUE}; the default) or not (\code{FALSE}). Ignored, if \code{exact = TRUE}.}

\item{simple_output, 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{fisher_test_pv()} performs Fisher's exact test or a chi-square approximation
to assess if rows and columns of a 2-by-2 contingency table with fixed
marginals are independent. In contrast to \code{\link[stats:fisher.test]{stats::fisher.test()}}, it is
vectorised, only calculates \emph{p}-values and offers a normal approximation of
their computation. Furthermore, it is capable of returning the discrete
\emph{p}-value supports, i.e. all observable \emph{p}-values under a null hypothesis.
Multiple tables can be analysed simultaneously. In two-sided tests, several
procedures of obtaining the respective \emph{p}-values are implemented.

\strong{Note}: Please do not use the older \code{fisher.test.pv()} anymore! It is now
defunct and will be removed in a future version.\cr
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
}
\details{
The parameters \code{x} and \code{alternative} are vectorised. They are replicated
automatically, such that the number of \code{x}'s rows is the same as the length
of \code{alternative}. This allows multiple null hypotheses to be tested
simultaneously. Since \code{x} is (if necessary) coerced to a matrix with four
columns, it is replicated row-wise.

If \code{exact = TRUE}, Fisher's exact test is performed (the specific hypothesis
depends on the value of \code{alternative}). Otherwise, if \code{exact = FALSE}, a
chi-square approximation is used for two-sided hypotheses or a normal
approximation for one-sided tests, based on the square root of the
chi-squared statistic. This is possible because the degrees of freedom of
chi-squared tests on 2-by-2 tables are limited to 1.

For exact computation, various procedures of determining two-sided p-values
are implemented.
\describe{
\item{\code{"minlike"}}{The standard approach in \code{\link[stats:fisher.test]{stats::fisher.test()}} and
\code{\link[stats:binom.test]{stats::binom.test()}}. The probabilities of the
likelihoods that are equal or less than the observed one
are summed up. In Hirji (2006), it is referred to as the
\emph{Probability-based} approach.}
\item{\code{"blaker"}}{The minima of the observations' lower and upper tail
probabilities are combined with the opposite tail not
greater than these minima. More details can be found in
Blaker (2000) or Hirji (2006), where it is referred to as
the \emph{Combined Tails} method.}
\item{\code{"absdist"}}{The probabilities of the absolute distances from the
expected value that are greater than or equal to the
observed one are summed up. In Hirji (2006), it is
referred to as the \emph{Distance from Center} approach.}
\item{\code{"central"}}{The smaller values of the observations' simply doubles
the minimum of lower and upper tail probabilities. In
Hirji (2006), it is referred to as the \emph{Twice the
Smaller Tail} method.}
}
For non-exact (i.e. continuous approximation) approaches, \code{ts_method} is
ignored, since all its methods would yield the same p-values. More
specifically, they all converge to the doubling approach as in
\code{ts_mthod = "central"}.
}
\examples{
# Constructing
S1 <- c(4, 2, 2, 14, 6, 9, 4, 0, 1)
S2 <- c(0, 0, 1, 3, 2, 1, 2, 2, 2)
N1 <- rep(148, 9)
N2 <- rep(132, 9)
F1 <- N1 - S1
F2 <- N2 - S2
df <- data.frame(S1, F1, S2, F2)

# Fisher's exact p-values and their supports
results_ex <- fisher_test_pv(df)
print(results_ex)
results_ex$get_pvalues()
results_ex$get_pvalue_supports()

# Chi-square-approximated p-values and their supports
results_ap <- fisher_test_pv(df, exact = FALSE)
print(results_ap)
results_ap$get_pvalues()
results_ap$get_pvalue_supports()

}
\references{
Fisher, R. A. (1935). The logic of inductive inference.
\emph{Journal of the Royal Statistical Society Series A}, \strong{98}, pp.
39–54. \doi{10.2307/2342435}

Agresti, A. (2002). \emph{Categorical data analysis}. Second Edition. New York:
John Wiley & Sons. pp. 91–97. \doi{10.1002/0471249688}

Blaker, H. (2000). Confidence curves and improved exact confidence intervals
for discrete distributions. \emph{Canadian Journal of Statistics},
\strong{28}(4), pp. 783-798. \doi{10.2307/3315916}

Hirji, K. F. (2006). \emph{Exact analysis of discrete data}. New York: Chapman
and Hall/CRC. pp. 55-83. \doi{10.1201/9781420036190}
}
\seealso{
\code{\link[stats:fisher.test]{stats::fisher.test()}}
}
