% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ASE-methods.R
\name{ASE-methods}
\alias{ASE-methods}
\alias{limma_ASE}
\alias{DESeq_ASE}
\alias{DoubleExpSeq_ASE}
\title{Use Limma, DESeq2 or DoubleExpSeq to test for differential Alternative
Splice Events}
\usage{
limma_ASE(
  se,
  test_factor,
  test_nom,
  test_denom,
  batch1 = "",
  batch2 = "",
  filter_antiover = TRUE,
  filter_antinear = FALSE
)

DESeq_ASE(
  se,
  test_factor,
  test_nom,
  test_denom,
  batch1 = "",
  batch2 = "",
  n_threads = 1,
  filter_antiover = TRUE,
  filter_antinear = FALSE
)

DoubleExpSeq_ASE(
  se,
  test_factor,
  test_nom,
  test_denom,
  filter_antiover = TRUE,
  filter_antinear = FALSE
)
}
\arguments{
\item{se}{The \linkS4class{NxtSE} object created by \code{MakeSE()}. To reduce
runtime and avoid excessive multiple testing, consider filtering
the object using \link{apply_filters}}

\item{test_factor}{The condition type which contains the
contrasting variable}

\item{test_nom}{The nominator condition to test for differential ASE. Usually
the "treatment" condition}

\item{test_denom}{The denominator condition to test against for differential
ASE. Usually the "control" condition}

\item{batch1, batch2}{(Optional, limma and DESeq2 only) One or two condition
types containing batch information to account for.}

\item{filter_antiover, filter_antinear}{Whether to remove novel IR events that
overlap over or near anti-sense genes. Default will exclude antiover but
not antinear introns. These are ignored if stranded RNA-seq protocols are
used.}

\item{n_threads}{(DESeq2 only) How many threads to use for DESeq2
based analysis.}
}
\value{
A data table containing the following:
\itemize{
\item EventName: The name of the ASE event. This identifies each ASE
in downstream functions including \link{make_diagonal}, \link{make_matrix},
and \link{Plot_Coverage}
\item EventType: The type of event. See details section above.
\item EventRegion: The genomic coordinates the event occupies. This spans the
most upstream and most downstream splice junction involved in the ASE,
and is use to guide the \link{Plot_Coverage} function.
\item NMD_direction: Indicates whether one isoform is a NMD substrate. +1 means
included isoform is NMD, -1 means the excluded isoform is NMD, and 0
means there is no change in NMD status (i.e. both / neither are NMD)
\item AvgPSI_nom, Avg_PSI_denom: the average percent spliced in / percent
IR levels for the two conditions being contrasted. \code{nom} and \code{denom} in
column names are replaced with the condition names
}

\strong{limma specific output}
\itemize{
\item logFC, AveExpr, t, P.Value, adj.P.Val, B: limma topTable columns of
differential ASE. See \link[limma:toptable]{limma::topTable} for details.
\item inc/exc_(logFC, AveExpr, t, P.Value, adj.P.Val, B): limma results
for differential testing for raw included / excluded counts only
}

\strong{DESeq2 specific output}
\itemize{
\item baseMean, log2FoldChange, lfcSE, stat, pvalue, padj:
DESeq2 results columns for differential ASE; see \link[DESeq2:results]{DESeq2::results} for
details.
\item inc/exc_(baseMean, log2FoldChange, lfcSE, stat, pvalue, padj):
DESeq2 results for differential testing for
raw included / excluded counts only
}

\strong{DoubleExp specific output}
\itemize{
\item MLE_nom, MLE_denom: Expectation values for the two groups. \code{nom} and
\code{denom} in column names are replaced with the condition names
\item MLE_LFC: Log2-fold change of the MLE
\item P.Value, adj.P.Val: Nominal and BH-adjusted P values
\item n_eff: Number of effective samples (i.e. non-zero or non-unity PSI)
\item mDepth: Mean Depth of splice coverage in each of the two groups.
\item Dispersion_Reduced, Dispersion_Full: Dispersion values for reduced and
full models. See \link[DoubleExpSeq:DBGLM1]{DoubleExpSeq::DBGLM1} for details.
}
}
\description{
Use Limma, DESeq2 or DoubleExpSeq to test for differential Alternative
Splice Events
}
\details{
Using \strong{limma}, NxtIRF models included and excluded counts as log-normal
distributed, whereas
using \strong{DESeq2}, NxtIRF models included and excluded counts as negative
binomial distributed with dispersion shrinkage according to their mean count
expressions.
For \strong{limma} and \strong{DESeq2}, differential ASE are considered as the
"interaction" between included and excluded splice counts for each sample.
See \href{https://rpubs.com/mikelove/ase}{this vignette} for an explanation of
how this is done.

Using \strong{DoubleExpSeq}, included and excluded counts are modelled using
the generalized beta prime distribution, using empirical Bayes shrinkage
to estimate dispersion.

\strong{EventType} are as follow:
\itemize{
\item \code{IR} = (novel) intron retention
\item \code{MXE} = mutually exclusive exons
\item \code{SE} = skipped exons
\item \code{AFE} = alternate first exon
\item \code{ALE} = alternate last exon
\item \code{A5SS} = alternate 5'-splice site
\item \code{A3SS} = alternate 3'-splice site
\item \code{RI} = (known / annotated) intron retention.
}

NB: NxtIRF separately considers known "RI" and novel "IR" events separately:
\itemize{
\item \strong{IR} novel events are calculated using the IRFinder method, whereby
spliced transcripts are \strong{all} isoforms that do not retain the intron, as
estimated via the \code{SpliceMax} and \code{SpliceOverMax} methods
}
\itemize{
\item see \link{CollateData}.
}
\itemize{
\item \strong{RI} known retained introns are those that lie completely within a
single exon of another transcript.
(NB: in NxtIRFcore v1.1.1 and later, this encompasses exons from any
transcript, including \code{retained_intron} and \code{sense_intronic} transcripts).
RI's are calculated by considering the specific
spliced intron as a binary event paired with its retention. The spliced
abundance is calculated exclusively by splice reads mapped to the
specific intron boundaries. Known retained introns are those where the
intron retaining transcript is an \strong{annotated} transcript.
In NxtIRFcore \verb{version < 1.1.1},
the IR-transcript's \code{transcript_biotype} must not be
an \code{retained_intron} or \code{sense_intronic}.
}

NxtIRF considers "included" counts as those that represent abundance of the
"included" isoform, whereas "excluded" counts represent the abundance of the
"excluded" isoform.
For consistency, it applies a convention whereby
the "included" transcript is one where its splice junctions
are by definition shorter than those of "excluded" transcripts.
Specifically, this means the included / excluded isoforms are as follows:\tabular{ccc}{
   EventType \tab Included \tab Excluded \cr
   IR or RI \tab Intron Retention \tab Spliced Intron \cr
   MXE \tab Upstream exon inclusion \tab Downstream exon inclusion \cr
   SE \tab Exon inclusion \tab Exon skipping \cr
   AFE \tab Downstream exon usage \tab Upstream exon usage \cr
   ALE \tab Upstream exon usage \tab Downstream exon usage \cr
   A5SS \tab Downstream 5'-SS \tab Upstream 5'-SS \cr
   A3SS \tab Upstream 3'-SS \tab Downstream 3'-SS \cr
}
}
\section{Functions}{
\itemize{
\item \code{limma_ASE}: Use limma to perform differential ASE analysis of
a filtered NxtSE object

\item \code{DESeq_ASE}: Use DESeq2 to perform differential ASE analysis of
a filtered NxtSE object

\item \code{DoubleExpSeq_ASE}: Use DoubleExpSeq to perform differential ASE analysis
of a filtered NxtSE object (uses double exponential beta-binomial model)
to estimate group dispersions, followed by LRT
}}

\examples{
# see ?MakeSE on example code of generating this NxtSE object
se <- NxtIRF_example_NxtSE()

colData(se)$treatment <- rep(c("A", "B"), each = 3)

require("limma")
res_limma <- limma_ASE(se, "treatment", "A", "B")

require("DoubleExpSeq")
res_DES <- DoubleExpSeq_ASE(se, "treatment", "A", "B")
\dontrun{

require("DESeq2")
res_DESeq <- DESeq_ASE(se, "treatment", "A", "B")
}
}
\references{
Ritchie ME, Phipson B, Wu D, Hu Y, Law CW, Shi W, Smyth GK (2015).
'limma powers differential expression analyses for RNA-sequencing and
microarray studies.' Nucleic Acids Research, 43(7), e47.
\url{https://doi.org/10.1093/nar/gkv007}

Love MI, Huber W, Anders S (2014). 'Moderated estimation of fold change and
dispersion for RNA-seq data with DESeq2.' Genome Biology, 15, 550.
\url{https://doi.org/10.1186/s13059-014-0550-8}

Ruddy S, Johnson M, Purdom E (2016). 'Shrinkage of dispersion parameters in
the binomial family, with application to differential exon skipping.'
Ann. Appl. Stat. 10(2): 690-725.
\url{https://doi.org/10.1214/15-AOAS871}
}
