SimBu

Workflows

Standard Workflow

Simulate pseudo-bulk RNA-seq data from custom single-cell count matrices or Seurat objects with controlled cell-type fractions and mRNA bias scaling.

library(SimBu)

# Create toy data
counts <- Matrix::Matrix(matrix(stats::rpois(3e5, 5), ncol = 300), sparse = TRUE)
tpm <- Matrix::Matrix(matrix(stats::rpois(3e5, 5), ncol = 300), sparse = TRUE)
tpm <- Matrix::t(1e6 * Matrix::t(tpm) / Matrix::colSums(tpm))
colnames(counts) <- paste0("cell_", rep(1:300))
colnames(tpm) <- paste0("cell_", rep(1:300))
rownames(counts) <- paste0("gene_", rep(1:1000))
rownames(tpm) <- paste0("gene_", rep(1:1000))

annotation <- data.frame(
  "ID" = paste0("cell_", rep(1:300)),
  "cell_type" = c(rep("T cells CD4", 150), rep("T cells CD8", 150))
)

# 1. Merge datasets (Create and merge)
ds1 <- SimBu::dataset(annotation = annotation, count_matrix = counts, tpm_matrix = tpm, name = "test_dataset1")
ds2 <- SimBu::dataset(annotation = annotation, count_matrix = counts, tpm_matrix = tpm, name = "test_dataset2")
ds_merged <- SimBu::dataset_merge(dataset_list = list(ds1, ds2), name = "merged_dataset")

# 2. Simulate pseudo-bulk samples
simulation1 <- SimBu::simulate_bulk(
  data = ds_merged,
  scenario = "random",
  scaling_factor = "NONE",
  ncells = 100,
  nsamples = 10
)

simulation2 <- SimBu::simulate_bulk(
  data = ds_merged,
  scenario = "even",
  scaling_factor = "NONE",
  ncells = 100,
  nsamples = 10
)

# 3. Merge simulations
merged_simulations <- SimBu::merge_simulations(list(simulation1, simulation2))

# 4. Plot the simulation results
SimBu::plot_simulation(simulation = merged_simulations)

Input: Single-cell count matrices and cell type annotations; Output: Simulated pseudo-bulk expression matrices and cell type fraction tables.

When to Use

• Simulating pseudo-bulk RNA-seq datasets with known cell-type fractions using SimBu::simulate_bulk().
• Introducing cell-type-specific mRNA bias using scaling factors (e.g., EPIC or quanTIseq) via the scaling_factor parameter in SimBu::simulate_bulk().
• Creating a unified dataset from Seurat objects using SimBu::dataset_seurat() or merging multiple datasets using SimBu::dataset_merge().

When NOT to Use

• For direct deconvolution of bulk RNA-seq data, use packages like EPIC or quanTIseq because SimBu is a simulation tool, not an estimator.
• For simulating spatial transcriptomics data, use spatialDE because SimBu is designed for bulk RNA-seq simulation from single-cell profiles.

Data Requirements

• Single-cell raw count matrix (mandatory) where genes are in rows and cells are in columns.
• Optional TPM-like scaled count matrix (e.g., TPM, RPKM) with identical dimensions, genes, and cells as the raw count matrix.
• Cell type annotation data frame containing at least ID (matching matrix column names) and cell_type columns.

Key Parameters

• data: A dataset object generated by SimBu::dataset() or SimBu::dataset_seurat().
• scenario ("random"): The simulation scenario to use (e.g., "even", "random", "mirror_db", "weighted", "pure", "custom").
• scaling_factor ("NONE"): Scaling factor to model mRNA bias (e.g., "NONE", "EPIC", "quantiseq").
• ncells: Number of cells to sample for each simulated bulk sample.
• nsamples: Total number of bulk samples to simulate.
• run_parallel (FALSE): Logical indicating whether to run the simulation in parallel.
• whitelist: Vector of cell types to exclusively include in the simulation.

Best Practices

• Provide both raw counts and TPM-like matrices to SimBu::dataset() to generate both count-based and TPM-based pseudo-bulk simulations.
• Filter out genes with zero expression across all cells by setting filter_genes = TRUE during dataset creation.
• Ensure cell type names in the annotation match the pre-defined scaling factor names (e.g., EPIC or quanTIseq) 1:1 to avoid unscaled cell types.

Common Pitfalls

• Missing raw count matrix: Providing only TPM data will fail because raw counts are mandatory for SimBu::dataset().
• Mismatched cell IDs: If cell IDs in the annotation do not match the column names of the count matrix, ensure they match exactly or SimBu will use the intersection.
• Unscaled cell types: Using pre-defined scaling factors with custom cell type names that do not match the standard names will leave those cell types unscaled.

Alternatives

• Seurat: For general single-cell preprocessing and analysis rather than pseudo-bulk simulation.
• scater: For single-cell quality control and visualization.
• scran: For single-cell normalization and variance modeling.

Citations

• Dietrich et al. (2022), SimBu package vignette.
• Fischer et al. (2020), bioRxiv (Sfaira database).

References

• Homepage: bioconductor.org/packages/SimBu
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/SimBu/inst/doc/simbu.html