scMultiSim

https://github.com/zhanglabgt/scmultisim
Admin
scMultiSim is an R package for simulating multi-modality single-cell genomic data, including...
Tokens:17,709
Snippets:188
Trust Score:6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure Simulation Speed Options

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Example configuration for optimizing simulation performance.

```r
options_ <- list(
    # ...
    speed.up = T,
    cci = list(
        # ...
        start.layer = ncells
    )
)
```

--------------------------------

### Simulate an example dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_example.Rd

Generates a small example dataset with a specified number of cells.

```R
sim_example(ncells = 10)
```

--------------------------------

### Install scMultiSim from GitHub

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/workflow.Rmd

Install the development version of the package directly from the GitHub repository.

```R
devtools::install_github("ZhangLabGT/scMultiSim@main")
```

--------------------------------

### Phyla1(len = 1)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla1.Rd

Creates a linear example tree of a specified length.

```APIDOC
## Phyla1

### Description
Creates a linear example tree object.

### Signature
`Phyla1(len = 1)`

### Parameters
- **len** (numeric) - Optional - The length of the tree. Defaults to 1.

### Returns
- **phylo** (object) - A R phylo object representing the linear tree.

### Example
```R
Phyla1(len = 1)
```
```

--------------------------------

### Divide batches example

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/divide_batches.Rd

Demonstrates the workflow of simulating data, adding expression noise, and then dividing the results into batches.

```R
results <- sim_example(ncells = 10)
add_expr_noise(results)
divide_batches(results)
```

--------------------------------

### sim_example(ncells = 10, velocity = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_example.Rd

Simulates a small example dataset with 200 cells and the 100-gene GRN.

```APIDOC
## sim_example

### Description
Simulate a small example dataset with 200 cells and the 100-gene GRN.

### Usage
`sim_example(ncells = 10, velocity = FALSE)`

### Arguments
- **ncells** (numeric) - Optional - Number of cells to simulate. Default is 10.
- **velocity** (boolean) - Optional - Whether to simulate RNA velocity. Default is FALSE.

### Returns
- **result** (object) - The simulation result object.
```

--------------------------------

### Simulate spatial example data

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_example_spatial.Rd

Generates a small example dataset with 200 cells and a 100-gene GRN, including cell-cell interaction (CCI) features.

```R
sim_example_spatial(ncells = 10)
```

--------------------------------

### Launch the Shiny Application

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/README.md

Execute the run_shiny function to start the interactive visualization interface for parameter tuning.

```R
run_shiny()
```

--------------------------------

### sim_example_spatial(ncells = 10)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_example_spatial.Rd

Simulate a small example dataset with 200 cells and the 100-gene GRN, with CCI enabled.

```APIDOC
## sim_example_spatial

### Description
Simulate a small example dataset with 200 cells and the 100-gene GRN, with CCI enabled.

### Usage
sim_example_spatial(ncells = 10)

### Arguments
- **ncells** (numeric) - Optional - Number of cells, please increase this number on your machine.

### Value
Returns the simulation result.

### Example
```r
sim_example_spatial(ncells = 10)
```
```

--------------------------------

### Phyla5(plotting = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla5.Rd

Generates an example phylogenetic tree with 5 tips. Users can optionally toggle a console plot of the tree.

```APIDOC
## Phyla5

### Description
Creates an example phylogenetic tree with 5 tips.

### Signature
`Phyla5(plotting = FALSE)`

### Parameters
- **plotting** (logical) - Optional - If TRUE, plots the tree on the console. Defaults to FALSE.

### Returns
- **phylo** (object) - Returns an R phylo object representing the tree.

### Example
```R
# Generate the tree
tree <- Phyla5()

# Generate and plot the tree
Phyla5(plotting = TRUE)
```
```

--------------------------------

### Install scMultiSim via Bioconductor

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/README.md

Use BiocManager to install the scMultiSim package from the Bioconductor repository.

```R
if (!require("BiocManager")) {
  install.packages("BiocManager")
}

BiocManager::install("scMultiSim")
```

--------------------------------

### Phyla3(plotting = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla3.Rd

Generates an example phylo object representing a tree with 3 tips.

```APIDOC
## Phyla3

### Description
Creates an example phylogenetic tree with 3 tips.

### Signature
`Phyla3(plotting = FALSE)`

### Parameters
- **plotting** (logical) - Optional - If TRUE, plots the tree on the console. Defaults to FALSE.

### Returns
- **phylo** (object) - An R phylo object representing the tree.

### Example
```r
# Create a tree with 3 tips
tree <- Phyla3()

# Create and plot a tree with 3 tips
Phyla3(plotting = TRUE)
```
```

--------------------------------

### Generate CCI parameters example

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/cci_cell_type_params.Rd

Demonstrates the basic usage of cci_cell_type_params with a phylogenetic tree and specified interaction parameters.

```R
cci_cell_type_params(Phyla3(), 100, 4:6, 0.5, TRUE, FALSE)
```

--------------------------------

### Implement custom layout

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Define a custom layout function to place cells sequentially starting from the bottom-left corner.

