% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/normalization.R
\name{relative2abs}
\alias{relative2abs}
\title{Transform relative expression values into absolute transcript counts.}
\usage{
relative2abs(
  relative_cds,
  t_estimate = estimate_t(exprs(relative_cds)),
  modelFormulaStr = "~1",
  ERCC_controls = NULL,
  ERCC_annotation = NULL,
  volume = 10,
  dilution = 40000,
  mixture_type = 1,
  detection_threshold = 800,
  expected_capture_rate = 0.25,
  verbose = FALSE,
  return_all = FALSE,
  method = c("num_genes", "tpm_fraction"),
  cores = 1
)
}
\arguments{
\item{relative_cds}{the cds object of relative expression values for single cell RNA-seq with each row and column representing genes/isoforms and cells. Row and column names should be included}

\item{t_estimate}{an vector for the estimated most abundant FPKM value of isoform for a single cell. Estimators based on gene-level relative expression can also give good approximation but estimators
based on isoform FPKM will give better results in general}

\item{modelFormulaStr}{modelformula used to grouping cells for transcript counts recovery. Default is "~ 1", which means to recover the transcript counts from all cells.}

\item{ERCC_controls}{the FPKM matrix for each ERCC spike-in transcript in the cells if user wants to perform the transformation based on their spike-in data. Note that the row and column names should match up with the ERCC_annotation and relative_exprs_matrix respectively.}

\item{ERCC_annotation}{the ERCC_annotation matrix from illumina USE GUIDE which will be ued for calculating the ERCC transcript copy number for performing the transformation.}

\item{volume}{the approximate volume of the lysis chamber (nanoliters). Default is 10}

\item{dilution}{the dilution of the spikein transcript in the lysis reaction mix. Default is 40, 000. The number of spike-in transcripts per single-cell lysis reaction was calculated from}

\item{mixture_type}{the type of spikein transcripts from the spikein mixture added in the experiments. By default, it is mixture 1. Note that m/c we inferred are also based on mixture 1.}

\item{detection_threshold}{the lowest concentration of spikein transcript considered for the regression. Default is 800 which will ensure (almost) all included spike transcripts expressed in all the cells. Also note that the value of c is based on this concentration.}

\item{expected_capture_rate}{the expected fraction of RNA molecules in the lysate that will be captured as cDNAs during reverse transcription}

\item{verbose}{a logical flag to determine whether or not we should print all the optimization details}

\item{return_all}{parameter for the intended return results. If setting TRUE, matrix of m, c, k^*, b^* as well as the transformed absolute cds will be returned
in a list format}

\item{method}{the formula to estimate the total mRNAs (num_genes corresponds to the second formula while tpm_fraction corresponds to the first formula, see the anouncement on Trapnell lab website for the Census paper)}

\item{cores}{number of cores to perform the recovery. The recovery algorithm is very efficient so multiple cores only needed when we have very huge number of cells or genes.}
}
\value{
an matrix of absolute count for isoforms or genes after the transformation.
}
\description{
Converts FPKM/TPM data to transcript counts. This allows for the use for negative binomial
as an expressionFamily. These results are often far more accurate than using tobit().
}
\details{
Transform a relative expression matrix to absolute transcript matrix based on the inferred linear regression parameters from most abundant isoform relative expression value.
This function takes a relative expression matrix and a vector of estimated most abundant expression value from the isoform-level matrix and transform it into absolute transcript number.
It is based on the observation that the recovery efficient of the single-cell RNA-seq is relative low and that most expressed isoforms of gene in a single cell therefore only sequenced one copy so that the 
most abundant isoform log10-FPKM (t^*) will corresponding to 1 copy transcript. It is also based on the fact that the spikein regression parameters k/b for each cell will fall on a line because of the 
intrinsic properties of spikein experiments. We also assume that if we perform the same spikein experiments as Treutlein et al. did, the regression parameters should also fall on a line in the same way. The
function takes the the vector t^* and the detection limit as input, then it uses the t^* and the m/c value corresponding to the detection limit to calculate two parameters vectors k^* and b^* (corresponding to each cell)
which correspond to the slope and intercept for the linear conversion function between log10 FPKM and log10 transcript counts. The function will then apply a linear transformation 
to convert the FPKM to estimated absolute transcript counts based on the the k^* and b^*. The default m/c values used in the algoritm are 3.652201, 2.263576, respectively.
}
\examples{
\dontrun{
HSMM_relative_expr_matrix <- exprs(HSMM)
HSMM_abs_matrix <- relative2abs(HSMM_relative_expr_matrix, 
   t_estimate = estimate_t(HSMM_relative_expr_matrix))
}
}
