bioconductor-simbu

name	bioconductor-simbu
description	SimBu can be used to simulate bulk RNA-seq datasets with known cell type fractions. You can either use your own single-cell study for the simulation or the sfaira database. Different pre-defined simulation scenarios exist, as are options to run custom simulations. Additionally, expression values can be adapted by adding an mRNA bias, which produces more biologically relevant simulations.

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