estimate_cycle_position {tricycle} | R Documentation

## Assign cell cycle position

### 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.

### Usage

    estimate_cycle_position(
      x,
      exprs_values = "logcounts",
      dimred = "tricycleEmbedding",
      center.pc1 = 0,
      center.pc2 = 0,
      altexp = NULL,
      ...
    )

### Arguments

`x` | A numeric matrix of **log-expression** values where rows are features and columns are cells. Alternatively, a SummarizedExperiment or SingleCellExperiment containing such a matrix.
`exprs_values` | Integer scalar or string indicating which assay of `x` contains the **log-expression** values, which will be used for projection. If the projection already exists, you can ignore this value. Default: 'logcounts'
`dimred` | The name of reducedDims in SingleCellExperiment (`reducedDims`). If the `dimred` already exists, it will be used to assign cell cycle position. If `dimred` does not exist, the projection will be calculated first by `project_cycle_space` and stored with name `dimred` in x. Default: 'tricycleEmbedding'
`center.pc1` | The center of PC1 when defining the angle. Default: 0
`center.pc2` | The center of PC2 when defining the angle. Default: 0
`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 SingleCellExperiment as a dimred, leave this value to default NULL.
`...` | Arguments to be used by `project_cycle_space`. If `x` is a SingleCellExperiment, and the projection is already in the reducedDim with name `dimred`. The `dimred` will be directly used to assign cell cycle position withou new projection.

### 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 SummarizedExperiment, the projection will be calculated with the input **log-expression** values. For SingleCellExperiment, the projection will also be calculated if the designated `dimred` does not exist. Ohterwise, the `dimred` will directly be used to assign cell cycle position. Therefore, this function is a wrapper function if the input is a SingleCellExperiment. Refer to `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.

### Value

If the input is a numeric matrix, the cell cycle position - a numeric vector bound between 0 \sim 2 π with the same length as the number of input coumlum will be returned.

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

If the input is SingleCellExperiment, the original SingleCellExperiment with cell cycle position stored in colData with name 'tricyclePosition' will be returned and the projection will be stored in `reducedDims(..., dimred)` if it does not exist before.

### Author(s)

Shijie C. Zheng

### References

Zheng SC, et al. Universal prediction of cell cycle position using transfer learning.

### See Also

`project_cycle_space`, for projecting new data with a pre-learned reference

### 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])

[Package tricycle version 1.0.0 Index]