% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/estimate_cycle_position.R
\name{estimate_cycle_position}
\alias{estimate_cycle_position}
\title{Assign cell cycle position}
\usage{
estimate_cycle_position(
  x,
  exprs_values = "logcounts",
  dimred = "tricycleEmbedding",
  center.pc1 = 0,
  center.pc2 = 0,
  altexp = NULL,
  ...
)
}
\arguments{
\item{x}{A numeric matrix of **log-expression** values where rows are features and columns are cells.
Alternatively, a \linkS4class{SummarizedExperiment} or \linkS4class{SingleCellExperiment} containing such a matrix.}

\item{exprs_values}{Integer scalar or string indicating which assay of \code{x} contains the **log-expression** values, which will be used for projection.
If the projection already exists, you can ignore this value. Default: 'logcounts'}

\item{dimred}{The name of reducedDims in  \linkS4class{SingleCellExperiment} (\code{\link[SingleCellExperiment]{reducedDims}}). If the \code{dimred} already exists,
it will be used to assign cell cycle position. If \code{dimred} does not exist, the projection will be calculated first by \code{\link{project_cycle_space}}
and stored with name \code{dimred} in {x}. Default: 'tricycleEmbedding'}

\item{center.pc1}{The center of PC1 when defining the angle. Default: 0}

\item{center.pc2}{The center of PC2 when defining the angle. Default: 0}

\item{altexp}{String or integer scalar specifying an alternative experiment containing the **log-expression** data, which will be used for projection.
If the projection is already calculated and stored in the \linkS4class{SingleCellExperiment} as a dimred, leave this value to default NULL.}

\item{...}{Arguments to be used by \code{\link{project_cycle_space}}. If \code{x} is a \linkS4class{SingleCellExperiment}, and the projection is
already in the reducedDim with name \code{dimred}. The \code{dimred} will be directly used to assign cell cycle position withou new projection.}
}
\value{
If the input is a numeric matrix, the cell cycle position - a numeric vector bound between \eqn{0 \sim 2 \pi} with the same length as the number of input coumlum will be returned.

If the input is \linkS4class{SummarizedExperiment}, the original \linkS4class{SummarizedExperiment} with cell cycle position stored in colData with name 'tricyclePosition' will be returned.

If the input is \linkS4class{SingleCellExperiment}, the original \linkS4class{SingleCellExperiment} with cell cycle position stored in colData with name 'tricyclePosition' will be returned
and the projection will be stored in \code{\link[SingleCellExperiment]{reducedDims}(..., dimred)} if it does not exist before.
}
\description{
Assign cell cycle position by the angle formed by PC1 and PC2 in the cell cycle space.
If the cell cycle projection does not exist, the function will project the data.
}
\details{
The function will use assign the cell cycle position by the angle formed by the PC1 and PC2 of cell cycle projections.
If the input is a numeric matrix or a \linkS4class{SummarizedExperiment}, the projection will be calculated with the input **log-expression** values.
For \linkS4class{SingleCellExperiment}, the projection will also be calculated if the designated \code{dimred} does not exist.
Ohterwise, the \code{dimred} will directly be used to assign cell cycle position.
Therefore, this function is a wrapper function if the input is a \linkS4class{SingleCellExperiment}.
Refer to \code{\link{project_cycle_space}} to all arguments during the projection.

The estimated cell cycle position is bound between 0 and 2pi.
Note that we strive to get high resolution of cell cycle state, and we think
the continuous position is more appropriate when describing the cell cycle.
However, to help users understand the position variable, we also note that 
users can approximately relate 0.5pi to be the start of S stage, pi to be the
start of G2M stage, 1.5pi to be the middle of M stage, and 1.75pi-0.25pi to 
be G1/G0 stage.
}
\examples{
data(neurosphere_example, package = "tricycle")
neurosphere_example <- estimate_cycle_position(neurosphere_example)
reducedDimNames(neurosphere_example)
plot(reducedDim(neurosphere_example, "tricycleEmbedding"))
plot(neurosphere_example$tricyclePosition,
 reducedDim(neurosphere_example, "tricycleEmbedding")[, 1])
plot(neurosphere_example$tricyclePosition,
 reducedDim(neurosphere_example, "tricycleEmbedding")[, 2])
}
\references{
Zheng SC, et al.
\emph{Universal prediction of cell cycle position using transfer learning.}
Genome Biology (2022) 23: 41
doi:\href{https://doi.org/10.1186/s13059-021-02581-y}{10.1186/s13059-021-02581-y}.
}
\seealso{
\code{\link{project_cycle_space}}, for projecting new data with a pre-learned reference
}
\author{
Shijie C. Zheng
}
