% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils_annotation.R
\name{calculateLigationPvalues}
\alias{calculateLigationPvalues}
\title{Calculate ligation-based significance statistics for RNA duplexes}
\usage{
calculateLigationPvalues(
  gi,
  df_counts,
  id_col = "gene_id",
  compute_binom = TRUE,
  compute_odds = FALSE
)
}
\arguments{
\item{gi}{\code{GInteractions} object annotated with gene/transcript names.}

\item{df_counts}{\code{data.frame}. A two-column data frame with gene/transcript
counts. The first column should match the \verb{<id_col>.A} / \verb{<id_col>.B}
identifiers in \code{gi}. The second column is the corresponding count.}

\item{id_col}{\code{character(1)}. Prefix for gene/transcript metadata fields in
\code{gi}. Two fields, \verb{<id_col>.A} and \verb{<id_col>.B}, are expected.}

\item{compute_binom}{\code{logical(1)}. Whether to compute the binomial
random-ligation test. Default is \code{TRUE}.}

\item{compute_odds}{\code{logical(1)}. Whether to compute the odds-ratio /
Fisher exact test. Default is \code{TRUE}.}
}
\value{
\code{GInteractions} object with added metadata columns.
}
\description{
Calculates significance statistics for each gene/transcript pair represented
in a \code{GInteractions} object. Two optional models are supported:
}
\details{
\enumerate{
\item A binomial random-ligation model, where pair probability is derived from
per-gene/transcript counts and tested using the right-tail binomial test.
\item An odds-ratio / Fisher exact test based on a 2x2 contingency table using
chimeric counts and singleton counts. This test is used in RBP-dependent and
RNA probing methods like RIL-seq
}

The function also outputs abundance fractions for each duplex pair and counts
of other RNA duplexes formed by either or neither gene/transcript in the pair.

\strong{Binomial model}

Null hypothesis: an observed duplex is generated by random ligation.

Alternative hypothesis: the duplex is enriched above the random-ligation
expectation.

The random-ligation probability \eqn{P(a, b)} is defined as:

\deqn{
P(a, b) \propto
\begin{cases}
    2 \cdot P(a) \cdot P(b) & \text{if } a:b \text{ is observed and } a \neq b \\
    P(a)^2                  & \text{if } a:b \text{ is observed and } a = b \\
    0                       & \text{otherwise}
\end{cases}
}

where:

\deqn{
P(a) = \frac{\text{N reads}(a)}{\text{total N reads}}
}

The observed-pair probabilities are renormalized to sum to one and the
p-value is computed from the right tail of the binomial distribution.

\strong{Odds-ratio / Fisher model}

For a pair \verb{(A, B)}, the contingency table is:

\tabular{lll}{
\tab B present \tab B absent\cr
A present     \tab C1        \tab C2\cr
A absent      \tab C3        \tab C4\cr
}

with:
\itemize{
\item \code{C1}: chimeric fragments containing both \code{A} and \code{B}
\item \code{C2}: fragments containing \code{A} but not \code{B}
\item \code{C3}: fragments containing \code{B} but not \code{A}
\item \code{C4}: fragments containing neither \code{A} nor \code{B}
}

A one-sided Fisher exact test (\code{alternative = "greater"}) is used.
}
\examples{
data("RNADuplexesSampleData")
gi <- calculateLigationPvalues(
  RNADuplexSampleDGs,
  df_counts = RNADuplexesGeneCounts
)
hist(gi$p.adj, breaks = 20)

}