```R
results <- sim_true_counts(spatial_options(
  layout = function (grid_size, cell_types) {
    ncells <- length(cell_types)
    new_locs <- matrix(nrow = ncells, ncol = 2)
    # for each cell...
    for (i in 1:ncells) {
      # ...place it in the grid
      new_locs[i,] <- c(i %% grid_size, i %/% grid_size)
    }
    return(new_locs)
  }
))
plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Simulate Observed Counts

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/True2ObservedCounts.Rd

Example usage of True2ObservedCounts to generate an observed count matrix from simulated data.

```R
\donttest{
results <- sim_example(ncells = 10)
data(gene_len_pool)
gene_len <- sample(gene_len_pool, results$num_genes, replace = FALSE)
True2ObservedCounts(
  results$counts, results$cell_meta, protocol = "nonUMI", randseed = 1,
  alpha_mean = 0.1, alpha_sd = 0.05, gene_len = gene_len, depth_mean = 1e5, depth_sd = 3e3
)
}
```

--------------------------------

### Calculate ATAC-seq correlation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Get_ATAC_correlation.Rd

Example usage of the Get_ATAC_correlation function using simulated data.

```R
results <- sim_example(ncells = 10)
Get_ATAC_correlation(results$counts, results$atacseq_data, results$num_genes)
```

--------------------------------

### Define CCI parameters

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Example of defining the spatial effect between ligand and receptor genes using a data frame.

```R
cci = list(
  params = data.frame(
    target    = c(2,   6,   10,   8, 20,  30),
    regulator = c(101, 102, 103, 104, 105, 106),
    effect    = 20
  )
)
```

--------------------------------

### Accessing help for ext.cif.giv

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Displays the documentation for the ext.cif.giv parameter.

```r
scmultisim_help("ext.cif.giv")
```

--------------------------------

### Load scMultiSim Package

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Initialize the scMultiSim library to begin simulation workflows.

```R
library("scMultiSim")
```

--------------------------------

### Access scMultiSim Help

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Retrieve documentation for simulation options or specific parameters.

```R
scmultisim_help("options")
```

--------------------------------

### Display scMultiSim help documentation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/scmultisim_help.Rd

Call this function to view parameter documentation for topics like options, dynamic.GRN, or cci.

```R
scmultisim_help()
```

--------------------------------

### Access CCI Help Documentation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Displays instructions for configuring the CCI option in scMultiSim.

```r
library(scMultiSim)

scmultisim_help("cci")
```

--------------------------------

### scmultisim_help(topic = NULL)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/scmultisim_help.Rd

Displays detailed documentation for specific parameter topics within the scMultiSim package.

```APIDOC
## scmultisim_help(topic = NULL)

### Description
Displays detailed documentation for scMultiSim's parameters. Users can specify a topic to get targeted information.

### Parameters
- **topic** (string) - Optional - The documentation topic to display. Supported values are 'options', 'dynamic.GRN', or 'cci'.

### Usage Example
```r
# Show general help
scmultisim_help()

# Show help for specific topic
scmultisim_help(topic = "options")
```
```

--------------------------------

### Load and Inspect GRN Parameters

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Load sample GRN data and display the first few rows.

```R
data(GRN_params_100)
GRN_params <- GRN_params_100
head(GRN_params)
```

--------------------------------

### run_shiny()

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/run_shiny.Rd

Launches the Shiny application used to configure simulation parameters.

```APIDOC
## run_shiny()

### Description
Launches the Shiny App to configure the simulation.

### Usage
run_shiny()
```

--------------------------------

### Configure Simulation Parameters

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Settings for kinetic parameter variation, bimodality, scaling, and intrinsic noise levels.

```text
vary

> character (default: "s")

Can be "all", "kon", "koff", "s", "except_kon", "except_koff", "except_s".
It specifies which kinetic parameters to vary across cells, i.e. which kinetic parameters have differential CIFs
sampled from the tree.
```

```text
bimod

> number (default: 0)

A number between 0 and 1, which adjust the bimodality of the gene expression distribution.
```

```text
scale.s

> number (default: 1)

Manually scale the final s parameter, thus the gene expression.
When discrete.cif = T, it can be a vector specifying the scale.s for each cluster.
In this case, you can use smaller value for cell types known to be small (like naive cells).
```

```text
intrinsic.noise

> number (default: 1)

A number between 0 and 1, which specify the weight of the random sample from the Beta-Poisson distribution.

```
       0 <----------------------> 1
Theoritical mean          Random sample from
                      Beta-Poisson distribution
```
```

--------------------------------

### Check dynamic GRN usage

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Displays the help documentation for the dynamic GRN simulation parameters.

```r
scmultisim_help("dynamic.GRN")
```

--------------------------------

### Add extra CIF and GIV with ext.cif.giv

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Use this function to inject additional CIF and GIV matrices into the simulation. The function should return a list containing the extra CIF and GIV matrices, or NULL if no additions are required.

```R
sim_true_counts(list(
    # ...
    ext.cif.giv = function(i) {
        # add extra cif and giv
        return(list(extra_cif, extra_giv))
    }
))
```

--------------------------------

### Simulate with enhanced layout

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Run a simulation using the default enhanced layout where cells are placed near existing cells of the same type.

```R
results <- sim_true_counts(spatial_options(
  layout = "enhanced"
))
plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Execute Simulation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/inst/shiny-app/www/index.html

Run the simulation using the configured parameter object.

```R
res <- sim_true_counts(opt)
```

--------------------------------

