# Simbu

> SimBu

- Skill: `biomate-ai/simbu` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/simbu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/simbu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/simbu

---


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

```r
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