% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dtu_analysis.R
\name{run_drimseq}
\alias{run_drimseq}
\title{Main filtering and DTU statistical computations}
\usage{
run_drimseq(
  counts,
  tx2gene,
  pd,
  id_col = NULL,
  cond_col,
  cond_levels = NULL,
  filtering_strategy = "bulk",
  add_pseudocount = FALSE,
  BPPARAM = BiocParallel::SerialParam(),
  force_dense = TRUE,
  subset_feature = NULL,
  subset_sample = NULL,
  carry_over_metadata = TRUE,
  filter_only = FALSE,
  ...
)
}
\arguments{
\item{counts}{Can be either:
\enumerate{
\item (sparse) matrix with feature counts, where the rows correspond to features (e.g. transcripts). One column per sample/cell with the count data for the specified features must be present (The names of these columns must match with the identifiers in \code{id_col}).
\item Seurat object with a transcription level assay as \code{active.assay} (most likely result object from \code{\link[=combine_to_matrix]{combine_to_matrix()}})
}}

\item{tx2gene}{Data frame, where the first column consists of feature identifiers and the second column consists of corresponding gene identifiers. Feature identifiers must match with the rownames of the counts object. If a Seurat object is provided in \code{counts} and \code{tx2gene} was provided in \code{\link[=combine_to_matrix]{combine_to_matrix()}}, a vector of the colnames of the specific feature and gene identifiers is sufficient.}

\item{pd}{Data frame with at least a column of sample/cell identifiers (rownames or specified in \code{id_col}) and the comparison group definition (specified in \code{cond_col}).}

\item{id_col}{Name of the column in \code{pd}, where unique sample/cell identifiers are stored. If \code{NULL} (default), use rownames of \code{pd}.}

\item{cond_col}{Name of the column in \code{pd}, where the comparison groups/conditions are defined. If more than 2 levels/groups are present, the groups that should be used must be specified in \code{cond_levels}.}

\item{cond_levels}{Define two levels/groups of \code{cond_col}, that should be compared. The order of the levels states the comparison formula (i.e. \code{cond_col[1]-cond_col[2]}).}

\item{filtering_strategy}{Define the filtering strategy to reduce and noise and increase statistical power.
\itemize{
\item \code{'bulk'}: Predefined strategy for bulk RNAseq data (default): Features must contribute at least 5\% of the total expression in at least 50\% of the samples of the smallest group. Additionally the total gene expression must be 5 or more for at least 50\% of the samples of the smallest group.
\item \code{'sc'}: Predefined strategy for single-cell RNAseq data: Features must contribute at least 5\% of the total expression in at least 5\% of the cells of the smallest group.
\item \code{'own'}: Can be used to specify a user-defined strategy via the \code{...} argument (using the parameters of \code{\link[sparseDRIMSeq:dmFilter]{dmFilter}}).
}}

\item{add_pseudocount}{Define \code{TRUE} if a very small pseudocount shall be added to transcripts with zero expression in one group. Adding the pseudocount enables statistical analysis for comparisons, where one groups proportion is completely zero.}

\item{BPPARAM}{If multicore processing should be used, specify a \code{BiocParallelParam} object here. Among others, can be \code{SerialParam()} (default) for non-multicore processing or \code{MulticoreParam('number_cores')} for multicore processing. See \code{\link[BiocParallel:BiocParallel-package]{BiocParallel}} for more information.}

\item{force_dense}{If you do not want to use a sparse Matrix for DRIMSeq calculations, you can force a dense conversion by specifying \code{TRUE}. Increases memory usage, but also reduces runtime drastically (currently).}

\item{subset_feature}{Subsets the provided count matrix to only specified features. Can be names, indices or logicals.}

\item{subset_sample}{Subsets the provided count matrix to only specified samples. Can be names, indices or logicals.}

\item{carry_over_metadata}{Specify if compatible additional columns of \code{tx2gene} shall be carried over to the gene and transcript level \code{meta_table} in the results. Columns with \code{NA} values are not carried over.}

\item{filter_only}{Return filtered (sparse) matrix, without performing DRIMSeq statistical computations.}

\item{...}{
  Arguments passed on to \code{\link[sparseDRIMSeq:dmFilter]{sparseDRIMSeq::dmFilter}}
  \describe{
    \item{\code{x}}{\code{\linkS4class{dmDSdata}} or \code{\linkS4class{dmSQTLdata}}
object.}
  }}
}
\value{
\code{dturtle} object with the key results, that can be used in the DTUrtle steps hereafter. The object is just a easily accessible list with the following items:
\itemize{
\item \code{meta_table_gene}: Data frame of the expressed-in ratio of all genes. Expressed-in is defined as expression > 0. Can be used to add gene level meta-information for plotting.
\item \code{meta_table_tx}: Data frame of the expressed-in ratio of all transcripts. Expressed-in is defined as expression > 0. Can be used to add transcript level meta-information for plotting.
\item \code{meta_table_sample}: Data frame of the provided sample level information (\code{pd}). Can be used to add sample level meta-information for plotting.
\item \code{drim}: Results of the DRIMSeq statistical computations (\code{dmTest()}).
\item \code{design}: Design matrix generated from the specified \code{pd} columns.
\item \code{group}: Vector which sample/cell belongs to which comparison group.
\item \code{used_filtering_options}: List of the used filtering options.
\item \code{add_pseudocount}: Keeps track if pseudocount was added in comparison.
}

If \code{filter_only=TRUE}, only the filtered (sparse) matrix is returned.
}
\description{
Perform customizable filtering and the main DTU calling with DRIMSeq.
}
\details{
Run the main DRIMSeq pipeline, including generation of a design matrix, gene/feature filtering and running the statistical computations of DRIMSeq (\code{dmPrecision()}, \code{dmFit()} and \code{dmTest()})
}
\seealso{
Other DTUrtle DTU: 
\code{\link{combine_to_matrix}()},
\code{\link{import_counts}()},
\code{\link{posthoc_and_stager}()},
\code{\link{priming_bias_detection_probability}()}
}
\concept{DTUrtle DTU}