### Load match_params dataset in R

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/match_params.Rd

Load the Zeisel UMI cortex kinetic parameters dataset into the R environment.

```R
data(param_realdata.zeisel.imputed)
```

--------------------------------

### Define Options without GRN

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Demonstrates how to configure simulation options when omitting the Gene Regulatory Network.

```r
options <- list(
  GRN = NA
  num.cells = 1000,
  num.genes = 500,
  tree = Phyla5(),
)
```

--------------------------------

### Simulate with layers layout

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Arrange cells in distinct layers using the layers layout option.

```R
results <- sim_true_counts(spatial_options(
  layout = "layers"
))
plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Running the simulation with spatial parameters

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Executes the simulation using the custom CIF/GIV function and spatial interaction parameters.

```r
results <- sim_true_counts(list(
  num.cells = 500,
  num.genes = 300,
  num.cifs = 40,
  GRN = NA,
  speed.up = T,
  cif.sigma = 0.8,
  tree = ape::read.tree(text = "(A:1,B:1,C:1,D:1);"),
  diff.cif.fraction = 0.8,
  ext.cif.giv = ext_cif,
  discrete.cif = T,
  discrete.pop.size = as.integer(c(120,150,100,130)),
  cci = list(
    params = lig_params,
    max.neighbors = 4,
    start.layer = 500,
    cell.type.interaction = "random",
    layout = layout_fn,
    step.size = 1
  )
))
```

--------------------------------

### Load scMultiSim

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/workflow.Rmd

Load the package into the R environment.

```R
library(scMultiSim)
```

--------------------------------

### Execute Simulation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Runs the simulation using the defined options and inspects the output structure.

```r
results <- sim_true_counts(options)
names(results)
```

--------------------------------

### Define Simulation Options

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Configures the simulation parameters including GRN, cell count, CIFs, and RNA velocity settings.

```r
set.seed(42)

options <- list(
  GRN = GRN_params,
  num.cells = 300,
  num.cifs = 20,
  cif.sigma = 1,
  tree = Phyla5(),
  diff.cif.fraction = 0.8,
  do.velocity = TRUE
)
```

--------------------------------

### Simulate counts with custom parameters

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_true_counts.Rd

Executes a simulation using a predefined GRN parameter set and specified cell/CIF counts.

```R
data(GRN_params_100, envir = environment())
sim_true_counts(list(
  rand.seed = 0,
  GRN = GRN_params_100,
  num.cells = 100,
  num.cifs = 50,
  tree = Phyla5()
))
```

--------------------------------

### Define dynamic GRN simulation options

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Configures the simulation parameters including GRN structure, cell counts, and dynamic GRN settings.

```r
set.seed(42)

options_ <- list(
  GRN = GRN_params,
  num.cells = 300,
  num.cifs = 20,
  tree = Phyla1(),
  diff.cif.fraction = 0.8,
  do.velocity = FALSE,
  dynamic.GRN = list(
    cell.per.step = 3,
    num.changing.edges = 5,
    weight.mean = 0,
    weight.sd = 4
  )
)

results <- sim_true_counts(options_)
```

--------------------------------

### Retrieve R Session Information

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Displays the current R session environment, including loaded packages and version details.

```r
sessionInfo()
```

--------------------------------

### Simulate and plot spatial domains

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Executes the simulation using the custom layout function and visualizes the resulting cell locations.

```R
results <- sim_true_counts(list(
  num.cells = 500,
  num.genes = 300,
  num.cifs = 40,
  GRN = NA,
  speed.up = T,
  cif.sigma = 0.8,
  tree = ape::read.tree(text = "(A:1,B:1,C:1,D:1);"),
  diff.cif.fraction = 0.8,
  discrete.cif = T,
  discrete.pop.size = as.integer(c(120,150,100,130)),
  cci = list(
    params = lig_params,
    max.neighbors = 4,
    start.layer = 500,
    cell.type.interaction = "random",
    layout = layout_fn,
    step.size = 1
  )
))

plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Simulate with islands layout

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Configure specific cell types to form central islands in the spatial layout.

```R
results <- sim_true_counts(spatial_options(
  # cell type 4_1_2 should be the island
  layout = "islands:5"
))
plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Simulate with enhanced layout and custom probability

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Adjust the same.type.prob parameter to control the randomness of cell placement in the enhanced layout.

```R
results <- sim_true_counts(spatial_options(
  layout = "enhanced",
  same.type.prob = 0.1
))
plot_cell_loc(results, show.arrows = FALSE)
```

--------------------------------

### Configure RNA Velocity Simulation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Parameters for enabling and tuning the full kinetic model for RNA velocity data generation.

```text
do.velocity

> logical (default: FALSE)

When set to TRUE,
simulate using the full kinetic model and generate RNA velocity data.
Otherwise, the Beta-Poission model will be used.
```

```text
beta

> number (default: 0.4)

The splicing rate of each gene in the kinetic model.
```

```text
d

> number (default: 1)

The degradation rate of each gene in the kinetic model.
```

```text
num.cycles

> number (default: 3)

The number of cycles run before sampling the gene expression of a cell.
```

```text
cycle.len

> number (default: 1)

