# Simulating Spatial Cell-Cell Interactions

##

###

# Simulating Spatial Cell-Cell Interactions

scMultiSim can simulate spatial cell-cell interactions. To do so, we need to provide the `cci` option as a list. The following code will print more instructions on how to use the `cci` option.

    library(scMultiSim)

    scmultisim_help("cci")

    ##
    ## To enable simulating cell-cell interaction, the value should be a list including
    ## the following names:
    ##
    ## - params: (data.frame)
    ##     The spatial effect between neighbor cells.
    ##     It should be a data frame similar to the GRN parameter.
    ## - step.size: (number, optional)
    ##     If using continuous population, use this step size to further divide the
    ##     cell types on the tree. For example, if the tree only has one branch 1 -> 2
    ##     and the branch length is 1 while the step size is 0.34, there will be totally
    ##     three cell types: 1_2_1, 1_2_2, 1_2_3.
    ## - cell.type.interaction: ("random" or a matrix)
    ##     The interaction level between different cell types.
    ##     They act as factors multiplied to the ligand effect.
    ##     Supply the string "random" to let scMultiSim generate these factors randomly.
    ##     Otherwise, use cci_cell_type_params() to generate the template data structure.
    ##     See the help of this method for more info.
    ## - max.neighbors: (integer from 1 to 4, optional)
    ##     Constraint the maxinum number of neighbors with CCI for each cell.
    ##     The neighbors with CCI will be randomly sampled.
    ##

    ## NULL

Now, we prepare a ligand-receptor interaction database. This is pretty similar to the GRN network: it is a data frame with three columns, specifying `target`, `regulator`, and `effect`, respectively. The target and regulator columns should contain the IDs of the target and regulator genes. In the following example, we have two ligand-receptor pairs interacting between two neighboring cells.

    lig_params <- data.frame(
      target    = c(101, 102),
      regulator = c(103, 104),
      effect    = c(5.2, 5.9)
    )

We can now simulate the spatial cell-cell interactions. In scMultiSim, the CCI network is cell-type based, which means that between each cell type pair, we can have a different CCI network sampled from the database defined above. Here, we set the `step.size` to 0.5, so the differentiation tree is divided into segments of length 0.5, each segment is treated as a cell type in CCI. We set `cell.type.interaction` to `random`, so the CCI network between each cell type pair is randomly sampled from the database.

Here, we use only 100 cells to speed up the simulation. Feel free to try a larger number of cells when running this vignette locally.

    data(GRN_params_100)
    set.seed(42)

    options_ <- list(
      GRN = GRN_params_100,
      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_)

    ## CCI simulation is enabled.
    ## Get CIF...Done
    ## Get params...Done
    ## Simulating...50..
    ## Time spent: 2.28 mins

The `results$cell_meta` will contain the cell type information used in CCI. We can plot the cell spatial locations using `plot_cell_loc()`. The arrows indicate cell-cell interactions between two cells (for the first ligand-receptor pair).

    plot_cell_loc(results)

The cell locations are available in `results$cci_locs`.

    head(results$cci_locs)

    ##        x y
    ## cell1  6 6
    ## cell2  5 3
    ## cell3  5 7
    ## cell4  9 3
    ## cell5  9 4
    ## cell6 10 4

# Session Information

    sessionInfo()

    ## R version 4.4.0 beta (2024-04-15 r86425 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] dplyr_1.1.4      scMultiSim_1.0.0 knitr_1.46
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] utf8_1.2.4                  generics_0.1.3
    ##  [3] SparseArray_1.4.0           lattice_0.22-6
    ##  [5] digest_0.6.35               magrittr_2.0.3
    ##  [7] evaluate_0.23               grid_4.4.0
    ##  [9] iterators_1.0.14            foreach_1.5.2
    ## [11] jsonlite_1.8.8              Matrix_1.7-0
    ## [13] ape_5.8                     GenomeInfoDb_1.40.0
    ## [15] httr_1.4.7                  fansi_1.0.6
    ## [17] UCSC.utils_1.0.0            scales_1.3.0
    ## [19] codetools_0.2-20            abind_1.4-5
    ## [21] cli_3.6.2                   rlang_1.1.3
    ## [23] crayon_1.5.2                XVector_0.44.0
    ## [25] Biobase_2.64.0              commonmark_1.9.1
    ## [27] munsell_0.5.1               yaml_2.3.8
    ## [29] withr_3.0.0                 DelayedArray_0.30.0
    ## [31] Rtsne_0.17                  S4Arrays_1.4.0
    ## [33] tools_4.4.0                 parallel_4.4.0
    ## [35] zeallot_0.1.0               colorspace_2.1-0
    ## [37] ggplot2_3.5.1               GenomeInfoDbData_1.2.12
    ## [39] SummarizedExperiment_1.34.0 BiocGenerics_0.50.0
    ## [41] assertthat_0.2.1            mime_0.12
    ## [43] vctrs_0.6.5                 R6_2.5.1
    ## [45] matrixStats_1.3.0           stats4_4.4.0
    ## [47] lifecycle_1.0.4             zlibbioc_1.50.0
    ## [49] S4Vectors_0.42.0            IRanges_2.38.0
    ## [51] MASS_7.3-60.2               pkgconfig_2.0.3
    ## [53] pillar_1.9.0                gtable_0.3.5
    ## [55] glue_1.7.0                  Rcpp_1.0.12
    ## [57] highr_0.10                  xfun_0.43
    ## [59] tibble_3.2.1                GenomicRanges_1.56.0
    ## [61] tidyselect_1.2.1            KernelKnn_1.1.5
    ## [63] MatrixGenerics_1.16.0       farver_2.1.1
    ## [65] nlme_3.1-164                labeling_0.4.3
    ## [67] compiler_4.4.0              markdown_1.12