Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/satijalab/seurat-wrappers/llms.txt

Use this file to discover all available pages before exploring further.

This page demonstrates the use of estimate_cycle_position from the tricycle Bioconductor package on Seurat objects via SeuratWrappers.
Universal prediction of cell cycle position using transfer learning Shijie C. Zheng, Genevieve Stein-O’Brien, Jonathan J. Augustin, Jared Slosberg, Giovanni A. Carosso, Briana Winer, Gloria Shin, Hans T. Bjornsson, Loyal A. Goff, Kasper D. Hansen bioRxiv, 2021. doi: 10.1101/2021.04.06.438463

​
Installation

The following packages are required before proceeding:
BiocManager::install('tricycle')

library(Seurat)
library(SeuratWrappers)
library(tricycle)

​
Introduction

tricycle infers a continuous cell cycle position for each cell, represented as an angle θ bounded between 0 and 2π. Rather than assigning cells to discrete G1/S/G2M phases, this approach captures the full spectrum of cell cycle states with higher resolution. As a rough guide to interpreting θ values:
θ rangeApproximate cell cycle stage
~0.5πStart of S phase
~πStart of G2M phase
~1.5πMiddle of M phase
~1.75π – 0.25πG1/G0 phase
tricycle requires library-size-adjusted log-expression values as input. When converting from a SingleCellExperiment object, the "logcounts" assay is stored as the "data" slot in the Seurat default assay — use slot = "data" (the default) to ensure correct input.

​
Workflow

1

Load data

This example uses the neurosphere_example dataset bundled with the tricycle package. After converting from SingleCellExperiment to Seurat, log-normalized counts are available in the "data" slot.
data(neurosphere_example, package = "tricycle")
neurosphere_example <- as.Seurat(neurosphere_example)
neurosphere_example
# An object of class Seurat
# 1500 features across 400 samples within 1 assay
# Active assay: RNA (1500 features, 0 variable features)
2

Estimate cell cycle position

Runtricycle() projects cells into the tricycle cell cycle embedding using the package’s internal reference projection matrix, then computes θ (the cell cycle angle). Results are added to the Seurat object in two places:
  • $tricyclePosition: continuous angle θ in [0, 2π] stored in cell metadata
  • A new dimensional reduction (default name: "tricycleEmbedding") with two components
neurosphere_example <- Runtricycle(
  object = neurosphere_example,
  slot = "data",
  gname.type = "ENSEMBL",
  species = "mouse"
)
3

Visualize the embedding

Extract the cell cycle embedding and color cells by their estimated position.
library(ggplot2)
library(cowplot)

plot.df <- FetchData(
  object = neurosphere_example,
  vars = c("tricycleEmbedding_1", "tricycleEmbedding_2", "tricyclePosition")
)

p <- tricycle:::.plot_emb_circle_scale(
  emb.m = plot.df[, 1:2],
  color.value = plot.df$tricyclePosition,
  color_by = "tricyclePosition",
  point.size = 3.5,
  point.alpha = 0.9
)
legend <- circle_scale_legend(text.size = 5, alpha = 0.9)
plot_grid(p, legend, ncol = 2, rel_widths = c(1, 0.4))
You can also color cells by tricyclePosition on any existing embedding (e.g. UMAP or tSNE) using FeaturePlot().
4

Assess performance

A quick way to validate tricycle is to check whether a known cell cycle marker gene oscillates as expected along θ. Top2a is commonly used; its expression should peak near θ = π (G2M boundary).
plot.df <- FetchData(
  object = neurosphere_example,
  vars = c("tricycleEmbedding_1", "tricycleEmbedding_2",
           "tricyclePosition", "ENSMUSG00000020914")
)
names(plot.df)[4] <- "Top2a"

fit.l <- fit_periodic_loess(
  neurosphere_example$tricyclePosition,
  plot.df$Top2a,
  plot = TRUE,
  x_lab = "Cell cycle position θ",
  y_lab = "log2(Top2a)",
  fig.title = paste0("Expression of Top2a along θ (n=",
    ncol(neurosphere_example), ")")
)
fit.l$fig + theme_bw(base_size = 14)
5

Plot kernel density by cell type or condition

plot_ccposition_den() computes a von Mises kernel density of θ conditioned on a phenotype variable, useful for comparing cell cycle distributions across cell types or experimental conditions.
# Cartesian coordinates
plot_ccposition_den(
  neurosphere_example$tricyclePosition,
  neurosphere_example$sample,
  "sample",
  bw = 10,
  fig.title = "Kernel density of θ"
) + theme_bw(base_size = 14)

# Polar coordinates
plot_ccposition_den(
  neurosphere_example$tricyclePosition,
  neurosphere_example$sample,
  "sample",
  type = "circular",
  bw = 10,
  fig.title = "Kernel density of θ"
) + theme_bw(base_size = 14)

​
Functions

​
Runtricycle()

Runs tricycle::estimate_cycle_position on a Seurat object. Internally it calls tricycle:::.project_cycle_space() to project cells into the cell cycle embedding using the package’s built-in reference, then tricycle:::.getTheta() to compute θ. Results are added to both cell metadata and a new DimReduc slot.
​
object
Seurat
required
A Seurat object.
​
assay
string
Name of the assay to use. Defaults to the active assay.
​
slot
string
default:"data"
Slot within the assay to use as input. Should contain library-size-adjusted log-expression values. Defaults to "data", which corresponds to the "logcounts" slot from a SingleCellExperiment converted via as.Seurat().
​
reduction.name
string
default:"tricycleEmbedding"
Name of the dimensional reduction object added to the Seurat object to store the two-dimensional cell cycle projection.
​
reduction.key
string
default:"tricycleEmbedding_"
Key prefix for accessing embedding coordinates (e.g. tricycleEmbedding_1, tricycleEmbedding_2).
​
gname
character vector
Alternative gene names to use for mapping features in object to genes in the tricycle reference. If NULL (the default), the row names of object are used directly.
​
gname.type
string
default:"ENSEMBL"
The gene identifier type. Must be "ENSEMBL" or "SYMBOL". Used when mapping features in object to the reference.
​
species
string
default:"mouse"
Species of the input data. Must be "mouse" or "human".
​
AnnotationDb
AnnotationDb
An AnnotationDb object for mapping Ensembl IDs to gene symbols (used only for human data with Ensembl IDs). If not provided, org.Hs.eg.db is used.
​
center.pc1
number
default:"0"
Center of PC1 used when computing the angle θ from the two-dimensional projection.
​
center.pc2
number
default:"0"
Center of PC2 used when computing the angle θ from the two-dimensional projection.

​
Output added to the Seurat object

SlotContent
object$tricyclePositionContinuous cell cycle position θ ∈ [0, 2π] for each cell
object[[reduction.name]]DimReduc object with the two-dimensional cell cycle embedding (PC1 and PC2 of the projection)

​
Performance assessment

Deeper sequenced datasets will show a clearly ellipsoid pattern in the cell cycle embedding with an empty interior. As sequencing depth decreases, the radius shrinks until the interior disappears — this does not indicate that tricycle has failed. The more reliable quality check is inspecting marker gene expression (e.g. Top2a, Smc2) as a function of θ using fit_periodic_loess(). For more on building custom references or running tricycle outside Seurat, see the tricycle Bioconductor page.

Build docs developers (and LLMs) love

Get started for freeTalk to us