In velocity mode, a multiplier for the cell cycle length.
It is multiplied by the expected time to
transition from k_on to k_off and back to form the the length of a cycle.
```

--------------------------------

### Load dens_nonzero dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/dens_nonzero.Rd

Load the dens_nonzero dataset into the R environment using the data function.

```R
data(dens_nonzero)
```

--------------------------------

### Simulate Discrete Cell Population

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Configures a simulation with discrete cell populations by setting discrete.cif to TRUE, resulting in distinct clusters based on tree tips.

```R
set.seed(42)

options <- list(
  GRN = GRN_params,
  num.cells = 400,
  num.cifs = 20,
  tree = Phyla5(),
  diff.cif.fraction = 0.8,
  discrete.cif = TRUE
)

results <- sim_true_counts(options)

plot_tsne(log2(results$counts + 1),
         results$cell_meta$pop,
         legend = 'pop', plot.name = 'True RNA Counts Tsne')
```

--------------------------------

### Generate a 5-tip phylogenetic tree

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla5.Rd

Executes the Phyla5 function to return a phylo object.

```R
Phyla5()
```

--------------------------------

### Generate Simple Differentiation Tree

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Create a tree with n leaves for discrete cell clusters.

```R
# tree with four leaves
ape::read.tree(text = "(A:1,B:1,C:1,D:1);");
```

--------------------------------

### sim_true_counts(options, return_summarized_exp = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/sim_true_counts.Rd

Simulates scRNA and scATAC counts. Returns an environment containing simulation results, including counts, metadata, and optional velocity or cell-cell interaction data.

```APIDOC
## sim_true_counts

### Description
Simulate true scRNA and scATAC counts from the provided parameters.

### Parameters
- **options** (list) - Required - Simulation parameters. See scMultiSim_help() for details.
- **return_summarized_exp** (boolean) - Optional - Whether to return a SummarizedExperiment object. Defaults to FALSE.

### Returns
An environment containing simulation results, including:
- **counts**: Gene-by-cell scRNA-seq counts.
- **atac_counts**: Region-by-cell scATAC-seq counts.
- **region_to_gene**: Region-by-gene matrix.
- **cell_meta**: Dataframe with cell type labels and pseudotime.
- **cif/giv/kinetic_params**: Simulation parameters used.
- **.grn**: GRN structure used.

### Example
```r
data(GRN_params_100, envir = environment())
sim_true_counts(list(
  rand.seed = 0,
  GRN = GRN_params_100,
  num.cells = 100,
  num.cifs = 50,
  tree = Phyla5()
))
```
```

--------------------------------

### Visualize Differentiation Trees

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Plot predefined differentiation trees using Phyla functions.

```R
par(mfrow=c(1,2))
Phyla5(plotting = TRUE)
Phyla3(plotting = TRUE)

# It's not possible to plot Phyla1() because it only contains 1 branch connecting two nodes.
Phyla1()
```

--------------------------------

### Visualize a GRN network

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_grn.Rd

Load the GRN parameters and plot the network structure.

```R
data(GRN_params_100, envir = environment())
plot_grn(GRN_params_100)
```

--------------------------------

### Run Spatial CCI Simulation

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Configures simulation options including CCI parameters and executes the simulation.

```r
data(GRN_params_100)
set.seed(42)

options_ <- list(
  GRN = GRN_params_100,
  speed.up = TRUE,
  num.genes = 120,
  num.cells = 80,
  num.cifs = 20,
  cif.sigma = 0.2,
  tree = Phyla3(),
  intrinsic.noise = 0.5,
  cci = list(
    params = lig_params,
    max.neighbors = 4,
    grid.size = 13,
    cell.type.interaction = "random",
    step.size = 0.5
  )
)

results <- sim_true_counts(options_)
```

--------------------------------

### Load GRN_params_100 dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/GRN_params_100.Rd

Load the pre-defined GRN_params_100 dataset into the R environment.

```R
data(GRN_params_100)
```

--------------------------------

### Plotting a phylogenetic tree

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_phyla.Rd

Visualizes a phylogenetic tree using the Phyla5 dataset.

```R
plot_phyla(Phyla5())
```

--------------------------------

### Generate a 3-tip phylogenetic tree

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla3.Rd

Executes the Phyla3 function to return a phylo object.

```R
Phyla3()
```

--------------------------------

### Print regulator target correlations

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/gene_corr_regulator.Rd

Demonstrates how to generate a simulation result object and print the correlations for a specific regulator ID.

```R
results <- sim_example(ncells = 10)
gene_corr_regulator(results, 2)
```

--------------------------------

### Load dplyr and Define Utility Function

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Load the dplyr library and define a helper function for modifying lists.

```R
library(dplyr)
```

```R
list_modify <- function (curr_list, ...) {
  args <- list(...)
  for (i in names(args)) {
    curr_list[[i]] <- args[[i]]
  }
  curr_list
}
```

--------------------------------

### Visualize RNA velocity

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Generate a visualization of RNA velocity using the results object.

```r
plot_rna_velocity(results, arrow.length = 2)
```

--------------------------------

### Load len2nfrag dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/len2nfrag.Rd

Load the pre-computed vector mapping transcript lengths to fragment counts.

```R
data(len2nfrag)
```

--------------------------------

### Generate a linear tree

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/Phyla1.Rd

Creates a linear phylogenetic tree with a specified length.

```R
Phyla1(len = 1)
```

--------------------------------

### gen_clutter(n_cell, grid_size = NA, center = c(0, 0), existing_loc = NULL, existing_grid = NULL)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/gen_clutter.Rd

Generates a cluster of cells by growing from a defined center point. Returns a matrix of cell locations.

```APIDOC
## gen_clutter

