% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/make_plot_data.R
\name{make_plot_data}
\alias{make_plot_data}
\alias{make_matrix}
\alias{make_diagonal}
\title{Construct data of percent-spliced-in (PSI) matrices and "diagonal" for
heatmaps and scatter plots}
\usage{
make_matrix(
  se,
  event_list,
  sample_list = colnames(se),
  method = c("PSI", "logit", "Z-score"),
  depth_threshold = 10,
  logit_max = 5,
  na.percent.max = 0.1
)

make_diagonal(
  se,
  event_list = rownames(se),
  condition,
  nom_DE,
  denom_DE,
  depth_threshold = 10,
  logit_max = 5
)
}
\arguments{
\item{se}{(Required) A \linkS4class{NxtSE} object generated by \link{MakeSE}}

\item{event_list}{A character vector containing the row names of ASE events
(as given by the \code{EventName} column of differential ASE results table
using \code{limma_ASE()} or \code{DESeq_ASE()})}

\item{sample_list}{(default = \code{colnames(se)}) In \code{make_matrix()}, a list of
sample names in the given experiment to be included in the returned matrix}

\item{method}{In \code{make_matrix()}, rhe values to be returned
(default = "PSI"). It can
alternately be "logit" which returns logit-transformed PSI values, or
"Z-score" which returns Z-score-transformed PSI values}

\item{depth_threshold}{(default = 10) Samples with the number of reads
supporting either included or excluded isoforms below this values are
excluded}

\item{logit_max}{(default = 5) PSI values close to 0 or 1 are rounded up/down
to \code{plogis(-logit_max)} and \code{plogis(logit_max)}, respectively. See details.}

\item{na.percent.max}{(default = 0.1) The maximum proportion of values in
the given dataset that were transformed to \code{NA} because of low splicing
depth. ASE events where there are a higher proportion (default 10\%) \code{NA}
values will be excluded from the final matrix. Most heatmap
functions will spring an error if there are too many NA values in any
given row. This option caps the number of NA values to avoid returning
this error.}

\item{condition}{The name of the column containing the condition values in
\code{colData(se)}}

\item{nom_DE}{The condition to be contrasted, e.g. \code{nom_DE = "treatment"}}

\item{denom_DE}{The condition to be contrasted against, e.g.
\code{denom_DE = "control"}}
}
\value{
For \code{make_matrix}: A matrix of PSI (or alternate) values, with
columns as samples and rows as ASE events.

For \code{make_diagonal}: A 3 column data frame, with the first column containing
\code{event_list} list of ASE events, and the last 2 columns containing the
average PSI values of the nominator and denominator conditions.
}
\description{
\code{make_matrix()} constructs a matrix of PSI values of the given alternative
splicing events (ASEs).\cr\cr
\code{make_diagonal()} constructs a table of "average" PSI values, with samples
grouped by two given conditions (e.g. "group A" and "group B") of a given
condition category (e.g. condition "treatment"). See details below.\cr\cr
}
\details{
Note that this function takes the geometric mean of PSI, by first converting
all values to logit(PSI), taking the average logit(PSI) values of each
condition, and then converting back to PSI using inverse logit.

Samples with low splicing coverage (either due to insufficient sequencing
depth or low gene expression) are excluded from calculation of mean PSIs.
The threshold can be set using \code{depth_threshold}. Excluding these samples is
appropriate because the uncertainty of PSI is high when the total included /
excluded count is low. Note that events where all samples in a condition is
excluded will return a value of \code{NaN}.

Using logit-transformed PSI values is appropriate because PSI values are
bound to the (0,1) interval, and are often thought to be beta-distributed.
The link function often used with beta-distributed models is the logit
function, which is defined as \code{logit(x) = function(x) log(x / (1 - x))},
and is equivalent to \link[stats:Logistic]{stats::qlogis}. Its inverse is equivalent to
\link[stats:Logistic]{stats::plogis}.

Users wishing to calculate arithmetic means of PSI are advised to use
\link{make_matrix}, followed by \link{rowMeans} on subsetted sample columns.
}
\section{Functions}{
\itemize{
\item \code{make_matrix}: constructs a matrix of PSI values of the given
alternative splicing events (ASEs)

\item \code{make_diagonal}: constructs a table of "average" PSI values
}}

\examples{
se <- NxtIRF_example_NxtSE()

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

event_list <- rowData(se)$EventName

mat <- make_matrix(se, event_list[1:10])

diag_values <- make_diagonal(se, event_list,
  condition = "treatment", nom_DE = "A", denom_DE = "B"
)
}
