CellReprogramR Quick Start
Quick Start Guide

CellReprogramR

In silico cellular reprogramming

“A single spark can start a prairie fire.”LOUWENYUAN
I

Install

Remove any old copy, then install the latest version from GitHub with pak.

R console
# 1. remove an old copy (if present)
if ("CellReprogramR" %in% rownames(installed.packages())) {
  remove.packages("CellReprogramR")
}

# 2. install pak, then the newest CellReprogramR from GitHub
if (!requireNamespace("pak", quietly = TRUE)) install.packages("pak")
pak::pkg_install("louwenyuan/CellReprogramR", upgrade = TRUE)

# 3. load it and fix the random seed
library(CellReprogramR)
set.seed(2026)
Check the version

Confirm you really have the newest build: packageDescription("CellReprogramR")$RemoteSha should match the latest commit on GitHub.

II

First run

One line, no arguments. The built-in demo runs end to end.

R console
library(CellReprogramR)

# runs the packaged demo: four tumour states  ->  Oligodendrocyte
results <- run_reprogramming_pipeline()
What the demo does

It loads the example Seurat object and the small L1000 tables shipped in inst/extdata. The start cells are MES-like, AC-like, NPC-like and OPC-like, and the end cell is Oligodendrocyte. Only labels that really exist in the object are used.

What you get back

results is a list holding synergy_table, combo_res, phase_space, flow_df, selected_drugs, plots, run_log and output_dir.

III

Six ways to feed it

Every route calls the same function. Pick the tab that matches how much you want to decide yourself.

A · Built-in demo

Use it when

You want to see the whole pipeline work before touching your own data.

R console
results <- run_reprogramming_pipeline()
IV

Parameters you will use

ArgumentWhat it doesDefault
rds_path / objPath to a Seurat .rds file, or a Seurat object already loaded. Leave both empty to run the demo.NULL
meta_parquet_pathL1000 signature metadata (.parquet). The matrix file is found automatically or downloaded.NULL
cell_type_colMetadata column that holds your cell labels."CellType"
source_typesStart states. Leave empty to use every non-target type.NULL
target_typeEnd state you want to reach.NULL
cell_colorsNamed colour vector for your cell labels.NULL
color_input"code" uses cell_colors; "popup" opens a typing dialog."code"
cell_lines / pert_typesFilter L1000 signatures, for example by cell line or perturbation class.NULL
drug1 / drug2Two perturbations to combine. Empty means the two best distinct ones.NULL
top_nHow many candidates appear in the ranked plots.10
n_permPermutations for the significance test.1000
flow_methodArrow field on the UMAP: "auto", "target" or "manifold"."auto"
make_figureBuild one assembled multi-panel figure.TRUE
figure_page"auto" lets the page grow; "A4" or "A3" fixes the page."auto"
gradient_style"dopamine" gives each bar plot a different random gradient; "reds" uses white to red."dopamine"
gradient_seedReproduce a particular random gradient draw.NULL
seedRandom seed for the permutation tests.2026
run_survivalOptional TCGA / CGGA survival check using virtual marker genes.FALSE
run_pkOptional benchmark against reference perturbagens and global rank.TRUE
output_dirFolder for every figure and table."./Output"
V

What lands in the folder

Each output is produced on its own. If one fails, it is reported and the next one still runs.

Reprogramming_2D_Vector_FlowUMAP with metacells and arrows showing the predicted movement towards the target.
Waddington_2D_LandscapeDensity-based quasi-potential landscape of the metacells.
Synergy_Candidates_DashboardRanked horizontal bars with dose, exposure time and perturbation class.
Candidates_Circular_BarThe same ranking drawn as a circular bar chart.
Candidates_Synergy_Forest_PlotTop-20 candidates ranked by synergy score, with the same annotations.
CellReprogramR_Assembled_FigureAll panels combined as A, B, C. Auto-sized unless you ask for A4 or A3.
Reprogramming_Report.xlsxTables behind every plot, ready for supplementary material.
Reading the console

Nine numbered steps scroll past. A green check means done, a yellow exclamation mark is a warning that was handled, a red cross is an error. Steps 1 to 4 are required; later steps are skipped on error and listed in results$run_log.

VI

If something looks wrong

The figure shows cells I never asked for

Look at the first console step. If it says running on the built-in demo data, no input file was read. If the run stopped with a red message, the figure in your folder is an old one from a previous run. Use a new output_dir such as "./Output_new" to be sure.

Every non-target cell became a start cell

That happens when source_types is empty. Name the start states and the column: cell_type_col = "CellState", source_types = c("MES-like", ...).

Which column holds my labels?

Print the candidates and pick the one that contains your start and end states.

R console
seu <- readRDS("path/to/object.rds")
for (cc in colnames(seu@meta.data)) {
  v <- seu@meta.data[[cc]]
  if ((is.character(v) || is.factor(v)) && nlevels(factor(v)) < 40) {
    cat("\n==", cc, "==\n"); print(table(v))
  }
}
Reproducibility

Use seed = 2026 (the default) for the permutation tests and gradient_seed = 1 (any integer) to reproduce the same random bar colours.

Read the scores with care

Scores are model-based predictions of how well a signature aligns with the path from your start to your end state. They are a ranking for hypothesis generation and need experimental validation.