### Description
Generates a cluster of cells by growing from a specified center point. This function is used to simulate spatial cell distributions.

### Signature
`gen_clutter(n_cell, grid_size = NA, center = c(0, 0), existing_loc = NULL, existing_grid = NULL)`

### Parameters
- **n_cell** (integer) - The number of cells to generate.
- **grid_size** (numeric) - The width and height of the grid.
- **center** (vector) - The center coordinates of the grid (default: c(0, 0)).
- **existing_loc** (matrix/NULL) - Optional: only place cells on the specified existing locations.
- **existing_grid** (matrix/NULL) - Optional: manually specify what locations are in the grid.

### Returns
- **matrix** - A matrix of cell locations.

### Example
`gen_clutter(10, 10, c(5, 5))`
```

--------------------------------

### Configure and simulate long-distance CCI

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Sets up simulation parameters with varying Gaussian sigma values for the interaction radius and executes the simulation.

```r
options <- lapply(c(1, 3), \(sigma) {
  list(
    rand.seed = 1,
    GRN = NA,
    num.genes = 200,
    num.cells = 500,
    num.cifs = 50,
    tree = Phyla5(),
    discrete.cif = T,
    discrete.min.pop.size = 20,
    discrete.pop.size = as.integer(c(110, 80, 140, 40, 130)),
    do.velocity = F,
    scale.s = 1,
    cci = list(
      params = lig_params,
      max.neighbors = 4,
      cell.type.interaction = "random",
      cell.type.lr.pairs = 3:6,
      step.size = 0.3,
      grid.size = 35,
      start.layer = 500,
      radius = paste0("gaussian:", sigma),
      layout = "layers"
    )
  )

})

results_1 <- sim_true_counts(options[[1]])
results_3 <- sim_true_counts(options[[2]])
```

--------------------------------

### Define spatial options helper function

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

A helper function to standardize the configuration of spatial parameters for simulations.

```R
spatial_options <- function (...) {
  cci_opt <- list(
    params = lig_params,
    max.neighbors = 4,
    start.layer = 300,
    grid.size = 28,
    cell.type.interaction = "random"
  )
  list(
    rand.seed = 0,
    GRN = GRN_params_100,
    speed.up = TRUE,
    num.genes = 200,
    num.cells = 300,
    num.cifs = 50,
    tree = Phyla3(),
    cci = c(cci_opt, list(...))
  )
}
```

--------------------------------

### Customization Hooks

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Functional hooks for modifying or extending CIF and GIV matrices during the simulation process.

```APIDOC
## Customization Hooks

### mod.cif.giv
- **Type**: function
- **Description**: Allows modification of generated CIF and GIV matrices. The function accepts (index, cif, giv, meta) and returns a list containing the modified CIF and GIV matrices.

### ext.cif.giv
- **Type**: function
- **Description**: Allows addition of extra CIF and GIV matrices. The function accepts the kinetic parameter index and returns a list containing the extra CIF and GIV matrices.
```

--------------------------------

### True2ObservedCounts(true_counts, meta_cell, protocol, randseed, ...)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/True2ObservedCounts.Rd

Simulates an observed count matrix based on technical biases and true counts.

```APIDOC
## True2ObservedCounts

### Description
Simulate observed count matrix given technical biases and the true counts.

### Signature
True2ObservedCounts(true_counts, meta_cell, protocol, randseed, alpha_mean = 0.1, alpha_sd = 0.002, alpha_gene_mean = 1, alpha_gene_sd = 0, gene_len, depth_mean, depth_sd, lenslope = 0.02, nbins = 20, amp_bias_limit = c(-0.2, 0.2), rate_2PCR = 0.8, nPCR1 = 16, nPCR2 = 10, LinearAmp = FALSE, LinearAmp_coef = 2000)

### Parameters
- **true_counts** (matrix) - Gene cell matrix.
- **meta_cell** (data.frame) - Meta information related to cells.
- **protocol** (string) - Can be "nonUMI" or "UMI".
- **randseed** (numeric) - Seed for reproducibility.
- **alpha_mean** (numeric) - Mean rate of subsampling of transcripts during capture step.
- **alpha_sd** (numeric) - Std of rate of subsampling of transcripts.
- **alpha_gene_mean** (numeric) - Per-gene scale factor of the alpha parameter.
- **alpha_gene_sd** (numeric) - Standard deviation of the per-gene scale factor.
- **gene_len** (vector) - Lengths of all genes.
- **depth_mean** (numeric) - Mean of sequencing depth.
- **depth_sd** (numeric) - Std of sequencing depth.
- **lenslope** (numeric) - Amount of length bias.
- **nbins** (numeric) - Number of bins for gene length.
- **amp_bias_limit** (vector) - Range of amplification bias for each gene.
- **rate_2PCR** (numeric) - PCR efficiency.
- **nPCR1** (numeric) - Number of PCR cycles in pre-amplification step.
- **nPCR2** (numeric) - Number of PCR cycles used after fragmentation.
- **LinearAmp** (boolean) - Whether linear amplification is used.
- **LinearAmp_coef** (numeric) - Coefficient of linear amplification.

### Returns
- If UMI: A list containing the observed count matrix and metadata.
- If nonUMI: A matrix of observed counts.
```

--------------------------------

### Add batch effects to dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Divide the results into batches to simulate batch effects, adding a counts_with_batches field.

```r
divide_batches(
  results,
  nbatch = 2,
  effect = 1
)
```

--------------------------------

### Load GRN_params_1139 dataset

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/GRN_params_1139.Rd

Load the GRN_params_1139 dataset into the R environment.

```R
data(GRN_params_1139)
```

--------------------------------

### Visualize cell locations

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_cell_loc.Rd

Generates a plot showing cell positions and interactions based on simulation results.

```R
results <- sim_example_spatial(ncells = 10)
plot_cell_loc(results)
```

--------------------------------

### Adding experimental noise to simulation results

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/add_expr_noise.Rd

Applies default experimental noise to a previously generated simulation object.

```R
results <- sim_example(ncells = 10)
add_expr_noise(results)
```

--------------------------------

### Visualize the CCI grid

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_grid.Rd

Generates a plot of the CCI grid using a simulation result object.

```R
results <- sim_example_spatial(ncells = 10)
plot_grid(results)
```

--------------------------------

### ATAC Simulation Options

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Configuration parameters for controlling the influence of chromatin accessibility and the distribution of regulatory regions in ATAC-seq simulations.

```APIDOC
## ATAC Simulation Parameters

### atac.effect
- **Type**: number (0 to 1)
- **Default**: 0.5
- **Description**: The influence of chromatin accessibility data on gene expression.

### region.distrib
- **Type**: vector (length 3)
- **Default**: c(0.1, 0.5, 0.4)
- **Description**: The probability that a gene is regulated by 0, 1, or 2 consecutive regions, respectively. Must sum to 1.

### atac.p_zero
- **Type**: number (0 to 1)
- **Default**: 0.8
- **Description**: The proportion of zeros observed in the simulated scATAC-seq data.

### riv.mean, riv.sd, riv.prob
- **Default**: 0, 1, 0.3
- **Description**: Parameters for sampling Region Identity Vectors (RIV). With probability `riv.prob`, values are sampled from N(riv.mean, riv.sd); otherwise, the value is 0.
```

--------------------------------

### Visualize RNA counts with batch effects

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Visualize the modified RNA counts after applying batch effects using t-SNE.

```r
plot_tsne(log2(results$counts_with_batches + 1),
          results$cell_meta$pop,
          legend = 'pop', plot.name = 'RNA Counts Tsne with Batches')
```

--------------------------------

### Adjusting Intrinsic Noise with intrinsic.noise

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Demonstrates the effect of the intrinsic.noise parameter on RNA count simulations when using the Beta-Poisson model.

```R
set.seed(42)

options <- list(
  GRN = GRN_params,
  num.cells = 300,
  num.cifs = 20,
  tree = Phyla5(),
  diff.cif.fraction = 0.8,
  intrinsic.noise = 1
)

results <- sim_true_counts(
        options %>% list_modify(intrinsic.noise = 0.5))
plot_tsne(log2(results$counts + 1),
         results$cell_meta$pop,
         legend = 'pop', plot.name = 'RNA Counts (intrinsic.noise = 0.5)')

results <- sim_true_counts(
        options %>% list_modify(intrinsic.noise = 1))
plot_tsne(log2(results$counts + 1),
         results$cell_meta$pop,
         legend = 'pop', plot.name = 'RNA Counts (intrinsic.noise = 1)')
```

--------------------------------

### Customize CIF and GIV with mod.cif.giv

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/options.Rmd

Use this function to modify existing CIF and GIV matrices during simulation. The function must return a list containing the modified CIF and GIV matrices.

```R
sim_true_counts(list(
    # ...
    mod.cif.giv = function(i, cif, giv, meta) {
        # modify cif and giv
        return(list(cif, giv))
    }
))
```

--------------------------------

### gene_corr_cci(results, all.genes = FALSE, .pair = NULL, .exclude.same.types = TRUE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/gene_corr_cci.Rd

Plots the ligand-receptor correlation summary based on the provided simulation results.

```APIDOC
## gene_corr_cci

### Description
Plots the ligand-receptor correlation summary from scMultisim simulation results.

### Arguments
- **results** (object) - Optional - The scMultisim result object. Defaults to .getResultsFromGlobal().
- **all.genes** (boolean) - Optional - Whether to use all genes or only the ligand/receptor genes. Defaults to FALSE.
- **.pair** (string/null) - Optional - Return the raw data for the given LR pair. Defaults to NULL.
- **.exclude.same.types** (boolean) - Optional - Whether to exclude neighbor cells with same cell type. Defaults to TRUE.

### Returns
- **none** - This function generates a plot and does not return a value.

### Example
results <- sim_example_spatial(ncells = 10)
gene_corr_cci(results)
```

--------------------------------

### Add technical noise and batch effects

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/workflow.Rmd

Apply technical noise and batch effects to the simulated dataset.

```R
add_expr_noise(results)
divide_batches(results, nbatch = 2)
```

--------------------------------

### Simulate true counts

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/workflow.Rmd

Generate true counts using the sim_true_counts function with specified GRN and tree parameters.

```R
data(GRN_params_100)

results <- sim_true_counts(list(
  # required options
  GRN = GRN_params_100,
  tree = Phyla3(),
  num.cells = 500,
  # optional options
  num.cif = 20,
  discrete.cif = F,
  cif.sigma = 0.1
  # ... other options
))
```

--------------------------------

### Simulate Observed ATAC-seq Data

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/True2ObservedATAC.Rd

Demonstrates the application of technical noise to a simulated ATAC-seq count matrix.

```R
results <- sim_example(ncells = 10)
True2ObservedATAC(results$atac_counts, randseed = 1)
```

--------------------------------

### plot_phyla(tree)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_phyla.Rd

Plots a phylogenetic tree provided as an input object.

```APIDOC
## plot_phyla(tree)

### Description
Plots a phylogenetic tree.

### Parameters
- **tree** (object) - Required - The phylogenetic tree object to be plotted.

### Usage
plot_phyla(tree)

### Example
plot_phyla(Phyla5())
```

--------------------------------

### plot_grn(params)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_grn.Rd

Visualizes the GRN network using the provided parameters data frame.

```APIDOC
## plot_grn(params)

### Description
Plots the Gene Regulatory Network (GRN) based on the provided parameters.

### Parameters
- **params** (data frame) - Required - The GRN parameters data frame.

### Example
```r
data(GRN_params_100, envir = environment())
plot_grn(GRN_params_100)
```
```

--------------------------------

### cci_cell_type_params(tree, total.lr, ctype.lr = 4:6, step.size = 1, rand = TRUE, discrete = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/cci_cell_type_params.Rd

Generates a 3D matrix of (n_cell_type, n_cell_type, n_lr) where the value at (i, j, k) is 1 if there exists a CCI of LR-pair k between cell type i and cell type j.

```APIDOC
## cci_cell_type_params

### Description
Generates cell-type level CCI parameters. This function returns a 3D matrix representing the ground truth for cell-type level interactions.

### Parameters
- **tree** (object) - Required - Use the same value for sim_true_counts().
- **total.lr** (numeric) - Required - Total number of LR pairs in the database. Use the same value for sim_true_counts().
- **ctype.lr** (numeric) - Optional - If rand is TRUE, how many LR pairs should be enabled between each cell type pair. Default is 4:6.
- **step.size** (numeric) - Optional - Use the same value for sim_true_counts(). Default is 1.
- **rand** (boolean) - Optional - Whether to fill the matrix randomly. Default is TRUE.
- **discrete** (boolean) - Optional - Whether the cell population is discrete. Use the same value for sim_true_counts(). Default is FALSE.

### Returns
- **matrix** (3D) - A 3D matrix of (n_cell_type, n_cell_type, n_lr). The value at (i, j, k) is 1 if there exist CCI of LR-pair k between cell type i and cell type j.

### Example
cci_cell_type_params(Phyla3(), 100, 4:6, 0.5, TRUE, FALSE)
```

--------------------------------

### plot_gene_module_cor_heatmap(results = .getResultsFromGlobal(), seed = 0, grn.genes.only = TRUE, save = FALSE)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_gene_module_cor_heatmap.Rd

Generates a gene module correlation heatmap from simulation results.

```APIDOC
## plot_gene_module_cor_heatmap

### Description
Plots the gene module correlation heatmap based on the provided scMultisim result object.

### Parameters
- **results** (object) - Optional - The scMultisim result object. Defaults to .getResultsFromGlobal().
- **seed** (numeric) - Optional - The random seed. Defaults to 0.
- **grn.genes.only** (boolean) - Optional - Whether to plot only GRN genes. Defaults to TRUE.
- **save** (boolean) - Optional - Whether to save the plot as a PDF. Defaults to FALSE.

### Returns
- **none**

### Example
```r
results <- sim_example(ncells = 10)
plot_gene_module_cor_heatmap(results)
```
```

--------------------------------

### Custom layout function signature

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

The required function signature for implementing a custom spatial layout.

```R
# grid_size is a number
# cell_types is an integer vector, representing the cell types
function(grids_size, cell_types) {
  # return a matrix with two columns, representing the x and y coordinates of the cells
  return matrix(nrow = 2, ncol = ncells)
}
```

--------------------------------

### Adjusting Cell Heterogeneity with cif.sigma

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/basics.Rmd

Visualizes the impact of varying the cif.sigma parameter on cell heterogeneity using t-SNE plots.

```R
set.seed(42)

options <- list(
  GRN = GRN_params,
  num.cells = 300,
  num.cifs = 20,
  tree = Phyla5(),
  diff.cif.fraction = 0.8,
  cif.sigma = 0.5
)

results <- sim_true_counts(
        options %>% list_modify(cif.sigma = 0.1))
plot_tsne(log2(results$counts + 1),
         results$cell_meta$pop,
         legend = 'pop', plot.name = 'RNA Counts (cif.sigma = 0.1)')

results <- sim_true_counts(
        options %>% list_modify(cif.sigma = 1.0))
plot_tsne(log2(results$counts + 1),
         results$cell_meta$pop,
         legend = 'pop', plot.name = 'RNA Counts (cif.sigma = 1.0)')
```

--------------------------------

### Define custom spatial layout function

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/vignettes/spatialCCI.Rmd

Creates a layout function that assigns cells to circular locations and partitions them into three domains based on distance to the origin.

```R
layout_fn <- function(grid_size, final_types) {
  ncells <- length(final_types)
  grid_center <- c(round(grid_size / 2), round(grid_size / 2))
  all_locs <- gen_clutter(ncells, grid_size, grid_center)
  # center is bottom-left
  left_ones <- which(all_locs[,1] == min(all_locs[,1]))
  new_center <<- all_locs[left_ones[which.min(all_locs[left_ones, 2])],]
  dist_to_center <- sqrt(colSums((t(all_locs) - new_center)^2))
  new_locs <- all_locs[order(dist_to_center),]
  # prob of a cell type being in a zone (cell_type x zone)
  ct_matrix <- matrix(c(
    0.9, 0.1, 0.0,
    0.1, 0.8, 0.1,
    0.1, 0.7, 0.2,
    0.0, 0.1, 0.9
  ), nrow = 4, byrow = TRUE)
  # number of cells per type
  ct_pop <- c(160, 80, 100, 140)
  pop_mtx <- round(ct_matrix * ct_pop)
  if (sum(pop_mtx) != ncells) {
    diffrence <- ncells - sum(pop_mtx)
    pop_mtx[1, 1] <- pop_mtx[1, 1] + diffrence
  }
  # number of cells per zone
  zone_pop <- colSums(pop_mtx)
  # assign cells to zones
  cs <- cumsum(zone_pop)
  # sample cells
  cell_idx <- unlist(lapply(1:3, function(izone) {
    sample(rep(1:4, pop_mtx[,izone]), zone_pop[izone])
  }))
  locs <<- new_locs[order(cell_idx),]
  zone_gt <<- rep(1:3, zone_pop)[order(cell_idx)]
  return(locs)
}
```

--------------------------------

### plot_tsne(data, labels, perplexity = 60, legend = "", plot.name = "", save = FALSE, rand.seed = 0, continuous = FALSE, labels2 = NULL, lim = NULL, runPCA = FALSE, alpha = 1)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_tsne.Rd

Generates a t-SNE plot from a d x n matrix. It can optionally save the output as a PDF and supports continuous or categorical labeling.

```APIDOC
## plot_tsne

### Description
Plot t-SNE visualization of a data matrix.

### Parameters
- **data** (matrix) - Required - The d x n matrix.
- **labels** (vector) - Required - A vector of length n, usually cell clusters.
- **perplexity** (numeric) - Optional - Perplexity value used for t-SNE (default: 60).
- **legend** (list) - Optional - A list of colors for the labels.
- **plot.name** (string) - Optional - The plot title.
- **save** (boolean) - Optional - If TRUE, save as plot.name.pdf (default: FALSE).
- **rand.seed** (numeric) - Optional - The random seed (default: 0).
- **continuous** (boolean) - Optional - Whether labels should be treated as continuous, e.g. pseudotime (default: FALSE).
- **labels2** (vector) - Optional - Additional label.
- **lim** (vector) - Optional - Specify the xlim and y lim c(x_min, x_max, y_min, y_max).
- **runPCA** (boolean) - Optional - Whether to run PCA before t-SNE (default: FALSE).
- **alpha** (numeric) - Optional - The alpha value for the points (default: 1).

### Returns
The figure if not save, otherwise saves the figure as plot.name.pdf.

### Example
results <- sim_example(ncells = 10)
plot_tsne(log2(results$counts + 1), results$cell_meta$pop, perplexity = 3)
```

--------------------------------

### plot_rna_velocity(results = .getResultsFromGlobal(), velocity = results$velocity, perplexity = 70, arrow.length = 1, save = FALSE, randseed = 0, ...)

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/plot_rna_velocity.Rd

Plots RNA velocity as arrows on a tSNE projection based on the provided scMultiSim result object.

```APIDOC
## plot_rna_velocity

### Description
Plots RNA velocity as arrows on a tSNE plot to visualize cellular dynamics.

### Parameters
- **results** (object) - Optional - The scMultiSim result object. Defaults to .getResultsFromGlobal().
- **velocity** (matrix) - Optional - The velocity matrix. Defaults to results$velocity.
- **perplexity** (numeric) - Optional - The perplexity parameter for tSNE. Defaults to 70.
- **arrow.length** (numeric) - Optional - The length scaler of the arrow. Defaults to 1.
- **save** (boolean) - Optional - Whether to save the plot. Defaults to FALSE.
- **randseed** (numeric) - Optional - The random seed for reproducibility. Defaults to 0.
- **...** (dots) - Optional - Other parameters passed to ggplot.

### Returns
- **plot** (ggplot) - The generated tSNE plot with velocity arrows.

### Example
```r
results <- sim_example(ncells = 10, velocity = TRUE)
plot_rna_velocity(results, perplexity = 3)
```
```

--------------------------------

### Generate a cell cluster

Source: https://github.com/zhanglabgt/scmultisim/blob/bioconductor/man/gen_clutter.Rd

Creates a cluster of 10 cells within a 10x10 grid centered at coordinates (5, 5).

```R
gen_clutter(10, 10, c(5, 5))
```
Tokens:
Raw